@@ -52,6 +52,33 @@ expert feedback for accuracy:
5252 calls where empty strings matter
5353- ** Output** : Don't use misleading ` [OutputType([PSCustomObject])] ` declarations
5454- ** Documentation** : Don't use broken comment-based help (missing ` <# ` opener)
55+ - ** Block Scoping** : Don't ` return ` from ` begin ` to stop a command. ` return ` ends the ` begin ` block and nothing
56+ else; ` process ` still runs. A teardown that did this printed "cancelled" and deleted everything. Record the
57+ decision in a variable and test it at the top of ` process `
58+ - ** Confirmation Gates** : Don't rely on ` Read-Host ` or ` ShouldContinue ` to stop an unattended run. ` Read-Host `
59+ reads end-of-file in a non-interactive session and never matches the confirmation word; ` ShouldContinue ` hangs
60+ a console and is refused in CI. Treat a session that cannot answer as a refusal, and require ` -Force ` for an
61+ unattended destructive run
62+ - ** Parameter Shadowing** : Don't name a local after a parameter in any letter case. Variable names are
63+ case-insensitive, so a body-level ` $settings = @{} ` silently overwrites ` -Settings ` . Inside a nested function
64+ ` $PSBoundParameters ` is that function's own, so capture what it needs into a plain variable before defining it
65+ - ** WhatIf Reach** : Don't enumerate with ` ForEach-Object -MemberName ` in a command that supports ` -WhatIf ` ; that
66+ parameter set honours ` ShouldProcess ` , so the enumeration returns nothing under ` -WhatIf ` . Use a script block.
67+ ` $WhatIfPreference ` is also inherited by every child scope, which is why a release rehearsal has to pin its
68+ non-destructive steps; see
69+ [ module.instructions.md] ( ./instructions/module.instructions.md#the-rehearsal-under--whatif )
70+ - ** Background Scope** : Don't read ` $script: ` state, or call the module's own functions, inside ` Start-Job ` , a
71+ runspace worker, or a ` ForEach-Object -Parallel ` block. A job starts without this session's state and
72+ functions, and a worker without its state; neither fails loudly. A seed that did this created 688 computers
73+ with no prefix and silently created none of its 296 users. Pass values through ` -ArgumentList ` , ` $using: ` , or a
74+ parameter, and remember that Pester mocks do not reach a worker either
75+ - ** Empty Collections** : Don't rely on a nested helper returning ` @() ` . PowerShell unrolls an empty array on
76+ the way out of a function, so the caller receives ` $null ` and a splatted ` [object[]] ` parameter fails to
77+ bind. Wrap the call site with ` @(...) ` , or return with ` Write-Output -NoEnumerate `
78+ - ** Response Shapes** : Don't index response data with ` ['key'] ` or assume one shape. Graph SDK responses are
79+ hashtables by default and PSObjects with ` -OutputType PSObject ` ; ` ConvertFrom-Json ` is the reverse, and
80+ ` $psobject['key'] ` returns ` $null ` with no error. Read through one accessor that handles both; see
81+ [ module.instructions.md] ( ./instructions/module.instructions.md#responses-that-arrive-as-hashtables-or-psobjects )
5582
5683### Script Development Guidelines
5784
@@ -622,6 +649,12 @@ Describe "Get-ExampleData" -Tag "Unit" {
622649}
623650```
624651
652+ Before the first publish, read
653+ [ Releasing to the PowerShell Gallery] ( ./instructions/module.instructions.md#releasing-to-the-powershell-gallery ) .
654+ A Gallery version can never be deleted, so the publish stages an allowlist rather than the
655+ repository root, the Gallery's metadata limits are measured locally, no URI key is left empty, and
656+ the release script is written knowing that ` -WhatIf ` reaches every child scope it calls.
657+
625658## 🎯 Community Standards Integration
626659
627660### Automatic Validation
@@ -716,7 +749,7 @@ Prefer matching these over inventing a shape. Each is complete, runs, and passes
716749described above:
717750
718751| Need | Example |
719- | ---| ---|
752+ | --- | --- |
720753| A complete advanced function | [ Basic-Function-Example.ps1] ( ../powershell-standards/Examples/Basic-Function-Example.ps1 ) |
721754| Module layout and export boundary | [ Module-Structure-Example] ( ../powershell-standards/Examples/Module-Structure-Example/ ) |
722755| Pester 6 tests, including private functions | [ Module-Structure-Example/Tests] ( ../powershell-standards/Examples/Module-Structure-Example/Tests/ ) |
0 commit comments