diff --git a/README.md b/README.md index 9fb9ce8e..22da9ac0 100644 --- a/README.md +++ b/README.md @@ -953,6 +953,21 @@ How the module is built. │ └── README.md # Module-level docs ingested by Document-PSModule ``` +### Declaring module dependencies + +Declare module dependencies using +[`#Requires -Modules`](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_requires) +statements at the top of function files in `src/functions/public/` or `src/functions/private/` that require external modules. +[Build-PSModule](https://github.com/PSModule/Build-PSModule) collects every `#Requires -Modules` declaration across all +source files, de-duplicates the list, and writes it into the `RequiredModules` field of the compiled manifest +automatically. For the full range of supported syntax variants, see the +[about_Requires](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_requires) +documentation. + +> [!IMPORTANT] +> Adding `RequiredModules` to `src/manifest.psd1` is **not** supported for this purpose. Those entries are silently +> ignored by the build and will not appear in the compiled manifest. Use `#Requires -Modules` in function files instead. + ## Principles and practices The contribution and release process is based on the idea that a PR is a release, and we only maintain a single linear ancestry of versions, not going @@ -965,6 +980,9 @@ For each topic or feature to add to the release, open a new branch representing branch. Optionally add the `Prerelease` label on the PR for the release branch, to release preview versions before merging and releasing a published version of the PowerShell module. +Co-locate concerns for long-term maintainability. For example, `#Requires -Modules` statements belong in the function files that use them, not in a +central manifest — this makes it immediately visible which functions drive each external dependency, and avoids silent drift between the manifest and +the actual code. The process is compatible with: