Improve markdown and changelog instructions for clarity and consistency (#2146)

Author: johlju

.github/instructions/dsc-community-style-guidelines-changelog.instructions.md

@@ -7,7 +7,7 @@ applyTo: "CHANGELOG.md"
 
 - Always update the Unreleased section in CHANGELOG.md
 - Use Keep a Changelog format
-- Describe main changes as concise release notes
-- Reference issues using format #<issue_number>
+- Describe notable changes briefly, ≤2 items per change type
+- Reference issues using format [#<issue_number>](https://github.com/<owner>/<repo>/issues/<issue_number>)
 - No empty lines between list items in same section
 - Do not add item if there are already an existing item for the same change

.github/instructions/dsc-community-style-guidelines-markdown.instructions.md

@@ -8,5 +8,13 @@ applyTo: "**/*.md"
 - Wrap lines at word boundaries when over 80 characters (except tables/code blocks)
 - Use 2 spaces for indentation
 - Use '1.' for all items in ordered lists (1/1/1 numbering style)
-- Surround fenced code blocks with blank lines
 - Disable `MD013` rule by adding a comment for tables/code blocks exceeding 80 characters
+- Empty lines required before/after code blocks and headings (except before line 1)
+- Code blocks must specify language identifiers
+
+## Text Formatting
+
+- Parameters: **bold**
+- Values/literals: `inline code`
+- Resource/module/product names: _italic_
+- Commands/files/paths: `inline code`

.github/instructions/dsc-community-style-guidelines-pester.instructions.md

@@ -47,3 +47,5 @@ applyTo: "**/*.[Tt]ests.ps1"
 - Keep results and assertions in same `It` block
 - Cover all scenarios and code paths
 - Use `BeforeEach` and `AfterEach` sparingly
+- Avoid try-catch-finally for cleanup, use `AfterAll` or `AfterEach`
+- Avoid unnecessary remove/recreate cycles

.github/instructions/dsc-community-style-guidelines-powershell.instructions.md

@@ -151,7 +151,7 @@ function Get-Something
 - Use `PSCredential` for credentials
 - Avoid hardcoded computer names, use cross-platform [`Get-ComputerName`](https://github.com/dsccommunity/DscResource.Common/wiki/Get%E2%80%91ComputerName) instead of `$env:COMPUTERNAME`
 - Place `$null` on left side of comparisons
-- Avoid empty catch blocks (use `-ErrorAction SilentlyContinue`)
+- Avoid empty catch blocks (use `-ErrorAction Ignore`)
 - Don't use `Invoke-Expression` (use `&` operator)
 - Use CIM commands instead of WMI commands
 
@@ -165,7 +165,7 @@ function Get-Something
 
 ## File Rules
 
-- End files with newline
+- End files with a blank line
 - Use CR+LF line endings
 - Maximum two consecutive newlines
 

CHANGELOG.md

@@ -91,6 +91,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   - Improved documentation with optimized analysis workflow description.
 - DSC community style guidelines
   - Added requirement to follow guidelines over existing code patterns.
+- Improved markdown and changelog instructions.
 
 ## [17.1.0] - 2025-05-22