Skip to content

Commit b4138fc

Browse files
đź“– [Docs]: Guide major-version bounding for #Requires module dependencies (#22)
The PowerShell scripts coding standard now explains how to version-constrain `#Requires` module dependencies, so authors pick the pin that matches their risk appetite instead of making ad-hoc choices. ## Changed: `#Requires` version-constraint guidance The Scripts standard now recommends a **minimum** version by default, a **major-version bound** (`MaximumVersion = 'N.*'`) for dependencies whose new major would break you — a test framework like Pester being the typical case — and avoiding exact `RequiredVersion` pins that freeze out patches. Module-identity pinning with a `GUID` is called out as a separate, stricter supply-chain control, used only when identity assurance is needed and not as part of the default version lock. ## Technical Details - Updates `src/docs/Coding-Standards/PowerShell/Scripts.md` (the `#Requires` item in the section structure and the example). - Aligns with the Pester 6.x lock adopted across the PSModule modules (PSModule/Process-PSModule#356).
1 parent 1ac3201 commit b4138fc

1 file changed

Lines changed: 2 additions & 2 deletions

File tree

‎src/docs/Coding-Standards/PowerShell/Scripts.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -11,15 +11,15 @@ A script (`.ps1`) is an entry point, not a home for logic. Keep scripts **thin**
1111

1212
A script file is laid out top to bottom in this order:
1313

14-
1. **`#Requires`** statements — PowerShell version and module dependencies with minimum versions.
14+
1. **`#Requires`** statements — PowerShell version and module dependencies. Prefer a **minimum** version (`ModuleVersion`) so security patches and fixes flow in. When a new *major* of a dependency would break you — a test framework such as Pester is the typical case — bound it to that major by adding `MaximumVersion` (e.g. `ModuleVersion = '6.0.0'; MaximumVersion = '6.*'`). Avoid exact `RequiredVersion` pins, which freeze out patches and go stale. Pinning module identity with a `GUID` is a separate, stricter supply-chain control — reach for it only when you need identity assurance, not as part of the default version lock.
1515
2. **Comment-based help** — the same sections and order as a [function's](Functions.md#comment-based-help-required), only without the enclosing `function` block: `.SYNOPSIS`, `.DESCRIPTION`, at least one `.EXAMPLE`, then `.INPUTS`, `.OUTPUTS`, `.NOTES`, and `.LINK` as they apply. Document each parameter with an inline comment above it, just as a function does.
1616
3. **`[CmdletBinding()]` + `param()`** — typed and validated, mandatory first; add `SupportsShouldProcess` when the script changes state.
1717
4. **`$ErrorActionPreference = 'Stop'`**.
1818
5. **Body** — the thin orchestration.
1919

2020
```powershell
2121
#Requires -Version 7.0
22-
#Requires -Modules Pester
22+
#Requires -Modules @{ ModuleName = 'Pester'; ModuleVersion = '6.0.0'; MaximumVersion = '6.*' }
2323
2424
<#
2525
.SYNOPSIS

0 commit comments

Comments
 (0)