Skip to content

Commit 7828713

Browse files
authored
Merge pull request #52 from fadwen/chore/sync-copilot-standards
chore: sync Copilot and Claude Code standards from standards repo
2 parents b924a2d + 416062d commit 7828713

17 files changed

Lines changed: 601 additions & 59 deletions

‎.github/copilot-instructions.md‎

Lines changed: 34 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -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
716749
described 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/) |

‎.github/instructions/architecturedesign.instructions.md‎

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -139,7 +139,11 @@ Implement comprehensive error handling:
139139

140140
### Scalability Patterns
141141

142-
- **Parallel Processing**: ForEach-Object -Parallel for PowerShell 7+
142+
- **Parallel Processing**: ForEach-Object -Parallel for PowerShell 7+. A parallel block, a runspace
143+
worker, and a `Start-Job` body all start without the caller's `$script:` state; pass what they need
144+
through `$using:`, a parameter, or `-ArgumentList`, and keep a contract test that refuses a `$script:`
145+
read inside one. Measure before adopting: a cmdlet that keeps one session per process, such as the
146+
RSAT `ActiveDirectory` module, fails under runspaces in ways a process per batch does not
143147
- **Batch Processing**: Chunked operations for large datasets
144148
- **Streaming**: Pipeline-based processing for memory efficiency
145149
- **Caching**: Multi-level caching strategies

‎.github/instructions/cicd.instructions.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -179,6 +179,13 @@ Configure automated publishing with:
179179
- Pre-release versions for development branches
180180
- Release notes generation from changelog
181181
- API key management through secure secret storage
182+
- A release rehearsal, `Publish-Module.ps1 -WhatIf`, that stages the allowlisted package, imports it
183+
in a fresh process, verifies exports and help, measures the Gallery's metadata limits, and stops
184+
before the upload. Run it on every pull request; the tag-driven release re-runs it and publishes.
185+
- The rules the rehearsal exists to enforce are in
186+
[module.instructions.md](./module.instructions.md#releasing-to-the-powershell-gallery): never
187+
publish the repository root, the `ReleaseNotes`, `Description` and tag limits, no empty URI keys,
188+
and `$WhatIfPreference` reaching every child scope of the release script.
182189

183190
## Security Integration
184191

‎.github/instructions/comments.instructions.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ This file defines **what good help content contains**. Where that content is wri
1515
whether the function is exported:
1616

1717
| Function | Help lives in | Notes |
18-
|---|---|---|
18+
| --- | --- | --- |
1919
| Exported (`Public/`) in a module | PlatyPS Markdown under `docs/ModuleName/` | The `.ps1` keeps only `# .EXTERNALHELP` plus a one-line `.SYNOPSIS` |
2020
| Private (`Private/`) in a module | Full comment-based help in the `.ps1` | PlatyPS never sees these - the comment block is the only documentation |
2121
| Standalone script or function | Full comment-based help in the `.ps1` | No module, no MAML, no PlatyPS |
@@ -276,7 +276,7 @@ The sections above are named for comment-based help keywords. In PlatyPS Markdow
276276
The content requirements are identical; only the syntax differs:
277277

278278
| Comment-based help | PlatyPS Markdown |
279-
|---|---|
279+
| --- | --- |
280280
| `.SYNOPSIS` | `## SYNOPSIS` |
281281
| `.DESCRIPTION` | `## DESCRIPTION` |
282282
| `.PARAMETER Name` | `### -Name` under `## PARAMETERS` |

0 commit comments

Comments
 (0)