Skip to content

Commit 9c41fb1

Browse files
Use centralized community policy defaults
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent f8d8941 commit 9c41fb1

2 files changed

Lines changed: 38 additions & 35 deletions

File tree

.github/plugin/psmodule/skills/psmodule-repository-audit/SKILL.md

Lines changed: 13 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -77,13 +77,19 @@ overwrite an established repository.
7777
| Creation scaffold | Use for new repositories. Do not overwrite established module source, tests, examples, or content. |
7878
| Repository-owned addition | Preserve it unless it violates a governing standard or breaks the framework contract. |
7979

80-
Treat `.github/CONTRIBUTING.md`, `.github/CODE_OF_CONDUCT.md`,
81-
`.github/SECURITY.md`, `.github/SUPPORT.md`, governance files, caller workflows,
82-
linter settings, dependency configuration, agent entry points, and
83-
documentation-site defaults as template-owned or parameterized unless the
84-
template or PSModule standard says otherwise. Treat `src/`, established
85-
`tests/`, `examples/`, documentation content, and module-specific assets as
86-
repository-owned after creation.
80+
Treat `.github/CONTRIBUTING.md`, governance files, caller workflows, linter
81+
settings, dependency configuration, agent entry points, and documentation-site
82+
defaults as template-owned or parameterized unless the template or PSModule
83+
standard says otherwise. Treat `src/`, established `tests/`, `examples/`,
84+
documentation content, and module-specific assets as repository-owned after
85+
creation.
86+
87+
Do not require `.github/CODE_OF_CONDUCT.md`, `.github/SECURITY.md`, or
88+
`.github/SUPPORT.md`. These policies are centrally provided by
89+
`PSModule/.github`; a target may carry a repository-local copy only as a
90+
documented policy override. Do not require `.github/release.yml`: current
91+
Process-PSModule releases do not use GitHub's built-in release configuration.
92+
Report an undocumented local release configuration as stale drift.
8793

8894
Report a root-level duplicate of a community file as drift. GitHub recognizes
8995
these files under `.github/`, which is their canonical PSModule location.

docs/content/reference/repository-standard.md

Lines changed: 25 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -103,16 +103,12 @@ Module repositories use the PSModule framework layout:
103103
| `README.md` | Concise start page for the module. |
104104
| `LICENSE` | Repository license. PSModule module repositories default to MIT unless a different license is explicitly decided. |
105105
| `.github/CONTRIBUTING.md` | Self-contained contribution workflow for this repository. Does not rely on an organization-level fallback. |
106-
| `.github/SECURITY.md` | Security support policy and private vulnerability reporting instructions. |
107-
| `.github/SUPPORT.md` | Support expectations and where users ask for help. |
108-
| `.github/CODE_OF_CONDUCT.md` | Community conduct expectations. |
109106
| `AGENTS.md` | Agent onboarding entry point. Points agents to the canonical guidance at `https://psmodule.io/Process-PSModule/`. |
110107
| `.claude/CLAUDE.md` | Claude Code entry point. Imports the root `AGENTS.md`. |
111108
| `.github/copilot-instructions.md` | Route for Copilot surfaces that do not read `AGENTS.md` directly. |
112109
| `.github/PSModule.yml` | Module workflow configuration overrides. |
113110
| `.github/workflows/Process-PSModule.yml` | Caller workflow that runs the module's CI/CD by calling the shared Process-PSModule workflow. |
114111
| `.github/zensical.toml` | Canonical generated-site configuration copied from `Template-PSModule`. |
115-
| `.github/release.yml` | Release-note and changelog categorization for GitHub releases. |
116112
| `.github/linters/` | Linter configuration used by the framework's linting stage, including `.markdown-lint.yml` and `.powershell-psscriptanalyzer.psd1`. |
117113
| `.github/dependabot.yml` | Configures ecosystem-appropriate dependency-update pull requests. For PowerShell module repositories the `github-actions` ecosystem is expected; add any other ecosystems the module actually develops in. |
118114
| `.github/CODEOWNERS` | Ownership routing for reviews and protected areas. |
@@ -154,13 +150,13 @@ reference permitted by the MSX GitHub Actions standard.
154150

155151
## Required common files
156152

157-
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:
158-
159-
- agents and humans need the files in the repository they are changing, not only inherited through GitHub UI behavior;
160-
- tools such as Dependabot and CODEOWNERS read repository-local files — as do linters and release automation when the module uses those linters or generates releases;
161-
- reviews need diffs against the actual managed file in the target repository;
162-
- repository-local files make the standard portable to other initiatives such as MSXOrg, where each initiative should define its own standards and managed files;
163-
- central fallback files in `PSModule/.github` do not provide a reliable enforcement or update workflow across all repositories.
153+
Every module repository must carry the same baseline framework, governance, and
154+
automation files. The PSModule organization centrally manages the standard Code
155+
of Conduct, security policy, and support guidance in
156+
[`PSModule/.github`](https://github.com/PSModule/.github/tree/main/.github).
157+
GitHub surfaces those files for repositories that do not define local versions.
158+
Add a repository-local copy only when the repository intentionally deviates from
159+
the organization standard.
164160

165161
Required baseline files for module repositories:
166162

@@ -169,9 +165,6 @@ Required baseline files for module repositories:
169165
| `README.md` | Repository landing page and evergreen context for humans and agents. |
170166
| `LICENSE` | Clear legal terms for reuse, packaging, and redistribution. |
171167
| `.github/CONTRIBUTING.md` | Self-contained contribution workflow and expectations for this repository. |
172-
| `.github/SECURITY.md` | Private vulnerability reporting and latest-version support policy. |
173-
| `.github/SUPPORT.md` | Support channel and issue-routing expectations. |
174-
| `.github/CODE_OF_CONDUCT.md` | Community participation rules. |
175168
| `AGENTS.md` | Cross-tool agent instructions pointing to the canonical guidance at `https://psmodule.io/Process-PSModule/`. |
176169
| `.claude/CLAUDE.md` | Claude Code entry point that imports the root `AGENTS.md`. |
177170
| `.github/copilot-instructions.md` | Route to `AGENTS.md` for Copilot surfaces that need their own filename. |
@@ -182,17 +175,20 @@ Required baseline files for module repositories:
182175
| `.gitattributes` | Normalizes line endings and declares text/binary handling so the module can be developed and built consistently on Linux, macOS, and Windows. |
183176
| `.gitignore` | Ignores files that must never be committed, tailored to the PowerShell-module ecosystem: operating-system files, editor and developer-tooling files, PowerShell and Pester test-harness artifacts, and all local build outputs and files created during build and test. |
184177

185-
Repositories can add local files, but they should not remove these baseline files unless the repository is explicitly outside the module standard.
178+
`.github/release.yml` is not part of the baseline. Process-PSModule does not
179+
use GitHub's built-in release configuration; its release behavior is driven by
180+
the framework's release action and settings.
186181

187-
Each repository must stand on its own. It carries its own copy of every file above and does not depend on the organization `.github` fallback: that fallback is only surfaced in GitHub's web UI, and agents, linters, and local tooling do not read it.
182+
Repositories can add local files, but they should not remove the baseline files
183+
above unless the repository is explicitly outside the module standard.
188184

189-
Keep repository-local community health files together under `.github/`.
190-
GitHub discovers `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, and
191-
`SUPPORT.md` there, so root-level duplicates add no value and are not part of
192-
the PSModule layout. This is the PSModule initiative's explicit path override
193-
of the MSX repository default. `README.md`, `LICENSE`, and `AGENTS.md` remain
194-
at the repository root because they are repository entry points rather than
195-
community health files.
185+
Keep any repository-local community health overrides together under `.github/`.
186+
The organization-managed Code of Conduct, security policy, and support
187+
guidance do not need local copies. A local `CONTRIBUTING.md` remains part of the
188+
module baseline, and root-level duplicates of community files are not part of
189+
the PSModule layout. `README.md`, `LICENSE`, and `AGENTS.md` remain at the
190+
repository root because they are repository entry points rather than community
191+
health files.
196192

197193
## Agent onboarding files
198194

@@ -389,11 +385,12 @@ Retain upstream attribution and licensing context. Credit, acknowledgements, don
389385
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.
390386

391387
Do not add a community-file or policy link section by default. Readers can find
392-
standard files such as `LICENSE`, `.github/CONTRIBUTING.md`,
393-
`.github/SECURITY.md`, and `.github/CODE_OF_CONDUCT.md` through GitHub
394-
conventions and the repository file tree. Link them only when the module has an
395-
unusual rule the user must know before using it, or when it carries required
396-
upstream attribution.
388+
standard files such as `LICENSE` and `.github/CONTRIBUTING.md` through GitHub
389+
conventions and the repository file tree. The organization-managed Code of
390+
Conduct, security policy, and support guidance are provided by
391+
`PSModule/.github` unless the module overrides them locally. Link them only
392+
when the module has an unusual rule the user must know before using it, or when
393+
it carries required upstream attribution.
397394

398395
## Placeholder and in-progress repositories
399396

0 commit comments

Comments
 (0)