📖 [Docs]: Guide major-version bounding for #Requires module dependencies - #22
Merged
Marius Storhaug (MariusStorhaug) merged 5 commits intoJul 9, 2026
Merged
Conversation
Marius Storhaug (MariusStorhaug)
added
the
documentation
Marius Storhaug (MariusStorhaug)
added a commit
that referenced
this pull request
Jul 9, 2026
…onstraint implementation (#26) The coding standards now include a **Dependencies** standard: how to pin a dependency and keep it current, across every ecosystem. It lays out the locking spectrum — from identity pins through patch, minor, and major to floating latest — and the balance every pin has to strike: loose enough to take security patches and fixes quickly, tight enough that unvetted or compromised code never lands automatically. PowerShell version constraints and GitHub Actions SHA pinning are its concrete implementations. ## New: the Dependencies standard `Coding Standards → Dependencies` separates a pin into two axes — **identity** (which artifact, proven: a module `GUID`, an Action SHA, an image digest) and **version tightness** (exact through latest) — and walks the spectrum with the tradeoff at each step: tighter is safer but slower to update; looser is faster but less vetted and not reproducible. It states the resolution the ecosystem follows — pin for integrity and automate the movement — and answers the practical questions: which update tracks exist, who each is for, and that a repository does not need all of them. A library declares a wide compatibility floor so it does not over-constrain its consumers; an application pins tight for reproducibility and lets the updater move it. It links to Security → Supply chain (the why) and the Dependency Updates capability (the automation). ## New: PowerShell version constraints `Coding Standards → PowerShell → Version Constraints` is the PowerShell implementation. Express every constraint as a NuGet version range in explicit brackets; a new locking-spectrum table maps identity, exact, patch, minor, major, and latest to NuGet ranges and `#Requires` keys. The syntax applies directly on PSResourceGet (`Install`/`Find`/`Save`/`Update-PSResource -Version`, `RequiredResourceFile`) and .NET `PackageReference`, maps to `ModuleVersion` / `MaximumVersion` / `RequiredVersion` for `#Requires` and manifests (which cannot take a NuGet string), and flags the PSResourceGet trap where a bare version is treated as the exact version, not a minimum. ## Changed: GitHub Actions The "Pin every action to a full commit SHA" section now names SHA pinning as the GitHub Actions expression of the Dependencies standard — an identity pin, kept current by the updater. ## Technical Details - New `src/docs/Coding-Standards/Dependencies.md` (baseline tier, placed after Security); reframed `src/docs/Coding-Standards/PowerShell/Version-Constraints.md` (adds the locking-spectrum table, folds the old intent→ModuleSpecification table into it); one cross-link added to `src/docs/Coding-Standards/GitHub-Actions.md`; registered in `src/zensical.toml` nav and the generated index tables. - Complements the in-flight `#Requires` PRs #22 (major-version bounding) and #23 (the `#Requires -Modules` reference); the spectrum's major lock (`ModuleVersion='6.0.0'; MaximumVersion='6.*'`) matches them. - Validated locally: `Update-DocumentationIndex.ps1 -Check`, `Test-DocumentationLink.ps1`, and markdownlint (repo config) all pass; front matter parses as YAML. <details> <summary>Related issues</summary> No linked issue — created on direct request. The Dependencies standard is the "separate doc" for the broader dependency/supply-chain update-management concept; open a tracking issue if it should be tracked. </details>
Marius Storhaug (MariusStorhaug)
deleted the
maintenance/pester-major-lock
branch
July 9, 2026 09:41
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The PowerShell scripts coding standard now explains how to version-constrain
#Requiresmodule dependencies, so authors pick the pin that matches their risk appetite instead of making ad-hoc choices.Changed:
#Requiresversion-constraint guidanceThe 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 exactRequiredVersionpins that freeze out patches. Module-identity pinning with aGUIDis 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
src/docs/Coding-Standards/PowerShell/Scripts.md(the#Requiresitem in the section structure and the example).