Skip to content

Commit 509c752

Browse files
MariusStorhaugMariusStorhaug
authored
📖 [Docs]: PowerShell module repository defaults now documented (#55)
PowerShell module repository defaults are now documented in the PSModule docs site. Module maintainers can use one central page to understand the expected repository metadata, layout, README shape, shared community files, supply-chain defaults, managed-file distribution model, documentation ownership, and release defaults. > ⚠️ This PR has no linked issue. Consider creating one for traceability. ## New: Repository defaults for module repositories A new PowerShell module repository defaults page defines the baseline contract for PSModule module repositories. It explains what belongs in the README, when placeholder repositories should say they are placeholders, and where generated command documentation should live. ## New: Required common files and managed-file ownership The standard now defines required repository files such as `README.md`, `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`, `SUPPORT.md`, `CODE_OF_CONDUCT.md`, `.github/dependabot.yml`, `.github/CODEOWNERS`, linter settings, and PSModule settings. It also explains why repository-local files are needed even when organization-level `.github` community files exist, and points to Distributor as the preferred managed-file mechanism. ## New: Supply-chain defaults use Dependabot Module repositories are expected to include Dependabot configuration for GitHub Actions and PowerShell dependencies. This makes dependency maintenance and supply-chain review part of the default repository contract. ## Changed: README pages are concise start pages Implemented module READMEs should answer what the module is, why it matters, how to install it, how it works at a high level, and where generated documentation lives. The capabilities section is a short discovery showcase, not command reference duplication. ## Changed: Product documentation belongs in generated docs or docs folders PowerShell modules should keep detailed product documentation in generated command help and, when needed, a `docs/` documentation surface published through GitHub Pages or the initiative's module documentation site. ## Changed: Installation guidance uses PSResourceGet New module repository documentation should use `Install-PSResource`. `Install-Module` is only retained for legacy or historical context where changing it would misrepresent the referenced system. ## Technical Details - Adds `src/docs/PowerShell/Modules/Repository-Defaults.md`. - Adds the page to the Zensical navigation in `src/zensical.toml`. - Adds a link from `src/docs/PowerShell/Modules/index.md`. - Documents the current Distributor subscription model plus the desired global and mandatory file-set direction from `PSModule/Distributor#4` and `PSModule/Distributor#5`.
1 parent b2e7ab3 commit 509c752

3 files changed

Lines changed: 310 additions & 0 deletions

File tree

‎src/docs/PowerShell/Modules/Repository-Defaults.md‎

Lines changed: 308 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,308 @@
1+
# PowerShell module repository defaults
2+
3+
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.
4+
5+
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.
6+
7+
## Scope
8+
9+
These defaults apply to repositories whose primary artifact is a PowerShell module published through the PSModule framework.
10+
11+
They do not apply directly to:
12+
13+
- GitHub Action repositories such as `Build-PSModule`, `Invoke-Pester`, or `Publish-PSModule`.
14+
- Documentation repositories such as `PSModule/docs`.
15+
- Template repositories other than `Template-PSModule`.
16+
- Test, archive, service, or infrastructure repositories that are not published as module artifacts.
17+
18+
Each initiative should keep its own repository standards in its central documentation repository. For the PSModule organization, this repository is the source of truth.
19+
20+
## Repository creation
21+
22+
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.
23+
24+
After creating the repository:
25+
26+
1. Replace template tokens such as `{{ NAME }}` and `{{ DESCRIPTION }}`.
27+
2. Remove scaffold functions, tests, and examples that do not represent the module.
28+
3. Set repository metadata and custom properties.
29+
4. Confirm the README answers the start-page questions and uses `Install-PSResource` for installation.
30+
5. Confirm required common files are present.
31+
6. Confirm `.github/PSModule.yml` only overrides defaults when the module needs different behavior.
32+
33+
## Required repository metadata
34+
35+
Each module repository should have:
36+
37+
- A concise GitHub repository description that starts with or clearly says `A PowerShell module ...`.
38+
- `RepoType: Module` as the repository custom property.
39+
- Topics that help users find the module, when relevant.
40+
- Branch protection and workflow requirements inherited from organization defaults.
41+
- `main` as the default branch unless there is a documented legacy reason.
42+
43+
The repository description is used as a short landing-page summary in documentation and automation. Keep it user-facing and avoid implementation details.
44+
45+
## Default branch and worktrees
46+
47+
Use `main` for active module repositories. Legacy repositories that still use `master` should not be used as examples for new work.
48+
49+
Local work should use the organization worktree convention:
50+
51+
- The bare repository stays at the repository root.
52+
- `main/` tracks the default branch.
53+
- Feature worktrees use `<type>-<slug>` directories and `<type>/<slug>` branches.
54+
55+
For branch and worktree details, see [Git Worktrees](../../Ways-of-Working/Git-Worktrees.md).
56+
57+
## Default repository layout
58+
59+
Module repositories use the PSModule framework layout:
60+
61+
| Path | Default purpose |
62+
| ---- | --------------- |
63+
| `README.md` | Concise start page for the module. |
64+
| `LICENSE` | Repository license. PSModule module repositories default to MIT unless a different license is explicitly decided. |
65+
| `CONTRIBUTING.md` | Contribution workflow or a repository-level pointer to the organization contribution guide. |
66+
| `SECURITY.md` | Security support policy and private vulnerability reporting instructions. |
67+
| `SUPPORT.md` | Support expectations and where users ask for help. |
68+
| `CODE_OF_CONDUCT.md` | Community conduct expectations. |
69+
| `.github/PSModule.yml` | Module workflow configuration overrides. |
70+
| `.github/workflows/workflow.yml` | Reusable Process-PSModule workflow entry point. |
71+
| `.github/dependabot.yml` | Dependency and supply-chain update configuration. |
72+
| `.github/CODEOWNERS` | Ownership routing for reviews and protected areas. |
73+
| `.github/pull_request_template.md` | PR Manager-compatible pull request template. |
74+
| `.gitattributes` | Git line-ending and file handling defaults. |
75+
| `.gitignore` | Shared ignore rules. |
76+
| `src/` | Module source compiled into the shipped artifact. |
77+
| `src/functions/public/` | Exported commands, grouped by domain. |
78+
| `src/functions/private/` | Internal helper commands, grouped by domain. |
79+
| `src/classes/public/` | Public classes that are part of the user-facing model. |
80+
| `src/classes/private/` | Internal implementation classes. |
81+
| `src/data/` | Static module data that ships with the module. |
82+
| `examples/` | Realistic user scenarios, not copies of command help. |
83+
| `docs/` | Product documentation source when the module needs documentation beyond generated command help. |
84+
| `tests/` | Pester tests and test data. |
85+
| `icon/` | Module icon assets. |
86+
87+
Detailed source layout rules live in [PowerShell module standard](Standards.md#repository-layout).
88+
89+
## Required common files
90+
91+
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:
92+
93+
- agents and humans need the files in the repository they are changing, not only inherited through GitHub UI behavior;
94+
- tools such as Dependabot, linters, CODEOWNERS, and release automation read repository-local files;
95+
- reviews need diffs against the actual managed file in the target repository;
96+
- repository-local files make the standard portable to other initiatives such as MSXOrg, where each initiative should define its own standards and managed files;
97+
- central fallback files in `PSModule/.github` do not provide a reliable enforcement or update workflow across all repositories.
98+
99+
Required baseline files for module repositories:
100+
101+
| File | Why it is required |
102+
| ---- | ------------------ |
103+
| `README.md` | Repository landing page and evergreen context for humans and agents. |
104+
| `LICENSE` | Clear legal terms for reuse, packaging, and redistribution. |
105+
| `CONTRIBUTING.md` | Shared contribution workflow and expectations. |
106+
| `SECURITY.md` | Private vulnerability reporting and latest-version support policy. |
107+
| `SUPPORT.md` | Support channel and issue-routing expectations. |
108+
| `CODE_OF_CONDUCT.md` | Community participation rules. |
109+
| `.github/dependabot.yml` | Supply-chain maintenance for GitHub Actions and PowerShell dependencies. |
110+
| `.github/CODEOWNERS` | Review routing for source, docs, and GitHub workflow files. |
111+
| `.github/pull_request_template.md` | Consistent PR Manager-style PR descriptions and change classification. |
112+
| `.github/release.yml` | Release-note and changelog categorization where the repository creates GitHub releases. |
113+
| `.github/PSModule.yml` | Module workflow defaults and overrides. |
114+
| `.github/linters/.markdown-lint.yml` | Markdown linting defaults. |
115+
| `.github/linters/.powershell-psscriptanalyzer.psd1` | PSScriptAnalyzer defaults. |
116+
| `.gitattributes` | Git attribute defaults. |
117+
| `.gitignore` | Shared ignore rules. |
118+
119+
Repositories can add local files, but they should not remove these baseline files unless the repository is explicitly outside the module standard.
120+
121+
## Managed file distribution
122+
123+
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.
124+
125+
The current Distributor model is subscription-based:
126+
127+
- `Type` is an organization repository custom property that maps a repository to a type folder such as `Module` or `Action`.
128+
- `SubscribeTo` is an organization repository custom property that selects file sets such as `dependabot.yml`, `Linter Settings`, `PSModule Settings`, `CODEOWNERS`, `License`, `.gitattributes`, and `.gitignore`.
129+
- Sync changes are delivered through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request.
130+
- 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.
131+
- Removing a file from a Distributor file set does not delete the previously distributed file from target repositories; cleanup is explicit.
132+
133+
Two follow-up Distributor capabilities define the desired direction:
134+
135+
- **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.
136+
- **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.
137+
138+
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.
139+
140+
## Supply-chain defaults
141+
142+
Every module repository must include `.github/dependabot.yml`. Dependabot is part of the repository supply-chain control, not an optional convenience.
143+
144+
Module repositories should configure at least:
145+
146+
```yaml
147+
version: 2
148+
updates:
149+
- package-ecosystem: "github-actions"
150+
directory: "/"
151+
schedule:
152+
interval: "weekly"
153+
labels:
154+
- "dependencies"
155+
- "github-actions"
156+
157+
- package-ecosystem: "powershell"
158+
directory: "/"
159+
schedule:
160+
interval: "weekly"
161+
labels:
162+
- "dependencies"
163+
- "powershell"
164+
```
165+
166+
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.
167+
168+
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.
169+
170+
## README default
171+
172+
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.
173+
174+
The README answers these questions, in this order:
175+
176+
| Question | Module README responsibility |
177+
| --- | --- |
178+
| What is it? | Name the module and define its scope in one short paragraph. |
179+
| Why should I care? | State the value or kind of task the module makes easier. |
180+
| How do I get it? | Show the PowerShell Gallery install and import commands. |
181+
| How does it work? | Show one to three representative capabilities or usage examples. |
182+
| How do I get more info? | Link to generated module documentation and PowerShell help. |
183+
184+
Module installation examples must use PSResourceGet:
185+
186+
```powershell
187+
Install-PSResource -Name <ModuleName>
188+
```
189+
190+
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.
191+
192+
For implemented modules, use this shape:
193+
194+
````markdown
195+
# <ModuleName>
196+
197+
<One short paragraph describing what the module is and why it is useful.>
198+
199+
## Installation
200+
201+
Install the module from the PowerShell Gallery:
202+
203+
```powershell
204+
Install-PSResource -Name <ModuleName>
205+
Import-Module -Name <ModuleName>
206+
```
207+
208+
## Capabilities
209+
210+
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.
211+
212+
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.
213+
214+
```powershell
215+
# Replace this with a real example that demonstrates the module's value.
216+
Get-Command -Module <ModuleName>
217+
```
218+
219+
## Documentation
220+
221+
Documentation is published at [psmodule.io/<ModuleName>](https://psmodule.io/<ModuleName>/).
222+
223+
Use PowerShell help and command discovery for module details:
224+
225+
```powershell
226+
Get-Command -Module <ModuleName>
227+
Get-Help -Name 'CommandName' -Examples
228+
```
229+
````
230+
231+
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.
232+
233+
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.
234+
235+
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.
236+
237+
## Placeholder and in-progress repositories
238+
239+
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.
240+
241+
Use this shape for placeholder repositories:
242+
243+
````markdown
244+
# <ModuleName>
245+
246+
<One sentence describing what the module is intended to become.>
247+
248+
## Status
249+
250+
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.
251+
252+
## Documentation
253+
254+
When this module is implemented, command details should live in PowerShell help and generated documentation rather than being duplicated in this README.
255+
````
256+
257+
Use the same pattern for in-progress modules with stub commands, but name the stub honestly:
258+
259+
```markdown
260+
This repository is currently in progress. The current `<CommandName>` command is a stub and throws `NotImplementedException`, so there are no supported conversion commands or usage examples to document yet.
261+
```
262+
263+
## README validation
264+
265+
Before opening a README-only PR, check that the README follows the default and does not contain leftover scaffolding:
266+
267+
```powershell
268+
Select-String -Path README.md -SimpleMatch -Pattern 'Greet-Entity', 'PSModuleTemplate', 'YourModuleName'
269+
Select-String -Path README.md -SimpleMatch -Pattern '{{ NAME }}', '{{ DESCRIPTION }}'
270+
Select-String -Path README.md -Pattern '^## Commands$'
271+
git diff --check -- README.md
272+
```
273+
274+
`Template-PSModule` is the exception: it intentionally keeps `{{ NAME }}` and `{{ DESCRIPTION }}` tokens because those are template inputs.
275+
276+
## Documentation ownership
277+
278+
Command details belong in comment-based help and generated documentation. The README can showcase capability, then points to those sources for reference detail.
279+
280+
Use these defaults:
281+
282+
- Command synopsis, parameters, examples, links, and outputs live in comment-based help.
283+
- Group overview pages live next to public command groups in `src/functions/public/<Group>/<Group>.md`.
284+
- Realistic end-to-end scenarios live in `examples/`.
285+
- Product docs beyond generated command help live under `docs/` and publish through GitHub Pages or the initiative's module documentation site.
286+
- README capability examples are short, representative, and user-facing.
287+
- README pages stay short and stable.
288+
289+
This keeps the repository landing page readable and prevents drift between README content, PowerShell help, and generated documentation.
290+
291+
## Release and PR defaults
292+
293+
Module repositories use the Process-PSModule workflow. Version and release behavior is driven by PR labels and workflow settings.
294+
295+
Default expectations:
296+
297+
- `Major`, `Minor`, `Patch`, and `Prerelease` labels determine release behavior.
298+
- Documentation-only README standardization PRs use the `Docs`/`NoRelease` behavior when available.
299+
- Source changes under `src/` are module-impacting and should trigger the full module workflow.
300+
- README and documentation changes should update the site without pretending to be module API changes.
301+
302+
See [Versioning](Versioning.md) for semantic version rules and [PowerShell module standard](Standards.md#cicd-pipeline) for the Process-PSModule pipeline.
303+
304+
## Template maintenance
305+
306+
`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.
307+
308+
The template README may contain tokens, but generated module repositories should not keep them after the initial setup commit.

‎src/docs/PowerShell/Modules/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,7 @@ The template ships with placeholder files to illustrate the expected layout —
2020

2121
Version increments are driven by PR labels (`Major`, `Minor`, `Patch`, `Prerelease`), and the `RepoType: Module` custom property integrates each repository with organization-wide tooling.
2222

23+
- **[Repository Defaults](Repository-Defaults.md)** — Required repository defaults for PSModule PowerShell module repos, including README shape, placeholder handling, metadata, and documentation ownership.
2324
- **[Standards](Standards.md)** — Repository layout, naming, style, parameter design, comment-based help, and SOLID applied to PowerShell modules.
2425
- **[Test Specification](Test-Specification.md)** — How we write Pester tests: structure, hierarchy, and naming conventions.
2526
- **[Versioning](Versioning.md)** — How changes to the public interface determine the SemVer version bump.

‎src/zensical.toml‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -33,6 +33,7 @@ nav = [
3333
]},
3434
{"Modules" = [
3535
"PowerShell/Modules/index.md",
36+
{"Repository Defaults" = "PowerShell/Modules/Repository-Defaults.md"},
3637
{"Standards" = "PowerShell/Modules/Standards.md"},
3738
{"Test Specification" = "PowerShell/Modules/Test-Specification.md"},
3839
{"Versioning" = "PowerShell/Modules/Versioning.md"},

0 commit comments

Comments
 (0)