From 2a4e7d4c762b1fbaefbb3a785f3e7eb56b2c1c90 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 17 Sep 2026 07:33:46 -0500 Subject: [PATCH 1/3] Add rule template and documentation --- docs/rule-template-docs.md | 64 +++++++++++++++++++++++++ docs/rule-template.md | 95 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 159 insertions(+) create mode 100644 docs/rule-template-docs.md create mode 100644 docs/rule-template.md diff --git a/docs/rule-template-docs.md b/docs/rule-template-docs.md new file mode 100644 index 000000000..43e4f8a0b --- /dev/null +++ b/docs/rule-template-docs.md @@ -0,0 +1,64 @@ +# PSScriptAnalyzer rule template guidance + +The [rule-template.md](rule-template.md) file illustrates the structure of the PSScriptAnalyzer rule +articles. Replace all placeholder text, then remove optional sections that don't apply. + +## Required content + +Every rule article starts with these YAML frontmatter fields: + +- `description` +- `ms.date` +- `ms.topic: reference` +- `title` + +Place the H1, severity line, and default-state line immediately after the frontmatter. Follow them +with `## Description`, which explains the diagnostic, why it matters, and the preferred alternative. + +Each rule must have an `## Example` section. Each example includes a `### Noncompliant` code block +followed by a `### Compliant` alternative. Give each scenario an H3 heading and use H4 headings for +its noncompliant and compliant code pair. + +Every rule article includes `## Configure rule` after its example or examples. For a configurable +rule, include a `Rules` hashtable entry. For an always-enabled or otherwise nonconfigurable rule, +use the following text. + +```markdown +This rule is always enabled and isn't configurable. Use one of the following methods to avoid using +this rule: + +- Create a custom rule configuration file to include only the rules you want or exclude the rules + you don't want. +- Add the appropriate rule suppression attributes to your code to suppress the rule for specific + code blocks. For more information, see the _Suppressing rules_ section of + [Using PSScriptAnalyzer][02]. +``` + +## Optional sections + +Use an additional H2 explanatory section between `## Description` and the example when readers need +context before reviewing the code. Existing articles use this space for compatibility profile +information, reference tables, supported values, and remediation guidance. For examples, see the +following articles. + +- [AvoidUsingConvertToSecureStringWithPlainText](Rules/AvoidUsingConvertToSecureStringWithPlainText.md) +- [UseConsistentParameterSetName](Rules/UseConsistentParameterSetName.md) +- [UseConstrainedLanguageMode](Rules/UseConstrainedLanguageMode.md) + +When the rule is configurable, include `### Parameter` for each setting after `## Configure rule`. +Use an H3 heading for each setting and document what it controls, accepted values, and its default +value. + +Include `## Suppression` after the `## Configure rule` section only when the rule needs specific +suppression syntax or examples. Otherwise, link readers to the general _Suppressing rules_ guidance +from **Configure rule**. + +In the `## Further reading` section, provide links to additional resources that help readers +understand the rule, its context, or related topics. + +## Final checks + +- Include `## Configure rule` for every rule article. +- Include `### Parameters` only for configurable settings that need individual documentation. +- Pair noncompliant code with a practical compliant alternative. +- Remove all unused optional headings, placeholder text, and link definitions. diff --git a/docs/rule-template.md b/docs/rule-template.md new file mode 100644 index 000000000..52256db51 --- /dev/null +++ b/docs/rule-template.md @@ -0,0 +1,95 @@ +--- +description: {{Brief description of the rule behavior}} +ms.date: {{MM/DD/YYYY}} +ms.topic: reference +title: {{RuleName}} +--- +# {{RuleName}} + +**Severity Level: {{Error | Warning | Information}}** + +**Default state: {{Enabled | Disabled | Always enabled}}** + +## Description + +{{Explain what the rule detects, why the pattern is a problem, and the recommended +practice.}} + +## {{Optional explanatory topic}} + +{{Add a table, supported values, compatibility information, or remediation guidance +when the rule needs context before its examples. Remove this section when it doesn't +apply.}} + +## Example + +### Noncompliant + +```powershell +{{Code that produces the diagnostic}} +``` + +### Compliant + +```powershell +{{Equivalent code that doesn't produce the diagnostic}} +``` + +## Examples + +### {{Scenario name}} + +#### Noncompliant + +```powershell +{{Code that produces the diagnostic for this scenario}} +``` + +#### Compliant + +```powershell +{{Equivalent compliant code for this scenario}} +``` + +## Configure rule + +{{For a configurable rule, use the following configuration and include the Parameters +section. For a nonconfigurable rule, replace this text with an explanation that the +rule isn't configurable and describe available exclusion or suppression options.}} + +```powershell +@{ + Rules = @{ + PS{{RuleName}} = @{ + Enable = $true + {SettingName} = {Value} + } + } +} +``` + +## Parameters + +### {{SettingName}} + +{{Explain what the setting controls, its accepted value type or values, and its +default value. Add another H3 section for each setting. Remove this section for a +nonconfigurable rule.}} + +## Suppression + +{{Explain any rule-specific suppression syntax or examples. Remove this section when +general suppression guidance linked from Configure rule is enough.}} + +```powershell +[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PS{{RuleName}}', '')] +``` + +## Further reading + +- {{[Article title][01]}} +- [Using PSScriptAnalyzer][02] + + +[01]: {{URL or absolute path}} +[02]: ../using-scriptanalyzer.md From 523c7b456e91758ea75c9bcacd717b670eff4c32 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 17 Sep 2026 07:45:02 -0500 Subject: [PATCH 2/3] Correct H-levels for Parameters --- docs/rule-template-docs.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/rule-template-docs.md b/docs/rule-template-docs.md index 43e4f8a0b..779a426f5 100644 --- a/docs/rule-template-docs.md +++ b/docs/rule-template-docs.md @@ -45,13 +45,12 @@ following articles. - [UseConsistentParameterSetName](Rules/UseConsistentParameterSetName.md) - [UseConstrainedLanguageMode](Rules/UseConstrainedLanguageMode.md) -When the rule is configurable, include `### Parameter` for each setting after `## Configure rule`. -Use an H3 heading for each setting and document what it controls, accepted values, and its default -value. +When the rule is configurable, include `## Parameters` section after `## Configure rule`. Use an H3 +heading for each setting and document what it controls, accepted values, and its default value. -Include `## Suppression` after the `## Configure rule` section only when the rule needs specific -suppression syntax or examples. Otherwise, link readers to the general _Suppressing rules_ guidance -from **Configure rule**. +After the `## Configure rule` and any parameter sections, include a `## Suppression` section only +when the rule needs specific suppression syntax or examples. Otherwise, link readers to the general +_Suppressing rules_ guidance from **Configure rule**. In the `## Further reading` section, provide links to additional resources that help readers understand the rule, its context, or related topics. From d6b3b478ce26e1e7ccd16081707d82522ea00342 Mon Sep 17 00:00:00 2001 From: Sean Wheeler Date: Thu, 17 Sep 2026 10:08:39 -0500 Subject: [PATCH 3/3] Remove duplicated examples --- docs/rule-template.md | 22 +++++----------------- 1 file changed, 5 insertions(+), 17 deletions(-) diff --git a/docs/rule-template.md b/docs/rule-template.md index 52256db51..0dd11c7d4 100644 --- a/docs/rule-template.md +++ b/docs/rule-template.md @@ -21,34 +21,22 @@ practice.}} when the rule needs context before its examples. Remove this section when it doesn't apply.}} -## Example +## Examples ### Noncompliant +{{Describe the scenario as necessary.}} + ```powershell {{Code that produces the diagnostic}} ``` ### Compliant -```powershell -{{Equivalent code that doesn't produce the diagnostic}} -``` - -## Examples - -### {{Scenario name}} - -#### Noncompliant +{{Describe the scenario as necessary.}} ```powershell -{{Code that produces the diagnostic for this scenario}} -``` - -#### Compliant - -```powershell -{{Equivalent compliant code for this scenario}} +{{Equivalent code that doesn't produce the diagnostic}} ``` ## Configure rule