From 4c8ba2fb342551cd27b508f3b62a4afc197733e6 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 15:17:55 +0200 Subject: [PATCH 1/6] Add PowerShell module repository defaults --- .../PowerShell/Modules/Repository-Defaults.md | 188 ++++++++++++++++++ src/docs/PowerShell/Modules/index.md | 1 + src/zensical.toml | 1 + 3 files changed, 190 insertions(+) create mode 100644 src/docs/PowerShell/Modules/Repository-Defaults.md diff --git a/src/docs/PowerShell/Modules/Repository-Defaults.md b/src/docs/PowerShell/Modules/Repository-Defaults.md new file mode 100644 index 0000000..0f4aca5 --- /dev/null +++ b/src/docs/PowerShell/Modules/Repository-Defaults.md @@ -0,0 +1,188 @@ +# PowerShell module repository defaults + +This page defines the default repository contract for PowerShell module repositories in the PSModule organization. It describes what a newly created or maintained module repository should look like before module-specific code, tests, and documentation are considered. + +The implementation standard still lives in [PowerShell module standard](Standards.md). This page covers repository defaults: files, metadata, README shape, release integration, and placeholder handling. + +## Scope + +These defaults apply to repositories whose primary artifact is a PowerShell module published through the PSModule framework. + +They do not apply directly to: + +- GitHub Action repositories such as `Build-PSModule`, `Invoke-Pester`, or `Publish-PSModule`. +- Documentation repositories such as `PSModule/docs`. +- Template repositories other than `Template-PSModule`. +- Test, archive, service, or infrastructure repositories that are not published as module artifacts. + +Each initiative should keep its own repository standards in its central documentation repository. For the PSModule organization, this repository is the source of truth. + +## Repository creation + +Create new module repositories from [`PSModule/Template-PSModule`](https://github.com/PSModule/Template-PSModule). The template provides the framework wiring, starter layout, and CI/CD expectations. + +After creating the repository: + +1. Replace template tokens such as `{{ NAME }}` and `{{ DESCRIPTION }}`. +2. Remove scaffold functions, tests, and examples that do not represent the module. +3. Set repository metadata and custom properties. +4. Confirm the README reflects the module's actual status. +5. Confirm `.github/PSModule.yml` only overrides defaults when the module needs different behavior. + +## Required repository metadata + +Each module repository should have: + +- A concise GitHub repository description that starts with or clearly says `A PowerShell module ...`. +- `RepoType: Module` as the repository custom property. +- Topics that help users find the module, when relevant. +- Branch protection and workflow requirements inherited from organization defaults. +- `main` as the default branch unless there is a documented legacy reason. + +The repository description is used as a short landing-page summary in documentation and automation. Keep it user-facing and avoid implementation details. + +## Default branch and worktrees + +Use `main` for active module repositories. Legacy repositories that still use `master` should not be used as examples for new work. + +Local work should use the organization worktree convention: + +- The bare repository stays at the repository root. +- `main/` tracks the default branch. +- Feature worktrees use `-` directories and `/` branches. + +For branch and worktree details, see [Git Worktrees](../../Ways-of-Working/Git-Worktrees.md). + +## Default repository layout + +Module repositories use the PSModule framework layout: + +| Path | Default purpose | +| ---- | --------------- | +| `README.md` | Concise landing page for the repository. | +| `.github/PSModule.yml` | Module workflow configuration overrides. | +| `.github/workflows/workflow.yml` | Reusable Process-PSModule workflow entry point. | +| `src/` | Module source compiled into the shipped artifact. | +| `src/functions/public/` | Exported commands, grouped by domain. | +| `src/functions/private/` | Internal helper commands, grouped by domain. | +| `src/classes/public/` | Public classes that are part of the user-facing model. | +| `src/classes/private/` | Internal implementation classes. | +| `src/data/` | Static module data that ships with the module. | +| `examples/` | Realistic user scenarios, not copies of command help. | +| `tests/` | Pester tests and test data. | +| `icon/` | Module icon assets. | + +Detailed source layout rules live in [PowerShell module standard](Standards.md#repository-layout). + +## README default + +A module README is a landing page, not the command reference. It should help a user identify the module, install it, and find generated documentation. + +For implemented modules, use this shape: + +````markdown +# + + + +## Installation + +Install the module from the PowerShell Gallery: + +```powershell +Install-PSResource -Name +Import-Module -Name +``` + +## Documentation + +Documentation is published at [psmodule.io/](https://psmodule.io//). + +Use PowerShell help and command discovery for module details: + +```powershell +Get-Command -Module +Get-Help -Name 'CommandName' -Examples +``` + +## Contributing + +Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements. +```` + +README pages should not duplicate generated command documentation. Do not add full command inventories, parameter tables, or long usage sections when those details are already produced from comment-based help. + +## Placeholder and in-progress repositories + +If a repository is reserved for a future module or still contains scaffold code, say that directly. Do not leave `{{ NAME }}`, `{{ DESCRIPTION }}`, `PSModuleTemplate`, `Greet-Entity`, or similar template examples in the README. + +Use this shape for placeholder repositories: + +````markdown +# + + + +## Status + +This repository is currently a placeholder. The module source still contains scaffold code, so there are no supported commands or usage examples to document yet. + +## Documentation + +When this module is implemented, command details should live in PowerShell help and generated documentation rather than being duplicated in this README. + +## Contributing + +Issues and pull requests are welcome when implementation work begins. +```` + +Use the same pattern for in-progress modules with stub commands, but name the stub honestly: + +```markdown +This repository is currently in progress. The current `` command is a stub and throws `NotImplementedException`, so there are no supported conversion commands or usage examples to document yet. +``` + +## README validation + +Before opening a README-only PR, check that the README follows the default and does not contain leftover scaffolding: + +```powershell +Select-String -Path README.md -SimpleMatch -Pattern 'Greet-Entity', 'PSModuleTemplate', 'YourModuleName' +Select-String -Path README.md -SimpleMatch -Pattern '{{ NAME }}', '{{ DESCRIPTION }}' +Select-String -Path README.md -Pattern '^## (Usage|Commands|Examples)$' +git diff --check -- README.md +``` + +`Template-PSModule` is the exception: it intentionally keeps `{{ NAME }}` and `{{ DESCRIPTION }}` tokens because those are template inputs. + +## Documentation ownership + +Command details belong in comment-based help and generated documentation. The README points to those sources instead of re-stating them. + +Use these defaults: + +- Command synopsis, parameters, examples, links, and outputs live in comment-based help. +- Group overview pages live next to public command groups in `src/functions/public//.md`. +- Realistic end-to-end scenarios live in `examples/`. +- README pages stay short and stable. + +This keeps the repository landing page readable and prevents drift between README content, PowerShell help, and generated documentation. + +## Release and PR defaults + +Module repositories use the Process-PSModule workflow. Version and release behavior is driven by PR labels and workflow settings. + +Default expectations: + +- `Major`, `Minor`, `Patch`, and `Prerelease` labels determine release behavior. +- Documentation-only README standardization PRs use the `Docs`/`NoRelease` behavior when available. +- Source changes under `src/` are module-impacting and should trigger the full module workflow. +- README and documentation changes should update the site without pretending to be module API changes. + +See [Versioning](Versioning.md) for semantic version rules and [PowerShell module standard](Standards.md#cicd-pipeline) for the Process-PSModule pipeline. + +## Template maintenance + +`Template-PSModule` defines the default README shape and starter repository contract. When this page changes a default, update `Template-PSModule` in the same work item when practical. + +The template README may contain tokens, but generated module repositories should not keep them after the initial setup commit. diff --git a/src/docs/PowerShell/Modules/index.md b/src/docs/PowerShell/Modules/index.md index 77ecdd6..f88e7ad 100644 --- a/src/docs/PowerShell/Modules/index.md +++ b/src/docs/PowerShell/Modules/index.md @@ -20,6 +20,7 @@ The template ships with placeholder files to illustrate the expected layout — Version increments are driven by PR labels (`Major`, `Minor`, `Patch`, `Prerelease`), and the `RepoType: Module` custom property integrates each repository with organization-wide tooling. +- **[Repository Defaults](Repository-Defaults.md)** — Required repository defaults for PSModule PowerShell module repos, including README shape, placeholder handling, metadata, and documentation ownership. - **[Standards](Standards.md)** — Repository layout, naming, style, parameter design, comment-based help, and SOLID applied to PowerShell modules. - **[Test Specification](Test-Specification.md)** — How we write Pester tests: structure, hierarchy, and naming conventions. - **[Versioning](Versioning.md)** — How changes to the public interface determine the SemVer version bump. diff --git a/src/zensical.toml b/src/zensical.toml index 946c0e5..0d1dc8e 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -33,6 +33,7 @@ nav = [ ]}, {"Modules" = [ "PowerShell/Modules/index.md", + {"Repository Defaults" = "PowerShell/Modules/Repository-Defaults.md"}, {"Standards" = "PowerShell/Modules/Standards.md"}, {"Test Specification" = "PowerShell/Modules/Test-Specification.md"}, {"Versioning" = "PowerShell/Modules/Versioning.md"}, From 99716824a88ae9bfde25c91cbacd6cf6d866d8ac Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 15:25:52 +0200 Subject: [PATCH 2/6] Expand module repository defaults with managed file standards --- .../PowerShell/Modules/Repository-Defaults.md | 108 +++++++++++++++++- 1 file changed, 104 insertions(+), 4 deletions(-) diff --git a/src/docs/PowerShell/Modules/Repository-Defaults.md b/src/docs/PowerShell/Modules/Repository-Defaults.md index 0f4aca5..e560a42 100644 --- a/src/docs/PowerShell/Modules/Repository-Defaults.md +++ b/src/docs/PowerShell/Modules/Repository-Defaults.md @@ -1,8 +1,8 @@ # PowerShell module repository defaults -This page defines the default repository contract for PowerShell module repositories in the PSModule organization. It describes what a newly created or maintained module repository should look like before module-specific code, tests, and documentation are considered. +This page defines the default repository contract for PowerShell module repositories in the PSModule organization. It describes what a newly created or maintained module repository should look like before module-specific code, tests, documentation, and managed repository files are considered. -The implementation standard still lives in [PowerShell module standard](Standards.md). This page covers repository defaults: files, metadata, README shape, release integration, and placeholder handling. +The implementation standard still lives in [PowerShell module standard](Standards.md). This page covers repository defaults: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution. ## Scope @@ -26,8 +26,9 @@ After creating the repository: 1. Replace template tokens such as `{{ NAME }}` and `{{ DESCRIPTION }}`. 2. Remove scaffold functions, tests, and examples that do not represent the module. 3. Set repository metadata and custom properties. -4. Confirm the README reflects the module's actual status. -5. Confirm `.github/PSModule.yml` only overrides defaults when the module needs different behavior. +4. Confirm the README reflects the module's actual status and uses `Install-PSResource` for installation. +5. Confirm required common files are present. +6. Confirm `.github/PSModule.yml` only overrides defaults when the module needs different behavior. ## Required repository metadata @@ -60,8 +61,18 @@ Module repositories use the PSModule framework layout: | Path | Default purpose | | ---- | --------------- | | `README.md` | Concise landing page for the repository. | +| `LICENSE` | Repository license. PSModule module repositories default to MIT unless a different license is explicitly decided. | +| `CONTRIBUTING.md` | Contribution workflow or a repository-level pointer to the organization contribution guide. | +| `SECURITY.md` | Security support policy and private vulnerability reporting instructions. | +| `SUPPORT.md` | Support expectations and where users ask for help. | +| `CODE_OF_CONDUCT.md` | Community conduct expectations. | | `.github/PSModule.yml` | Module workflow configuration overrides. | | `.github/workflows/workflow.yml` | Reusable Process-PSModule workflow entry point. | +| `.github/dependabot.yml` | Dependency and supply-chain update configuration. | +| `.github/CODEOWNERS` | Ownership routing for reviews and protected areas. | +| `.github/pull_request_template.md` | PR Manager-compatible pull request template. | +| `.gitattributes` | Git line-ending and file handling defaults. | +| `.gitignore` | Shared ignore rules. | | `src/` | Module source compiled into the shipped artifact. | | `src/functions/public/` | Exported commands, grouped by domain. | | `src/functions/private/` | Internal helper commands, grouped by domain. | @@ -74,10 +85,99 @@ Module repositories use the PSModule framework layout: Detailed source layout rules live in [PowerShell module standard](Standards.md#repository-layout). +## Required common files + +Every module repository must carry the same baseline community, governance, and automation files. GitHub's organization-level `.github` community-file fallback is useful for display defaults, but it is not enough as the long-term PSModule standard because: + +- agents and humans need the files in the repository they are changing, not only inherited through GitHub UI behavior; +- tools such as Dependabot, linters, CODEOWNERS, and release automation read repository-local files; +- reviews need diffs against the actual managed file in the target repository; +- repository-local files make the standard portable to other initiatives such as MSXOrg, where each initiative should define its own standards and managed files; +- central fallback files in `PSModule/.github` do not provide a reliable enforcement or update workflow across all repositories. + +Required baseline files for module repositories: + +| File | Why it is required | +| ---- | ------------------ | +| `README.md` | Repository landing page and evergreen context for humans and agents. | +| `LICENSE` | Clear legal terms for reuse, packaging, and redistribution. | +| `CONTRIBUTING.md` | Shared contribution workflow and expectations. | +| `SECURITY.md` | Private vulnerability reporting and latest-version support policy. | +| `SUPPORT.md` | Support channel and issue-routing expectations. | +| `CODE_OF_CONDUCT.md` | Community participation rules. | +| `.github/dependabot.yml` | Supply-chain maintenance for GitHub Actions and PowerShell dependencies. | +| `.github/CODEOWNERS` | Review routing for source, docs, and GitHub workflow files. | +| `.github/pull_request_template.md` | Consistent PR Manager-style PR descriptions and change classification. | +| `.github/release.yml` | Release-note and changelog categorization where the repository creates GitHub releases. | +| `.github/PSModule.yml` | Module workflow defaults and overrides. | +| `.github/linters/.markdown-lint.yml` | Markdown linting defaults. | +| `.github/linters/.powershell-psscriptanalyzer.psd1` | PSScriptAnalyzer defaults. | +| `.gitattributes` | Git attribute defaults. | +| `.gitignore` | Shared ignore rules. | + +Repositories can add local files, but they should not remove these baseline files unless the repository is explicitly outside the module standard. + +## Managed file distribution + +Shared files should be treated as managed files. The current distribution service is [`PSModule/Distributor`](https://github.com/PSModule/Distributor). It keeps source file sets under `Repos/{Type}/{Selection}/` and syncs those files into repositories through pull requests. + +The current Distributor model is subscription-based: + +- `Type` is an organization repository custom property that maps a repository to a type folder such as `Module` or `Action`. +- `SubscribeTo` is an organization repository custom property that selects file sets such as `dependabot.yml`, `Linter Settings`, `PSModule Settings`, `CODEOWNERS`, `License`, `.gitattributes`, and `.gitignore`. +- Sync changes are delivered through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request. +- Managed files are overwritten by the source file set. Local edits to managed files should be made in Distributor, not directly in the receiving repository. +- Removing a file from a Distributor file set does not delete the previously distributed file from target repositories; cleanup is explicit. + +Two follow-up Distributor capabilities define the desired direction: + +- **Global file sets** should allow common file sets such as `.gitattributes`, `.gitignore`, and `License` to be defined once and made available to all repository types while still requiring subscription. +- **Mandatory file sets** should allow organization-critical files such as `SECURITY.md`, `CODE_OF_CONDUCT.md`, `CONTRIBUTING.md`, and supply-chain configuration to be pushed to applicable repositories without each repository having to subscribe manually. + +Until mandatory file sets exist, repository owners are still responsible for ensuring the required common files exist. Distributor is the preferred implementation mechanism; this document is the standard that says what must exist and why. + +## Supply-chain defaults + +Every module repository must include `.github/dependabot.yml`. Dependabot is part of the repository supply-chain control, not an optional convenience. + +Module repositories should configure at least: + +```yaml +version: 2 +updates: + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + labels: + - "dependencies" + - "github-actions" + + - package-ecosystem: "powershell" + directory: "/" + schedule: + interval: "weekly" + labels: + - "dependencies" + - "powershell" +``` + +The GitHub Actions ecosystem keeps pinned actions current. The PowerShell ecosystem keeps PowerShell dependency declarations current where Dependabot supports them. Repositories with additional package ecosystems should add them explicitly rather than replacing these defaults. + +Dependabot PRs still go through normal review. Automated dependency updates are not a substitute for reviewing release notes, changed permissions, pinned SHAs, or generated lock files. + ## README default A module README is a landing page, not the command reference. It should help a user identify the module, install it, and find generated documentation. +Module installation examples must use PSResourceGet: + +```powershell +Install-PSResource -Name +``` + +Do not use `Install-Module` in new module repository documentation. `Install-Module` belongs only in legacy/historical context where changing it would misrepresent the referenced system. + For implemented modules, use this shape: ````markdown From 0bc16f172afca06264bf8692c152dcaba9166e55 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 15:29:48 +0200 Subject: [PATCH 3/6] Use repository terminology for lockfiles --- src/docs/PowerShell/Modules/Repository-Defaults.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/docs/PowerShell/Modules/Repository-Defaults.md b/src/docs/PowerShell/Modules/Repository-Defaults.md index e560a42..59c1ede 100644 --- a/src/docs/PowerShell/Modules/Repository-Defaults.md +++ b/src/docs/PowerShell/Modules/Repository-Defaults.md @@ -164,7 +164,7 @@ updates: The GitHub Actions ecosystem keeps pinned actions current. The PowerShell ecosystem keeps PowerShell dependency declarations current where Dependabot supports them. Repositories with additional package ecosystems should add them explicitly rather than replacing these defaults. -Dependabot PRs still go through normal review. Automated dependency updates are not a substitute for reviewing release notes, changed permissions, pinned SHAs, or generated lock files. +Dependabot PRs still go through normal review. Automated dependency updates are not a substitute for reviewing release notes, changed permissions, pinned SHAs, or generated lockfiles. ## README default From df77116c161aa0523b653556cb9e0411c7885ac4 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 16:58:36 +0200 Subject: [PATCH 4/6] Allow README capability showcases --- .../PowerShell/Modules/Repository-Defaults.md | 22 +++++++++++++++---- 1 file changed, 18 insertions(+), 4 deletions(-) diff --git a/src/docs/PowerShell/Modules/Repository-Defaults.md b/src/docs/PowerShell/Modules/Repository-Defaults.md index 59c1ede..53e1d3b 100644 --- a/src/docs/PowerShell/Modules/Repository-Defaults.md +++ b/src/docs/PowerShell/Modules/Repository-Defaults.md @@ -168,7 +168,7 @@ Dependabot PRs still go through normal review. Automated dependency updates are ## README default -A module README is a landing page, not the command reference. It should help a user identify the module, install it, and find generated documentation. +A module README is a landing page, not the command reference. It should help a user identify the module, install it, see what it can do, and then find generated documentation. Module installation examples must use PSResourceGet: @@ -194,6 +194,17 @@ Install-PSResource -Name Import-Module -Name ``` +## Capabilities + +Use this section as a short showcase. Show the most important things the module makes possible with one to three realistic examples. + +The goal is discovery and marketing, not exhaustive command documentation. A reader should understand why the module exists and what kind of tasks it helps with. + +```powershell +# Replace this with a real example that demonstrates the module's value. +Get-Command -Module +``` + ## Documentation Documentation is published at [psmodule.io/](https://psmodule.io//). @@ -210,7 +221,9 @@ Get-Help -Name 'CommandName' -Examples Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements. ```` -README pages should not duplicate generated command documentation. Do not add full command inventories, parameter tables, or long usage sections when those details are already produced from comment-based help. +README pages may include a short capabilities or usage showcase before the documentation link. Keep that section focused on discovery and marketing: show representative outcomes, not every command, parameter, or edge case. + +README pages should not duplicate generated command documentation. Do not add full command inventories, parameter tables, or long reference sections when those details are already produced from comment-based help. ## Placeholder and in-progress repositories @@ -249,7 +262,7 @@ Before opening a README-only PR, check that the README follows the default and d ```powershell Select-String -Path README.md -SimpleMatch -Pattern 'Greet-Entity', 'PSModuleTemplate', 'YourModuleName' Select-String -Path README.md -SimpleMatch -Pattern '{{ NAME }}', '{{ DESCRIPTION }}' -Select-String -Path README.md -Pattern '^## (Usage|Commands|Examples)$' +Select-String -Path README.md -Pattern '^## Commands$' git diff --check -- README.md ``` @@ -257,13 +270,14 @@ git diff --check -- README.md ## Documentation ownership -Command details belong in comment-based help and generated documentation. The README points to those sources instead of re-stating them. +Command details belong in comment-based help and generated documentation. The README can showcase capability, then points to those sources for reference detail. Use these defaults: - Command synopsis, parameters, examples, links, and outputs live in comment-based help. - Group overview pages live next to public command groups in `src/functions/public//.md`. - Realistic end-to-end scenarios live in `examples/`. +- README capability examples are short, representative, and user-facing. - README pages stay short and stable. This keeps the repository landing page readable and prevents drift between README content, PowerShell help, and generated documentation. From d6287af19f0fee9c5d76ef23e7500ef70cbce00b Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 17:16:46 +0200 Subject: [PATCH 5/6] Remove community links from README defaults --- src/docs/PowerShell/Modules/Repository-Defaults.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/src/docs/PowerShell/Modules/Repository-Defaults.md b/src/docs/PowerShell/Modules/Repository-Defaults.md index 53e1d3b..c168b5f 100644 --- a/src/docs/PowerShell/Modules/Repository-Defaults.md +++ b/src/docs/PowerShell/Modules/Repository-Defaults.md @@ -215,10 +215,6 @@ Use PowerShell help and command discovery for module details: Get-Command -Module Get-Help -Name 'CommandName' -Examples ``` - -## Contributing - -Issues and pull requests are welcome. Please use the repository issue tracker to report bugs, request features, or discuss improvements. ```` README pages may include a short capabilities or usage showcase before the documentation link. Keep that section focused on discovery and marketing: show representative outcomes, not every command, parameter, or edge case. @@ -243,10 +239,6 @@ This repository is currently a placeholder. The module source still contains sca ## Documentation When this module is implemented, command details should live in PowerShell help and generated documentation rather than being duplicated in this README. - -## Contributing - -Issues and pull requests are welcome when implementation work begins. ```` Use the same pattern for in-progress modules with stub commands, but name the stub honestly: From 37bca484cff73cd96eff258738d19730b3b567e1 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Mon, 6 Jul 2026 18:19:57 +0200 Subject: [PATCH 6/6] Clarify module README start page defaults --- .../PowerShell/Modules/Repository-Defaults.md | 26 ++++++++++++++----- 1 file changed, 20 insertions(+), 6 deletions(-) diff --git a/src/docs/PowerShell/Modules/Repository-Defaults.md b/src/docs/PowerShell/Modules/Repository-Defaults.md index c168b5f..7ce6b66 100644 --- a/src/docs/PowerShell/Modules/Repository-Defaults.md +++ b/src/docs/PowerShell/Modules/Repository-Defaults.md @@ -26,7 +26,7 @@ After creating the repository: 1. Replace template tokens such as `{{ NAME }}` and `{{ DESCRIPTION }}`. 2. Remove scaffold functions, tests, and examples that do not represent the module. 3. Set repository metadata and custom properties. -4. Confirm the README reflects the module's actual status and uses `Install-PSResource` for installation. +4. Confirm the README answers the start-page questions and uses `Install-PSResource` for installation. 5. Confirm required common files are present. 6. Confirm `.github/PSModule.yml` only overrides defaults when the module needs different behavior. @@ -60,7 +60,7 @@ Module repositories use the PSModule framework layout: | Path | Default purpose | | ---- | --------------- | -| `README.md` | Concise landing page for the repository. | +| `README.md` | Concise start page for the module. | | `LICENSE` | Repository license. PSModule module repositories default to MIT unless a different license is explicitly decided. | | `CONTRIBUTING.md` | Contribution workflow or a repository-level pointer to the organization contribution guide. | | `SECURITY.md` | Security support policy and private vulnerability reporting instructions. | @@ -80,6 +80,7 @@ Module repositories use the PSModule framework layout: | `src/classes/private/` | Internal implementation classes. | | `src/data/` | Static module data that ships with the module. | | `examples/` | Realistic user scenarios, not copies of command help. | +| `docs/` | Product documentation source when the module needs documentation beyond generated command help. | | `tests/` | Pester tests and test data. | | `icon/` | Module icon assets. | @@ -168,7 +169,17 @@ Dependabot PRs still go through normal review. Automated dependency updates are ## README default -A module README is a landing page, not the command reference. It should help a user identify the module, install it, see what it can do, and then find generated documentation. +A module README is a start page, not the command reference or full manual. It brings a reader in, answers the first questions, and sends them to the right documentation surface. + +The README answers these questions, in this order: + +| Question | Module README responsibility | +| --- | --- | +| What is it? | Name the module and define its scope in one short paragraph. | +| Why should I care? | State the value or kind of task the module makes easier. | +| How do I get it? | Show the PowerShell Gallery install and import commands. | +| How does it work? | Show one to three representative capabilities or usage examples. | +| How do I get more info? | Link to generated module documentation and PowerShell help. | Module installation examples must use PSResourceGet: @@ -183,7 +194,7 @@ For implemented modules, use this shape: ````markdown # - + ## Installation @@ -196,7 +207,7 @@ Import-Module -Name ## Capabilities -Use this section as a short showcase. Show the most important things the module makes possible with one to three realistic examples. +Use this section as a short showcase and introduction to how the module works. Show the most important things the module makes possible with one to three realistic examples. The goal is discovery and marketing, not exhaustive command documentation. A reader should understand why the module exists and what kind of tasks it helps with. @@ -217,10 +228,12 @@ Get-Help -Name 'CommandName' -Examples ``` ```` -README pages may include a short capabilities or usage showcase before the documentation link. Keep that section focused on discovery and marketing: show representative outcomes, not every command, parameter, or edge case. +README pages should include a short capabilities or usage showcase before the documentation link when the module has working capabilities. Keep that section focused on discovery and marketing: show representative outcomes, not every command, parameter, or edge case. README pages should not duplicate generated command documentation. Do not add full command inventories, parameter tables, or long reference sections when those details are already produced from comment-based help. +Do not add a community-file or policy link section by default. Readers can find standard repository files such as `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, and `CODE_OF_CONDUCT.md` through GitHub conventions and the repository file tree. Link them only when the module has an unusual rule the user must know before using it. + ## Placeholder and in-progress repositories If a repository is reserved for a future module or still contains scaffold code, say that directly. Do not leave `{{ NAME }}`, `{{ DESCRIPTION }}`, `PSModuleTemplate`, `Greet-Entity`, or similar template examples in the README. @@ -269,6 +282,7 @@ Use these defaults: - Command synopsis, parameters, examples, links, and outputs live in comment-based help. - Group overview pages live next to public command groups in `src/functions/public//.md`. - Realistic end-to-end scenarios live in `examples/`. +- Product docs beyond generated command help live under `docs/` and publish through GitHub Pages or the initiative's module documentation site. - README capability examples are short, representative, and user-facing. - README pages stay short and stable.