DSC Community guidelines instructions (#2128)

Author: johlju

.github/copilot-instructions.md

@@ -0,0 +1,31 @@
+---
+description: SqlServerDsc-specific guidelines for AI development.
+applyTo: "**"
+---
+
+# SqlServerDsc Guidelines
+
+## Naming
+- Public commands: `{Verb}-SqlDsc{Noun}` format
+
+## Resources
+- Database Engine resources: inherit `SqlResourceBase`
+- `SqlResourceBase` provides: `InstanceName`, `ServerName`, `Credential`, `Reasons`, `GetServerObject()`
+
+## 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
+
+## Testing CI Environment
+- Database Engine: instance `DSCSQLTEST`
+- Reporting Services: instance `SSRS`
+- Power BI Report Server: instance `PBIRS`
+
+## 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/SqlServerDsc-guidelines.instructions.md

@@ -0,0 +1,13 @@
+---
+description: Guidelines for maintaining a clear and consistent changelog.
+applyTo: "CHANGELOG.md"
+---
+
+# 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-changelog.instructions.md

@@ -0,0 +1,67 @@
+---
+description: Guidelines for implementing Desired State Configuration (DSC) class-based resources.
+applyTo: "source/[cC]lasses/**/*.ps1"
+---
+
+# DSC Class-Based Resource Guidelines
+
+**Applies to:** Classes with `[DscResource(...)]` decoration only.
+
+## 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
+
+## Required Method Pattern
+
+```powershell
+[MyResourceName] Get()
+{
+    $currentState = ([ResourceBase] $this).Get()
+
+    # If needed, post-processing based on returned current state before returning to user
+
+    return $currentState
+}
+
+[System.Boolean] Test()
+{
+    $inDesiredState = ([ResourceBase] $this).Test()
+
+    # If needed, post-processing based on returned test result before returning to user
+
+    return $inDesiredState
+}
+
+[void] Set()
+{
+    ([ResourceBase] $this).Set()
+
+    # If needed, additional state changes that could not be handled by Modify()
+}
+
+hidden [System.Collections.Hashtable] GetCurrentState([System.Collections.Hashtable] $properties)
+{
+    # Return current state as hashtable
+    # Variable $properties contains the key properties (key-value pairs).
+}
+
+hidden [void] Modify([System.Collections.Hashtable] $properties)
+{
+    # Set desired state for non-compliant properties only
+    # Variable $properties contains the properties (key-value pairs) that are not in desired state.
+}
+
+hidden [void] AssertProperties([System.Collections.Hashtable] $properties)
+{
+    # Validate user-provided properties
+    # Variable $properties contains properties user assigned values.
+}
+
+hidden [void] NormalizeProperties([System.Collections.Hashtable] $properties)
+{
+    # Normalize user-provided properties
+    # Variable $properties contains properties user assigned values.
+}
+```

.github/instructions/dsc-community-style-guidelines-class-resource.instructions.md

@@ -0,0 +1,49 @@
+---
+description: Guidelines for implementing integration tests for commands.
+applyTo: "tests/[iI]ntegration/**/*.[iI]ntegration.[tT]ests.ps1"
+---
+
+# Integration Tests Guidelines
+
+## 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.
+
+## Required Setup Block
+
+```powershell
+[System.Diagnostics.CodeAnalysis.SuppressMessageAttribute('PSUseDeclaredVarsMoreThanAssignments', '', Justification = 'Suppressing this rule because Script Analyzer does not understand Pester syntax.')]
+param ()
+
+BeforeDiscovery {
+    try
+    {
+        if (-not (Get-Module -Name 'DscResource.Test'))
+        {
+            # Assumes dependencies have been resolved, so if this module is not available, run 'noop' task.
+            if (-not (Get-Module -Name 'DscResource.Test' -ListAvailable))
+            {
+                # Redirect all streams to $null, except the error stream (stream 2)
+                & "$PSScriptRoot/../../../build.ps1" -Tasks 'noop' 3>&1 4>&1 5>&1 6>&1 > $null
+            }
+
+            # If the dependencies have not been resolved, this will throw an error.
+            Import-Module -Name 'DscResource.Test' -Force -ErrorAction 'Stop'
+        }
+    }
+    catch [System.IO.FileNotFoundException]
+    {
+        throw 'DscResource.Test module dependency not found. Please run ".\build.ps1 -ResolveDependency -Tasks build" first.'
+    }
+}
+
+BeforeAll {
+    $script:dscModuleName = 'SqlServerDsc'
+
+    Import-Module -Name $script:dscModuleName -Force -ErrorAction 'Stop'
+}
+```

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

@@ -0,0 +1,36 @@
+---
+description: Guidelines for implementing localization.
+applyTo: "source/**/*.ps1"
+---
+
+# Localization Guidelines
+
+## 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
+
+## String Files
+- Commands/functions: `source/en-US/SqlServerDsc.strings.psd1`
+- Class resources: `source/en-US/{ResourceClassName}.strings.psd1`
+
+## Key Naming
+- Format: `FunctionName_Description` (underscore separators)
+- Example: `Get_SqlDscDatabase_ConnectingToDatabase`
+
+## String Format
+```powershell
+ConvertFrom-StringData @'
+    KeyName = Message with {0} placeholder. (PREFIX0001)
+'@
+```
+
+## 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
+```powershell
+Write-Verbose -Message ($script:localizedData.KeyName -f $value1)
+```

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

@@ -0,0 +1,9 @@
+---
+description: Guidelines for writing and maintaining Markdown documentation.
+applyTo: "**/*.md"
+---
+
+# Markdown Style Guidelines
+
+- Wrap lines at 80 characters
+- Use 2 spaces for indentation

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

@@ -0,0 +1,52 @@
+---
+description: Guidelines for implementing MOF DSC resources.
+applyTo: "source/DSCResources/**/*.psm1"
+---
+
+# MOF-based Desired State Configuration (DSC) Resources Guidelines
+
+## Required Functions
+- Every DSC resource must define: `Get-TargetResource`, `Set-TargetResource`, `Test-TargetResource`
+- Export using `*-TargetResource` pattern
+
+## Function Return Types
+- `Get-TargetResource`: Must return hashtable with all resource properties
+- `Test-TargetResource`: Must return boolean ($true/$false)
+- `Set-TargetResource`: Must not return anything (void)
+
+## Parameter Guidelines
+- `Get-TargetResource`: Only include parameters needed to retrieve actual current state values
+- `Get-TargetResource`: Remove non-mandatory parameters that are never used
+- `Set-TargetResource` and `Test-TargetResource`: Must have identical parameters
+- `Set-TargetResource` and `Test-TargetResource`: Unused mandatory parameters: Add "Not used in <function_name>" to help comment
+
+## Required Elements
+- Each function must include `Write-Verbose` at least once
+  - `Get-TargetResource`: Use verbose message starting with "Getting the current state of..."
+  - `Set-TargetResource`: Use verbose message starting with "Setting the desired state of..."
+  - `Test-TargetResource`: Use verbose message starting with "Determining the current state of..."
+- Use localized strings for all messages (Write-Verbose, Write-Error, etc.)
+- Import localized strings using `Get-LocalizedData` at module top
+
+## Error Handling
+- Do not use `throw` for terminating errors
+- Use `try/catch` blocks to handle exceptions
+- Throw localized exceptions using the appropriate `New-*Exception` cmdlet:
+  - [`New‑InvalidDataException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91InvalidDataException)
+  - [`New-ArgumentException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91ArgumentException)
+  - [`New-InvalidOperationException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91InvalidOperationException)
+  - [`New-ObjectNotFoundException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91ObjectNotFoundException)
+  - [`New-InvalidResultException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91InvalidResultException)
+  - [`New-NotImplementedException`](https://github.com/dsccommunity/DscResource.Common/wiki/New%E2%80%91NotImplementedException)
+
+# MOF Resource Localization
+
+## File Structure
+- Create `en-US` folder in each resource directory
+- Name strings file: `DSC_<ResourceName>.strings.psd1`
+- Use names returned from `Get-UICulture` for additional language folder names
+
+## String File Format
+
+- In `.strings.psd1` files, use underscores as word separators in localized
+  string key names (for multi-word keys)

.github/instructions/dsc-community-style-guidelines-mof-resources.instructions.md

@@ -0,0 +1,48 @@
+---
+description: Guidelines for writing and maintaining tests using Pester.
+applyTo: "**/*.[Tt]ests.ps1"
+---
+
+# Tests Guidelines
+
+## Core Requirements
+- All public commands, private functions and classes must have unit tests
+- Use Pester v5 syntax only
+- One `Describe` block per file matching the tested entity name
+- Test code only inside `Describe` blocks
+- Assertions only in `It` blocks
+- Never test `Write-Verbose`, `Write-Debug`, or parameter binding behavior
+- Pass all mandatory parameters to avoid prompts
+
+## Structure & Scope
+- Public commands: Never use `InModuleScope`
+- Private functions/class resources: Always use `InModuleScope`
+- Each scenario = separate `Context` block
+- Use nested `Context` blocks for complex scenarios
+- Mocking in `BeforeAll` (`BeforeEach` only when required)
+- Setup/teardown in `BeforeAll`,`BeforeEach`/`AfterAll`,`AfterEach` close to usage
+
+## Syntax Rules
+- PascalCase: `Describe`, `Context`, `It`, `Should`, `BeforeAll`, `BeforeEach`, `AfterAll`, `AfterEach`
+- `It` descriptions start with 'Should'
+- `Context` descriptions start with 'When'
+- Mock variables prefix: 'mock'
+- Prefer `-BeTrue`/`-BeFalse` over `-Be $true`/`-Be $false`
+- No `Should -Not -Throw` - invoke commands directly
+
+## File Organization
+- Class resources: `tests/Unit/Classes/{Name}.Tests.ps1`
+- Public commands: `tests/Unit/Public/{Name}.Tests.ps1`
+- Private functions: `tests/Unit/Private/{Name}.Tests.ps1`
+
+## Data-Driven Tests
+- Define variables in separate `BeforeDiscovery` for `-ForEach` (close to usage)
+- `-ForEach` allowed on `Context` and `It` blocks
+- Keep scope close to usage context
+
+## Best Practices
+- Assign unused return objects to `$null`
+- Tested entity must be called from within the `It` blocks
+- Keep results and assertions in same `It` block
+- Cover all scenarios and code paths
+- Use `BeforeEach` and `AfterEach` sparingly