The PSModule docs site has a Versioning page that defines how to version modules under SemVer, but there is no documentation on how modules should declare and constrain versions of their dependencies. This gap was exposed by PSModule/Fonts#58 and PSModule/NerdFonts#64, where exact version pins (RequiredVersion) caused Import-Module failures when users had newer versions of dependencies installed.
Request
What is confusing or missing
A developer creating or maintaining a PSModule module has no documented guidance on:
- Which mechanism to use for declaring dependencies (
RequiredModules vs #Requires -Modules vs NestedModules vs vendoring)
- How to constrain dependency versions (
ModuleVersion vs RequiredVersion vs MaximumVersion)
- What the org-wide conventions are for dependency management
Without this, each module author makes ad-hoc choices, leading to inconsistencies (some modules use #Requires per-file, others use RequiredModules in the manifest) and bugs (exact version pins causing import failures).
Acceptance criteria
- A new
Dependencies.md page exists under docs/PowerShell-Modules/ in the docs site
- The page is linked in the
mkdocs.yml navigation under PowerShell Modules
- The content covers the topics listed in the implementation plan below
- The page cross-references the existing Versioning page
Technical decisions
File location: docs/PowerShell-Modules/Dependencies.md, alongside the existing Versioning.md and Test-Specification.md.
Navigation placement: In mkdocs.yml, add Dependencies: PowerShell-Modules/Dependencies.md under the PowerShell Modules section, before Test-Specification (alphabetical order).
Content scope: The page should cover the topics outlined below. The research backing these recommendations comes from:
Content outline
The page should include the following sections:
1. Declaring dependencies — A comparison of the four mechanisms with a summary table:
| Mechanism |
Loaded into |
Auto-installed by Gallery? |
Recommended for |
RequiredModules (manifest) |
Caller's session |
Yes |
Published module dependencies |
#Requires -Modules (per-file) |
Caller's session |
No (assert only) |
Standalone scripts |
NestedModules (manifest) |
Module's private session |
Yes (if by name) |
Splitting own code |
| Vendored copy |
Module's session (via path) |
No |
Unpublished / isolated deps |
2. Version constraints — The three keys and their behavior:
| Key |
Behavior |
Example |
ModuleVersion |
Minimum floor — any version ≥ value satisfies |
ModuleVersion = '1.1.13' |
RequiredVersion |
Exact pin — only that version satisfies |
RequiredVersion = '1.1.13' |
MaximumVersion |
Ceiling — any version ≤ value satisfies |
MaximumVersion = '1.99.99' |
With recommended strategies:
- Minimum only (
ModuleVersion) — default, recommended
- Major-pinned range (
ModuleVersion + MaximumVersion) — when concerned about next major
- Exact pin (
RequiredVersion) — avoid for published modules; acceptable in test files for test framework pinning
3. Setting the minimum version — Bump to the latest published version of the dependency at each release. Do not carry forward stale minimums.
4. PSModule organization conventions:
- Declare dependencies in the manifest using
RequiredModules — not #Requires in function files
- Use
ModuleVersion (minimum) — never RequiredVersion (exact pin) for inter-module dependencies
- Bump the minimum on each release
- Follow SemVer (links to existing Versioning page)
- Do not vendor PSModule-published dependencies
5. Common mistakes table — RequiredVersion causing failures, version drift between manifest and #Requires, stale minimums, unnecessary vendoring
6. References — Links to official PowerShell docs and the Fonts/NerdFonts issues as case studies
Implementation plan
Documentation
Review
The PSModule docs site has a Versioning page that defines how to version modules under SemVer, but there is no documentation on how modules should declare and constrain versions of their dependencies. This gap was exposed by PSModule/Fonts#58 and PSModule/NerdFonts#64, where exact version pins (
RequiredVersion) causedImport-Modulefailures when users had newer versions of dependencies installed.Request
What is confusing or missing
A developer creating or maintaining a PSModule module has no documented guidance on:
RequiredModulesvs#Requires -ModulesvsNestedModulesvs vendoring)ModuleVersionvsRequiredVersionvsMaximumVersion)Without this, each module author makes ad-hoc choices, leading to inconsistencies (some modules use
#Requiresper-file, others useRequiredModulesin the manifest) and bugs (exact version pins causing import failures).Acceptance criteria
Dependencies.mdpage exists underdocs/PowerShell-Modules/in the docs sitemkdocs.ymlnavigation under PowerShell ModulesTechnical decisions
File location:
docs/PowerShell-Modules/Dependencies.md, alongside the existingVersioning.mdandTest-Specification.md.Navigation placement: In
mkdocs.yml, addDependencies: PowerShell-Modules/Dependencies.mdunder the PowerShell Modules section, before Test-Specification (alphabetical order).Content scope: The page should cover the topics outlined below. The research backing these recommendations comes from:
Content outline
The page should include the following sections:
1. Declaring dependencies — A comparison of the four mechanisms with a summary table:
RequiredModules(manifest)#Requires -Modules(per-file)NestedModules(manifest)2. Version constraints — The three keys and their behavior:
ModuleVersionModuleVersion = '1.1.13'RequiredVersionRequiredVersion = '1.1.13'MaximumVersionMaximumVersion = '1.99.99'With recommended strategies:
ModuleVersion) — default, recommendedModuleVersion+MaximumVersion) — when concerned about next majorRequiredVersion) — avoid for published modules; acceptable in test files for test framework pinning3. Setting the minimum version — Bump to the latest published version of the dependency at each release. Do not carry forward stale minimums.
4. PSModule organization conventions:
RequiredModules— not#Requiresin function filesModuleVersion(minimum) — neverRequiredVersion(exact pin) for inter-module dependencies5. Common mistakes table —
RequiredVersioncausing failures, version drift between manifest and#Requires, stale minimums, unnecessary vendoring6. References — Links to official PowerShell docs and the Fonts/NerdFonts issues as case studies
Implementation plan
Documentation
docs/PowerShell-Modules/Dependencies.mdwith the content outlined abovemkdocs.yml:Dependencies: PowerShell-Modules/Dependencies.mdunder PowerShell Modules, before Test-SpecificationReview