Skip to content

Commit 9971682

Browse files
MariusStorhaugMariusStorhaug
committed
Expand module repository defaults with managed file standards
1 parent 4c8ba2f commit 9971682

1 file changed

Lines changed: 104 additions & 4 deletions

File tree

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

Lines changed: 104 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
# PowerShell module repository defaults
22

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, and documentation are considered.
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.
44

5-
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.
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.
66

77
## Scope
88

@@ -26,8 +26,9 @@ After creating the repository:
2626
1. Replace template tokens such as `{{ NAME }}` and `{{ DESCRIPTION }}`.
2727
2. Remove scaffold functions, tests, and examples that do not represent the module.
2828
3. Set repository metadata and custom properties.
29-
4. Confirm the README reflects the module's actual status.
30-
5. Confirm `.github/PSModule.yml` only overrides defaults when the module needs different behavior.
29+
4. Confirm the README reflects the module's actual status 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.
3132

3233
## Required repository metadata
3334

@@ -60,8 +61,18 @@ Module repositories use the PSModule framework layout:
6061
| Path | Default purpose |
6162
| ---- | --------------- |
6263
| `README.md` | Concise landing page for the repository. |
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. |
6369
| `.github/PSModule.yml` | Module workflow configuration overrides. |
6470
| `.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. |
6576
| `src/` | Module source compiled into the shipped artifact. |
6677
| `src/functions/public/` | Exported commands, grouped by domain. |
6778
| `src/functions/private/` | Internal helper commands, grouped by domain. |
@@ -74,10 +85,99 @@ Module repositories use the PSModule framework layout:
7485

7586
Detailed source layout rules live in [PowerShell module standard](Standards.md#repository-layout).
7687

88+
## Required common files
89+
90+
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:
91+
92+
- agents and humans need the files in the repository they are changing, not only inherited through GitHub UI behavior;
93+
- tools such as Dependabot, linters, CODEOWNERS, and release automation read repository-local files;
94+
- reviews need diffs against the actual managed file in the target repository;
95+
- repository-local files make the standard portable to other initiatives such as MSXOrg, where each initiative should define its own standards and managed files;
96+
- central fallback files in `PSModule/.github` do not provide a reliable enforcement or update workflow across all repositories.
97+
98+
Required baseline files for module repositories:
99+
100+
| File | Why it is required |
101+
| ---- | ------------------ |
102+
| `README.md` | Repository landing page and evergreen context for humans and agents. |
103+
| `LICENSE` | Clear legal terms for reuse, packaging, and redistribution. |
104+
| `CONTRIBUTING.md` | Shared contribution workflow and expectations. |
105+
| `SECURITY.md` | Private vulnerability reporting and latest-version support policy. |
106+
| `SUPPORT.md` | Support channel and issue-routing expectations. |
107+
| `CODE_OF_CONDUCT.md` | Community participation rules. |
108+
| `.github/dependabot.yml` | Supply-chain maintenance for GitHub Actions and PowerShell dependencies. |
109+
| `.github/CODEOWNERS` | Review routing for source, docs, and GitHub workflow files. |
110+
| `.github/pull_request_template.md` | Consistent PR Manager-style PR descriptions and change classification. |
111+
| `.github/release.yml` | Release-note and changelog categorization where the repository creates GitHub releases. |
112+
| `.github/PSModule.yml` | Module workflow defaults and overrides. |
113+
| `.github/linters/.markdown-lint.yml` | Markdown linting defaults. |
114+
| `.github/linters/.powershell-psscriptanalyzer.psd1` | PSScriptAnalyzer defaults. |
115+
| `.gitattributes` | Git attribute defaults. |
116+
| `.gitignore` | Shared ignore rules. |
117+
118+
Repositories can add local files, but they should not remove these baseline files unless the repository is explicitly outside the module standard.
119+
120+
## Managed file distribution
121+
122+
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.
123+
124+
The current Distributor model is subscription-based:
125+
126+
- `Type` is an organization repository custom property that maps a repository to a type folder such as `Module` or `Action`.
127+
- `SubscribeTo` is an organization repository custom property that selects file sets such as `dependabot.yml`, `Linter Settings`, `PSModule Settings`, `CODEOWNERS`, `License`, `.gitattributes`, and `.gitignore`.
128+
- Sync changes are delivered through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request.
129+
- 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.
130+
- Removing a file from a Distributor file set does not delete the previously distributed file from target repositories; cleanup is explicit.
131+
132+
Two follow-up Distributor capabilities define the desired direction:
133+
134+
- **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.
135+
- **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.
136+
137+
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.
138+
139+
## Supply-chain defaults
140+
141+
Every module repository must include `.github/dependabot.yml`. Dependabot is part of the repository supply-chain control, not an optional convenience.
142+
143+
Module repositories should configure at least:
144+
145+
```yaml
146+
version: 2
147+
updates:
148+
- package-ecosystem: "github-actions"
149+
directory: "/"
150+
schedule:
151+
interval: "weekly"
152+
labels:
153+
- "dependencies"
154+
- "github-actions"
155+
156+
- package-ecosystem: "powershell"
157+
directory: "/"
158+
schedule:
159+
interval: "weekly"
160+
labels:
161+
- "dependencies"
162+
- "powershell"
163+
```
164+
165+
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.
166+
167+
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.
168+
77169
## README default
78170
79171
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.
80172
173+
Module installation examples must use PSResourceGet:
174+
175+
```powershell
176+
Install-PSResource -Name <ModuleName>
177+
```
178+
179+
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.
180+
81181
For implemented modules, use this shape:
82182

83183
````markdown

0 commit comments

Comments
 (0)