From ef05304fc2f9bc7009d3d5457a761230f1bf5a3d Mon Sep 17 00:00:00 2001 From: Copilot Date: Sat, 6 Jun 2026 13:43:16 -0700 Subject: [PATCH] docs(powershell): require ShouldProcess/-WhatIf over custom dry-run Add a "State-Changing Functions" section to the PowerShell instructions: mutating functions/scripts should implement SupportsShouldProcess and guard actions with $PSCmdlet.ShouldProcess(...), giving callers built-in -WhatIf and -Confirm. Prefer this over a bespoke -DryRun switch, since -WhatIf is the idiomatic PowerShell dry run. Closes #186 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --- .github/instructions/powershell.instructions.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/.github/instructions/powershell.instructions.md b/.github/instructions/powershell.instructions.md index 6c95164..2cad131 100644 --- a/.github/instructions/powershell.instructions.md +++ b/.github/instructions/powershell.instructions.md @@ -22,6 +22,22 @@ applyTo: '**/*.ps1,**/*.psm1,**/*.psd1' where appropriate. - Use `[OutputType()]` on functions that return typed objects. +## State-Changing Functions + +- For functions or scripts that modify state (create / change / delete files, + registry, services, remote resources, etc.), implement the standard + `SupportsShouldProcess` pattern -- declare + `[CmdletBinding(SupportsShouldProcess)]` and guard each mutating action with + `if ($PSCmdlet.ShouldProcess($target, $action)) { ... }`. +- This gives callers the built-in `-WhatIf` (dry run) and `-Confirm` (prompt) + switches for free. **Prefer this over a hand-rolled `-DryRun` / `-Preview` + switch or any other bespoke dry-run flag** -- `-WhatIf` is the idiomatic + PowerShell dry run and integrates with `$WhatIfPreference` and the rest of + the engine. +- Set `[CmdletBinding(SupportsShouldProcess, ConfirmImpact = 'High')]` for + destructive operations so they prompt by default; unattended callers opt out + with `-Confirm:$false`. + ## Error Handling - Use `-ErrorAction Stop` on critical calls within `try/catch` blocks.