Sync docs updates to source repo by sdwheeler · Pull Request #2190 · PowerShell/PSScriptAnalyzer · GitHub
Skip to content

Sync docs updates to source repo - #2190

Closed
Sean Wheeler (sdwheeler) wants to merge 3 commits into
PowerShell:mainfrom
sdwheeler:sdw-w591525-rule-sync-docs-src
Closed

Sync docs updates to source repo#2190
Sean Wheeler (sdwheeler) wants to merge 3 commits into
PowerShell:mainfrom
sdwheeler:sdw-w591525-rule-sync-docs-src

Conversation

@sdwheeler

@sdwheeler Sean Wheeler (sdwheeler) commented Jun 25, 2026 •
edited
Loading

Copy link
Copy Markdown
Collaborator

Sync docs updates to source repo

  • Fixes AB#591525

This PR only touches the Rules docs. We recently did a mass update in the Docs repo to improve grammar, formatting, and structure. This PR syncs those changes back to the source repo.

Copilot AI review requested due to automatic review settings June 25, 2026 21:07
Copilot AI reviewed Jun 25, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Syncs rule documentation updates from the source repo into this repo’s docs/Rules content (AB#591525), primarily standardizing descriptions/headings and expanding examples/configuration guidance across many built-in rules.

Changes:

  • Standardizes front-matter metadata (description, ms.date) and normalizes terminology (for example, “Noncompliant/Compliant”).
  • Reworks/clarifies rule descriptions and guidance, often adding or restructuring examples and configuration/parameter sections.
  • Updates the rules index (docs/Rules/README.md) to a “default state”/“always enabled” model and adds link reference definitions.

Reviewed changes

Copilot reviewed 76 out of 76 changed files in this pull request and generated 11 comments.

Show a summary per file
File Description
docs/Rules/UseUTF8EncodingForHelpFile.md Clarifies rule description and adds compliant/noncompliant examples.
docs/Rules/UseUsingScopeModifierInNewRunspaces.md Clarifies runspace $using: guidance and trims/standardizes examples.
docs/Rules/UseToExportFieldsInManifest.md Rewords guidance and simplifies examples for manifest export fields.
docs/Rules/UseSupportsShouldProcess.md Improves explanation and standardizes example headings.
docs/Rules/UseSingularNouns.md Expands description and reorganizes configuration/parameter docs.
docs/Rules/UseSingleValueFromPipelineParameter.md Clarifies rule behavior, adds notes, and reframes suppression guidance.
docs/Rules/UseShouldProcessForStateChangingFunctions.md Expands description and standardizes “See also” section.
docs/Rules/UsePSCredentialType.md Clarifies guidance and standardizes example headings.
docs/Rules/UseProcessBlockForPipelineCommand.md Clarifies pipeline semantics; simplifies example sections.
docs/Rules/UseOutputTypeCorrectly.md Adds link refs and clarifies OutputType intent and behavior.
docs/Rules/UseLiteralInitializerForHashtable.md Clarifies case-sensitivity rationale and simplifies examples.
docs/Rules/UseDeclaredVarsMoreThanAssignments.md Rewords description and standardizes headings/phrasing.
docs/Rules/UseCorrectCasing.md Adds clearer “how to follow” guidance and adds examples.
docs/Rules/UseConstrainedLanguageMode.md Major restructure: adds consolidated restriction/remediation table and clearer configuration/parameters.
docs/Rules/UseConsistentWhitespace.md Adds examples and rewrites configuration/parameter descriptions.
docs/Rules/UseConsistentParametersKind.md Simplifies explanation and provides clearer compliant/noncompliant examples.
docs/Rules/UseConsistentParameterSetName.md Rewords guidance, adds notes, and standardizes parameter documentation.
docs/Rules/UseConsistentIndentation.md Adds examples and expands parameter documentation.
docs/Rules/UseCompatibleTypes.md Adds examples and expands configuration/parameter documentation.
docs/Rules/UseCompatibleSyntax.md Adds examples and expands configuration/parameter documentation.
docs/Rules/UseCompatibleCommands.md Adds examples and expands configuration/parameter documentation.
docs/Rules/UseCompatibleCmdlets.md Rewords description; clarifies compatibility identifiers and configuration snippet.
docs/Rules/UseCmdletCorrectly.md Rewords to focus on missing mandatory parameters and standardizes examples.
docs/Rules/UseBOMForUnicodeEncodedFile.md Adds examples and “See also” links; clarifies encoding guidance.
docs/Rules/UseApprovedVerbs.md Expands guidance and updates reference link to Learn.
docs/Rules/ShouldProcess.md Clarifies mismatches between SupportsShouldProcess and ShouldProcess usage.
docs/Rules/ReviewUnusedParameter.md Rewords description; adds “Configure rule” section.
docs/Rules/ReservedParams.md Rewords description and standardizes examples.
docs/Rules/ReservedCmdletChar.md Expands reserved character explanation and adds a meaning table.
docs/Rules/README.md Rebuilds rule index table with “Default state” and link references.
docs/Rules/ProvideCommentHelp.md Rewords description; moves configuration/parameters after examples.
docs/Rules/PossibleIncorrectUsageOfRedirectionOperator.md Rewords description; standardizes examples.
docs/Rules/PossibleIncorrectUsageOfAssignmentOperator.md Expands explanation and adds link references.
docs/Rules/PossibleIncorrectComparisonWithNull.md Adds deeper behavioral explanation and more illustrative examples.
docs/Rules/PlaceOpenBrace.md Adds examples and expands parameter documentation.
docs/Rules/PlaceCloseBrace.md Adds examples and expands parameter documentation.
docs/Rules/MissingModuleManifestField.md Rewords description and adds link reference to about_Module_Manifests.
docs/Rules/MisleadingBacktick.md Expands description and adds examples.
docs/Rules/DSCUseVerboseMessageInDSCResource.md Rewords and adds link reference.
docs/Rules/DSCUseIdenticalParametersForDSC.md Rewords DSC parameter consistency guidance and standardizes examples.
docs/Rules/DSCUseIdenticalMandatoryParametersForDSC.md Rewords; corrects code fence language and tightens examples.
docs/Rules/DSCStandardDSCFunctionsInResource.md Rewords and reorganizes examples for MOF/class-based resources.
docs/Rules/DSCReturnCorrectTypesForDSCFunctions.md Rewords and reorganizes examples for MOF/class-based resources.
docs/Rules/DSCDscTestsPresent.md Clarifies required test folder structure and wording.
docs/Rules/DSCDscExamplesPresent.md Clarifies required examples folder structure and wording.
docs/Rules/AvoidUsingWriteHost.md Rewords rationale, adds links, standardizes examples.
docs/Rules/AvoidUsingWMICmdlet.md Rewords rationale and fixes casing in example cmdlet names.
docs/Rules/AvoidUsingUsernameAndPasswordParams.md Rewords and standardizes examples.
docs/Rules/AvoidUsingPositionalParameters.md Adds examples; expands configuration/parameter documentation.
docs/Rules/AvoidUsingPlainTextForPassword.md Adds SecureString link reference and clarifies parameter naming.
docs/Rules/AvoidUsingInvokeExpression.md Rewords security rationale; standardizes examples.
docs/Rules/AvoidUsingEmptyCatchBlock.md Expands guidance on why empty catch blocks are problematic.
docs/Rules/AvoidUsingDoubleQuotesForConstantString.md Clarifies rule intent and lists exceptions.
docs/Rules/AvoidUsingDeprecatedManifestFields.md Rewords and clarifies deprecated field replacements.
docs/Rules/AvoidUsingConvertToSecureStringWithPlainText.md Expands guidance and adds links (SecureString/SecretStore).
docs/Rules/AvoidUsingComputerNameHardcoded.md Rewords, adds examples, and standardizes headings.
docs/Rules/AvoidUsingCmdletAliases.md Adds explicit compliant/noncompliant examples and config section.
docs/Rules/AvoidUsingBrokenHashAlgorithms.md Rewords and simplifies examples.
docs/Rules/AvoidUsingAllowUnencryptedAuthentication.md Rewords and adds link references.
docs/Rules/AvoidTrailingWhitespace.md Expands explanation and adds illustrative parser error output.
docs/Rules/AvoidShouldContinueWithoutForce.md Rewords and adds Learn link references.
docs/Rules/AvoidSemicolonsAsLineTerminators.md Adds examples and expands parameter documentation.
docs/Rules/AvoidReservedWordsAsFunctionNames.md Rewords and standardizes examples.
docs/Rules/AvoidOverwritingBuiltInCmdlets.md Adds examples and expands configuration/parameter documentation.
docs/Rules/AvoidNullOrEmptyHelpMessageAttribute.md Rewords and adds link reference; standardizes examples.
docs/Rules/AvoidMultipleTypeAttributes.md Rewords and standardizes examples.
docs/Rules/AvoidLongLines.md Adds examples and expands parameter documentation.
docs/Rules/AvoidInvokingEmptyMembers.md Expands explanation and adds Learn link reference.
docs/Rules/AvoidGlobalVars.md Reworks description and examples; adds scope-related link references.
docs/Rules/AvoidGlobalFunctions.md Rewords and adds Learn link reference.
docs/Rules/AvoidGlobalAliases.md Rewords and adds Learn link reference.
docs/Rules/AvoidExclaimOperator.md Rewords and reorganizes configuration/parameters.
docs/Rules/AvoidDefaultValueSwitchParameter.md Rewords and adds Learn link reference.
docs/Rules/AvoidDefaultValueForMandatoryParameter.md Rewords and standardizes examples.
docs/Rules/AvoidAssignmentToAutomaticVariable.md Rewords and adds Learn link reference.
docs/Rules/AlignAssignmentStatement.md Adds examples and expands parameter documentation.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/Rules/PossibleIncorrectUsageOfAssignmentOperator.md Outdated
Comment thread docs/Rules/ReviewUnusedParameter.md Outdated
Comment thread docs/Rules/UseCompatibleTypes.md Outdated
Comment thread docs/Rules/UseCompatibleCommands.md Outdated
Comment thread docs/Rules/UseToExportFieldsInManifest.md Outdated
Comment thread docs/Rules/README.md Outdated
Comment thread docs/Rules/UseCompatibleCmdlets.md Outdated
Comment thread docs/Rules/UseCompatibleCmdlets.md Outdated
Comment thread docs/Rules/AvoidOverwritingBuiltInCmdlets.md
Comment thread docs/Rules/MissingModuleManifestField.md Outdated
SeeminglyScience
Patrick Meinecke (SeeminglyScience) approved these changes Jun 29, 2026
View reviewed changes

@SeeminglyScience Patrick Meinecke (SeeminglyScience) left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks Sean Wheeler (@sdwheeler)!

@liamjpeters Liam Peters (liamjpeters) mentioned this pull request Jul 20, 2026
Open
6 tasks
@sdwheeler

Sean Wheeler (sdwheeler) commented Jul 23, 2026

Copy link
Copy Markdown
Collaborator Author

auto-merge was automatically disabled July 23, 2026 15:36

Pull request was closed

@sdwheeler
Sean Wheeler (sdwheeler) deleted the sdw-w591525-rule-sync-docs-src branch July 23, 2026 15:40
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot
Copilot review effort, defaults to Lite
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@andyleejordan Andy Jordan (andyleejordan) andyleejordan approved these changes
@SeeminglyScience Patrick Meinecke (SeeminglyScience) SeeminglyScience approved these changes
@michaeltlombardi Mikey Lombardi (He/Him) (michaeltlombardi) Awaiting requested review from michaeltlombardi michaeltlombardi is a code owner

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

4 participants

@sdwheeler @andyleejordan @SeeminglyScience