Create Rule S6956: The properties and elements inside a template shou…

…ld appear in the recommended order

rules/S6956/azureresourcemanager/metadata.json

@@ -1,24 +1,23 @@
 {
-  "title": "FIXME",
+  "title": "The properties and elements inside a template should appear in the recommended order",
   "type": "CODE_SMELL",
   "status": "ready",
   "remediation": {
     "func": "Constant\/Issue",
     "constantCost": "5min"
   },
   "tags": [
+    "convention"
   ],
-  "defaultSeverity": "Major",
+  "defaultSeverity": "Minor",
   "ruleSpecification": "RSPEC-6956",
   "sqKey": "S6956",
   "scope": "All",
   "defaultQualityProfiles": ["Sonar way"],
   "quickfix": "unknown",
   "code": {
     "impacts": {
-      "MAINTAINABILITY": "HIGH",
-      "RELIABILITY": "MEDIUM",
-      "SECURITY": "LOW"
+      "MAINTAINABILITY": "LOW"
     },
     "attribute": "CONVENTIONAL"
   }

rules/S6956/azureresourcemanager/rule.adoc

@@ -1,44 +1,151 @@
-FIXME: add a description
+== Why is this an issue?
 
-// If you want to factorize the description uncomment the following line and create the file.
-//include::../description.adoc[]
+According to the best practices defined by Azure, a consistent order of properties and elements in a templates is recommended.
+This makes it easier to read and understand the template.
 
-== Why is this an issue?
+Not following this convention has no technical impact,
+but will reduce the template's readability because most developers are used to the standard order.
 
-FIXME: remove the unused optional headers (that are commented out)
+Sorting the resources according to deployment order is recommended as well, as this will convey the intent of the orchestration.
 
-//=== What is the potential impact?
+== How to fix it in ARM Templates
 
-== How to fix it
-//== How to fix it in FRAMEWORK NAME
+*Recommended order of the top-level template properties*:
 
-=== Code examples
+[source,json]
+----
+{
+  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/...",
+  "contentVersion": "1.0.0.0",
+  "apiProfile": "...",
+  "parameters": {},
+  "functions": {},
+  "variables": {},
+  "resources": [],
+  "outputs": {}
+}
+----
 
-==== Noncompliant code example
+*Recommended order of the resource properties*:
 
-[source,text,diff-id=1,diff-type=noncompliant]
+[source,json]
 ----
-FIXME
+{
+  "resources": [
+    {
+      "comments": "if any",
+      "condition": true,
+      "scope": "% parent scope %",
+      "type": "Microsoft.Compute/virtualMachines",
+      "apiVersion": "2023-09-01",
+      "name": "resourceName",
+      "location": "[parameters('location')]",
+      "zones": [],
+      "sku": {},
+      "kind": "",
+      "scale": "",
+      "plan": {},
+      "identity": {},
+      "copy": {
+        "name": "vmLoop",
+        "count": "[parameters('numberOfVMs')]"
+      },
+      "dependsOn": [
+        "nicLoop"
+      ],
+      "tags": {},
+      "properties": {}
+    }
+  ]
+}
 ----
 
-==== Compliant solution
+Any other properties or elements not listed here should be placed before the `properties` object for the resource.
 
-[source,text,diff-id=1,diff-type=compliant]
+== How to fix it in Bicep
+
+*Recommended order of the top-level template properties*:
+
+[source,bicep]
 ----
-FIXME
+targetScope '...'
+metadata '...'
+param '...'
+var '...'
+resource // (existing resources collected together)
+resource/module // (new resources)
+output '...'
 ----
 
-//=== How does this work?
+*Recommended order of the resource properties*:
+
+[source,bicep]
+----
+@description
+@batchSize
+resource resourceName
+  parent
+  scope
+  name
+  location/extendedLocation
+  zones
+  sku
+  kind
+  scale
+  plan
+  identity
+  dependsOn
+  tags
+  properties
+----
+
+Any other decorated not listed here should be placed before the `resource` object and after the other decorators.
+Any other properties or elements not listed here should be placed before the `properties` object for the resource.
+
+== Resources
+=== Documentation
+
+* Azure quickstart templates best practices - https://github.com/Azure/azure-quickstart-templates/blob/master/1-CONTRIBUTION-GUIDE/best-practices.md#sort-order-of-properties[Sort order of properties]
+* Microsoft Azure - Understand the structure and syntax of ARM templates - https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax#template-format[Template Format]
+* Microsoft Azure - Understand the structure and syntax of Bicep files - https://learn.microsoft.com/en-us/azure/azure-resource-manager/templates/syntax#template-format[Bicep Format]
+
+ifdef::env-github,rspecator-view[]
+
+'''
+== Implementation Specification
+(visible only on this page)
+
+=== Message
+
+In case of wrong order of top-level elements:
+
+* Primary Issue Message: Reorder the properties and elements to match the recommended order.
+This `<nameOfTheWronglyOrderedKey>` object should be located after the `<nameOfTheKeyThatShouldComeBeforeIt>` object.
+* Secondary Issue Message: This `<nameOfTheWronglyOrderedKey>` object should be located after the `<nameOfTheKeyThatShouldComeBeforeIt>` object.
+
+In case of wrong order in a resource:
+
+* Primary Issue Message: Reorder the properties and elements inside the resource to match the recommended order.
+This `<nameOfTheWronglyOrderedKey>` object should be located after the `<nameOfTheKeyThatShouldComeBeforeIt>` object.
+* Secondary Issue Message: This `<nameOfTheWronglyOrderedKey>` object should be located after the `<nameOfTheKeyThatShouldComeBeforeIt>` object.
+
+
+
+=== Highlighting
+
+In general, we want to highlight all the keys of elements that are in the wrong order.
+
+For wrong order in top-level elements:
+
+* The first wrongly ordered element should be highlighted as primary issue and the others as secondary locations.
 
-//=== Pitfalls
+For wrong order in a resource:
 
-//=== Going the extra mile
+* The name of the resource / key of the resource should be highlighted as a primary issues.
+All the wrongly ordered elements should be highlighted as secondary locations.
 
+'''
+== Comments And Links
+(visible only on this page)
 
-//== Resources
-//=== Documentation
-//=== Articles & blog posts
-//=== Conference presentations
-//=== Standards
-//=== External coding guidelines
-//=== Benchmarks
+endif::env-github,rspecator-view[]

rules/S6956/metadata.json

@@ -1,2 +1,3 @@
 {
+
 }