Refactor guidelines documentation for clarity and consistency across multiple files

Author: johlju

.github/instructions/SqlServerDsc-guidelines.instructions.md

@@ -1,97 +1,31 @@
 ---
-description: Guidelines for working with the SqlServerDsc PowerShell module.
+description: SqlServerDsc-specific guidelines for AI development.
 applyTo: "**"
 ---
 
-# SqlServerDsc Module Guidelines
+# SqlServerDsc Guidelines
 
-This file contains specific guidelines for working with the SqlServerDsc PowerShell module project.
+## Naming
+- Public commands: `{Verb}-SqlDsc{Noun}` format
 
-## Public Command Naming
+## Resources
+- Database Engine resources: inherit `SqlResourceBase`
+- `SqlResourceBase` provides: `InstanceName`, `ServerName`, `Credential`, `Reasons`, `GetServerObject()`
 
-All public command names must have the noun prefixed with 'SqlDsc', e.g.
-{Verb}-SqlDsc{Noun}.
+## SQL Server Interaction
+- Always prefer SMO over T-SQL
+- Unit tests: Use SMO stub types from SMO.cs, never mock SMO types
+- Run tests in new session after changing SMO.cs
 
-## DSC Resource Base Classes
+## Testing CI Environment
+- Database Engine: instance `DSCSQLTEST`
+- Reporting Services: instance `SSRS`
+- Power BI Report Server: instance `PBIRS`
 
-### SqlResourceBase
-
-Derived resources should inherit `SqlResourceBase` (which inherits `ResourceBase`)
-when they need to connect to the SQL Server Database Engine.
-
-`SqlResourceBase` provides the DSC properties `InstanceName`, `ServerName`,
-`Credential`, and `Reasons`, and the `GetServerObject` method used to connect
-to a SQL Server Database Engine instance.
-
-## SQL Server
-
-### SQL Server Management Objects (SMO)
-
-When developing commands, private functions, class-based resources, or making
-modifications to existing functionality, always prefer using SQL Server
-Management Objects (SMO) as the primary method for interacting with SQL Server.
-Only use T-SQL when it is not possible to achieve the desired functionality
-with SMO.
-
-Do not mock SMO types in unit tests, use SMO stub types from SMO.cs.
-Always run tests in a new session after changing stub types in SMO.cs.
-
-## Integration Testing Environment
-
-### SQL Server Database Engine
-
-Integration tests that depend on an SQL Server Database Engine instance
-will run in environments in CI/CD pipelines where an instance DSCSQLTEST
-is already installed. Each environment will have SQL Server 2016, 2017,
-2019, or 2022.
-
-### SQL Server Reporting Services
-
-Integration tests that depend on an SQL Server Reporting Services instance
-will run in environments in CI/CD pipelines where an instance SSRS is already
-installed. Each environment will have SQL Server Reporting Services 2016,
-2017, 2019, or 2022.
-
-### Power BI Report Server
-
-Integration tests that depend on a Power BI Report Server instance
-will run in one environment in CI/CD pipeline where an instance PBIRS is
-already installed. The environment will always have the latest Power BI
-Report Server version.
-
-## Integration Test Configuration
-
-Integration test script files for public commands must be added to a group
-within the 'Integration_Test_Commands_SqlServer' stage in ./azure-pipelines.yml.
-Choose the appropriate group number based on the command’s dependencies
-(for example, commands that require Database Engine should be in Group 2
-or later, after the Database Engine installation tests).
-
-For integration testing commands, use the information in
-tests/Integration/Commands/README.md, which describes the testing environment,
-including available instances, users, credentials, and other configuration
-details.
-
-## Testing
-
-### Unit Tests
-
-For every unit test the following must be added to the top level `BeforeAll`- and `AfterAll`-blocks in the test file:
-
-```powershell
-BeforeAll {
-    $env:SqlServerDscCI = $true
-}
-
-AfterAll {
-    Remove-Item -Path 'env:SqlServerDscCI'
-}
-```
-
-### Integration tests
-
-When using command `Connect-SqlDscDatabaseEngine` always use `Disconnect-SqlDscDatabaseEngine` when connection is no longer needed.
-
-Instances and credentials to use in integration tests are available for:
-- Commands: tests/Integration/Commands/README.md
-- Resources: tests/Integration/Resources/README.md
+## Test Requirements
+- Unit tests: Add `$env:SqlServerDscCI = $true` in `BeforeAll`, remove in `AfterAll`
+- Integration tests: Use `Disconnect-SqlDscDatabaseEngine` after `Connect-SqlDscDatabaseEngine`
+- Test config: tests/Integration/Commands/README.md and tests/Integration/Resources/README.md
+- Integration test script files must be added to a group
+within the test stage in ./azure-pipelines.yml.
+- Choose the appropriate group number based on the required dependencies

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

@@ -3,14 +3,11 @@ description: Guidelines for maintaining a clear and consistent changelog.
 applyTo: "CHANGELOG.md"
 ---
 
-# Changelog Style Guidelines
-
-Always update the Unreleased section in CHANGELOG.md with every change.
-Use the Keep a Changelog format and provide concrete release notes that
-describe the main changes. Include new commands, private functions,
-class-based resources, or significant modifications to existing
-functionality.
-
-Reference related issues using the format #<issue_number>.
-
-Do not leave empty lines between list items in the same section.
+# Changelog Guidelines
+
+- 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>
+- 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-class-resource.instructions.md

@@ -3,100 +3,65 @@ description: Guidelines for implementing Desired State Configuration (DSC) class
 applyTo: "source/[cC]lasses/**/*.ps1"
 ---
 
-# Desired State Configuration (DSC) class-based resource Style Guidelines
+# DSC Class-Based Resource Guidelines
 
-Only use this instruction when the class is decorated with `[DscResource(...)]`.
+**Applies to:** Classes with `[DscResource(...)]` decoration only.
 
-Each DSC class-based resource must have its own script file named after the
-resource class (with the .ps1 extension). Place these files in source/Classes.
+## Requirements
+- File: `source/Classes/{ResourceName}.ps1`
+- Decoration: `[DscResource(RunAsCredential = 'Optional')]` (replace with `'Mandatory'` if required)
+- Inheritance: Must inherit `ResourceBase` (part of module DscResource.Base)
+- `$this.localizedData` hashtable auto-populated by `ResourceBase` from localization file
 
-## Parent classes
-
-### ResourceBase
-
-A derived class should inherit the parent class `ResourceBase`.
-
-The parent class `ResourceBase` will set up `$this.localizedData` and provide
-logic to compare the desired state against the current state. To get the
-current state it will call the overridable method `GetCurrentState`. If not
-in desired state it will call the overridable method `Modify`. It will also
-call the overridable methods `AssertProperties` and `NormalizeProperties` to
-validate and normalize the provided values of the desired state.
-
-## Derived class
-
-The derived class should use the decoration `[DscResource(RunAsCredential = 'Optional')]`.
-
-The derived class should always inherit from a parent class.
-
-The derived class should override the methods `Get`, `Test`, `Set`, `GetCurrentState`,
-`Modify`, `AssertProperties`, and `NormalizeProperties` using this pattern
-(and replace MyResourceName with actual resource name):
+## Required Method Pattern
 
 ```powershell
 [MyResourceName] Get()
 {
-    # Call the base method to return the properties.
-    return ([ResourceBase] $this).Get()
+    $currentState = ([ResourceBase] $this).Get()
+
+    # If needed, post-processing based on returned current state before returning to user
+
+    return $currentState
 }
 
 [System.Boolean] Test()
 {
-    # Call the base method to test all of the properties that should be enforced.
-    return ([ResourceBase] $this).Test()
+    $inDesiredState = ([ResourceBase] $this).Test()
+
+    # If needed, post-processing based on returned test result before returning to user
+
+    return $inDesiredState
 }
 
 [void] Set()
 {
-    # Call the base method to enforce the properties.
     ([ResourceBase] $this).Set()
+
+    # If needed, additional state changes that could not be handled by Modify()
 }
 
-<#
-    Base method Get() calls this method to get the current state as a hashtable.
-    The parameter properties will contain the key properties.
-#>
 hidden [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties)
 {
-    # Add code to return the current state as a hashtable.
+    # Return current state as hashtable
+    # Variable $properties contains the key properties (key-value pairs).
 }
 
-<#
-    Base method Set() calls this method with the properties that are not in
-    the desired state and must be enforced. It is not called if all properties
-    are in the desired state. The $properties variable contains only the
-    properties that are not in the desired state.
-#>
 hidden [void] Modify([System.Collections.Hashtable] $properties)
 {
-    # Add code to set the desired state based on the properties that are not in desired state.
+    # Set desired state for non-compliant properties only
+    # Variable $properties contains the properties (key-value pairs) that are not in desired state.
 }
 
-<#
-    Base method Assert() calls this method with the properties that were assigned
-    a value.
-#>
 hidden [void] AssertProperties([System.Collections.Hashtable] $properties)
 {
-    # Add code to validate class properties that the user passed values to.
+    # Validate user-provided properties
+    # Variable $properties contains properties user assigned values.
 }
 
-<#
-    Base method Normalize() calls this method with the properties that were assigned
-    a value.
-#>
 hidden [void] NormalizeProperties([System.Collections.Hashtable] $properties)
 {
-    # Add code to normalize class properties that the user passed values to.
+    # Normalize user-provided properties
+    # Variable $properties contains properties user assigned values.
 }
 ```
-
-## Localization
-
-For class-based resources, add a localized strings file in the folder
-source/en-US. Name the file exactly after the resource class with the suffix
-`.strings.psd1`.
-Localized string key names should use underscores as word separators if the key
-name has more than one word. Always assume that all localized string keys for a
-class-based resource have already been assigned to `$this.localizedData` by the
-parent class.

.github/instructions/dsc-community-style-guidelines-integration-tests.instructions.md

@@ -1,25 +1,19 @@
 ---
 description: Guidelines for implementing integration tests for commands.
-applyTo: "**/*.[iI]ntegration.[tT]ests.ps1"
+applyTo: "tests/[iI]ntegration/**/*.[iI]ntegration.[tT]ests.ps1"
 ---
 
-# Command Integration Tests Style Guidelines
+# Integration Tests Guidelines
 
-Every public command must have an integration test. Integration tests must
-never mock any command; they run in a real environment. Place all integration
-tests in the folder `tests/Integration/Commands`. Name each test after the
-public command it verifies and suffix it with `.Integration.Tests.ps1`.
+## Requirements
+- Location Commands: `tests/Integration/Commands/{CommandName}.Integration.Tests.ps1`
+- Location Resources: `tests/Integration/Resources/{ResourceName}.Integration.Tests.ps1`
+- No mocking - real environment only
+- Cover all scenarios and code paths
+- Use `Get-ComputerName` for computer names in CI
+- Only run integration tests in CI unless explicitly instructed.
 
-Write tests to cover all scenarios and code paths, including common cases
-and edge cases. Tests should exercise the command in a real environment,
-using real resources and dependencies.
-
-When integration tests need the computer name in CI, use [`Get-ComputerName`](https://github.com/dsccommunity/DscResource.Common/wiki/Get%E2%80%91ComputerName).
-This helper is provided in the build pipeline and is not required locally.
-
-All integration tests must use the code block below before the first
-`Describe` block. The following code sets up the integration test
-environment and ensures the module under test is available:
+## Required Setup Block
 
 ```powershell
 [System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Suppressing this rule because Script Analyzer does not understand Pester syntax.')]
@@ -53,9 +47,3 @@ BeforeAll {
     Import-Module -Name $script:dscModuleName -Force -ErrorAction 'Stop'
 }
 ```
-
-The DscResource.Test module is used by the pipeline and its commands are
-typically not used when testing public functions, private functions, or
-class-based resources.
-
-Do not run integration tests locally unless explicitly instructed.

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

@@ -3,45 +3,34 @@ description: Guidelines for implementing localization.
 applyTo: "source/**/*.ps1"
 ---
 
-# Localization Style Guidelines
+# Localization Guidelines
 
-For public commands and private functions, you should always add all localized
-strings in the source/en-US/SqlServerDsc.strings.psd1 file, reusing the
-same pattern for new string keys. Localized string key names should always
-be prefixed with the function name but use underscores as word separators.
-Always assume that all localized string keys have already been assigned to
-the variable $script:localizedData.
+## Requirements
+- Localize all Write-Debug, Write-Verbose, Write-Error, Write-Warning and $PSCmdlet.ThrowTerminatingError() messages
+- Use localized string keys, not hardcoded strings
+- Assume `$script:localizedData` is available
 
-All message strings for Write-Debug, Write-Verbose, Write-Error, Write-Warning,
-and other error messages in classes, public commands, and private functions should
-be localized using localized string keys.
+## String Files
+- Commands/functions: `source/en-US/SqlServerDsc.strings.psd1`
+- Class resources: `source/en-US/{ResourceClassName}.strings.psd1`
 
-## String File Locations
+## Key Naming
+- Format: `FunctionName_Description` (underscore separators)
+- Example: `Get_SqlDscDatabase_ConnectingToDatabase`
 
-- Public commands and private functions: source/en-US/SqlServerDsc.strings.psd1
-- Class-based resources: source/en-US/<ResourceClassName>.strings.psd1
-
-## String File Format
+## String Format
 ```powershell
-# Localized resources for <ResourceName>
 ConvertFrom-StringData @'
     KeyName = Message with {0} placeholder. (PREFIX0001)
 '@
 ```
 
-## String ID Format
-Use unique IDs: `(PREFIX####)`
-- PREFIX: First letter of each word in resource name or function name
-- ####: Sequential number starting 0001
-- Examples: SqlSetup → SS0001, SqlAGDatabase → SAGD0001, Get-SqlDscSqlDatabase → GSDSD0001
+## String IDs
+- Format: `(PREFIX####)`
+- PREFIX: First letter of each word in class or function name (SqlSetup → SS, Get-SqlDscDatabase → GSDD)
+- Number: Sequential from 0001
 
-## Usage Patterns
+## Usage
 ```powershell
-# Verbose/Warning messages
-Write-Verbose -Message ($script:localizedData.KeyName -f $value)
-Write-Warning -Message ($script:localizedData.KeyName -f $value)
-
-# Error messages
-New-InvalidOperationException -Message ($script:localizedData.KeyName -f $value1, $value2)
-New-InvalidOperationException -ErrorRecord $_ -Message ($script:localizedData.KeyName -f $value1)
+Write-Verbose -Message ($script:localizedData.KeyName -f $value1)
 ```