Skip to content

Commit c0d28b4

Browse files
authored
Update contributing docs (Azure#2969)
1 parent 5b46232 commit c0d28b4

File tree

1 file changed

+15
-1
lines changed

1 file changed

+15
-1
lines changed

CONTRIBUTING.md

+15-1
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,7 @@ Each rule **must** meet the following requirements:
116116
- The rule name must not be longer than 35 characters.
117117
- Use a unique `Ref` following the format `AZR-nnnnnnn`.
118118
Where `nnnnnn` is a sequential number from `000001`.
119+
See [how to get the next unique rule ref](#how-to-get-the-next-unique-rule-ref).
119120
- Have documentation and unit tests.
120121
- Have a `release` tag either `GA` or `preview`. e.g. `-Tag @{ release = 'GA' }`
121122
- Rules are marked as `GA` if they relate to generally available Azure features.
@@ -125,13 +126,16 @@ Each rule **must** meet the following requirements:
125126
- The rule set tag identifies the quarter that the rule was first released.
126127
- This is used to include rules in quarterly baselines.
127128
- New rules are included in the next quarterly baseline. i.e. (YYYY_03, YYYY_06, YYYY_09, YYYY_12)
129+
- Have a `Azure.WAF/pillar` tag identifying the primary WAF pillar the rule aligns to.
130+
e.g. `-Tag @{ release = 'GA'; ruleSet = '2020_09'; 'Azure.WAF/pillar' = 'Reliability' }`
131+
- If more then one pillar is applicable, the `Azure.WAF/additionalPillars` label can be added on rules.
128132
- Include an inline `Synopsis: ` comment above each rule.
129133

130134
For example:
131135

132136
```powershell
133137
# Synopsis: Consider configuring a managed identity for each API Management instance.
134-
Rule 'Azure.APIM.ManagedIdentity' -Type 'Microsoft.ApiManagement/service' -Tag @{ release = 'GA'; ruleSet = '2020_06' } {
138+
Rule 'Azure.APIM.ManagedIdentity' -Type 'Microsoft.ApiManagement/service' -Tag @{ release = 'GA'; ruleSet = '2020_06'; 'Azure.WAF/pillar' = 'Security' } {
135139
$Assert.In($TargetObject, 'Identity.Type', @('SystemAssigned', 'UserAssigned'))
136140
}
137141
```
@@ -146,6 +150,7 @@ metadata:
146150
tags:
147151
release: 'GA'
148152
ruleSet: '2020_06'
153+
Azure.WAF/pillar: Security
149154
spec:
150155
type:
151156
- Microsoft.ApiManagement/service
@@ -164,6 +169,15 @@ spec:
164169
- Use `-Type` over `-If` pre-conditions when possible.
165170
Both may be required in some cases.
166171

172+
### How to get the next unique rule ref?
173+
174+
To get the next unique rule ref:
175+
176+
1. Scroll to the bottom of this [reference](https://azure.github.io/PSRule.Rules.Azure/en/rules/) page.
177+
2. Choose the next available ref number sequence.
178+
3. Be aware of any existing open PRs that add rules, and choose the next available ref number sequence.
179+
If both PRs choose the same rule ref the CI build will fail after one is merged.
180+
167181
### Adding rule configuration options
168182

169183
For some rules, adding configuration options to allow customization may be helpful.

0 commit comments

Comments
 (0)