You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Everything is a work in progress and can be updated and improved.
6
+
If you find a problem, fix it if it's small; otherwise, register it as an issue in the respective repo.
7
+
8
+
## Install the ecosystem
9
+
10
+
1. Create a folder in the home directory called `.msx/PSModule`:
11
+
2. Clone the ecosystem locally:
12
+
1.<https://github.com/PSModule/docs> — requires PRs to be updated.
13
+
- Clone as bare and use worktrees.
14
+
- Create a worktree for all branches - worktree = name of the branch.
15
+
2.<https://github.com/PSModule/memory> — work directly towards main.
16
+
- Simple clone, only main.
17
+
18
+
To install:
19
+
Clone the repos in the users home folder under a sub-folder named `.msx/PSModule`.
20
+
- Set configs locally to each of these repos using the GitHub username and email.
21
+
22
+
## Working with the ecosystem
23
+
24
+
1. Get to know this repo first:
25
+
-[README](README.md) for what this repository is and how it builds.
26
+
-[CONTRIBUTING](CONTRIBUTING.md) for how to contribute and the review process.
27
+
2. Read the `.msx/PSModule/main/docs` - start with the index to get an overview of what is here.
28
+
3. Read the `.msx/PSModule/memory` - start with the index to get an overview of what is here. Use this while working - commit your memories here for work inside the PSModule organization.
29
+
4. While working with the code, do small micro commits and push on every commit. This will make it easier to review and merge your changes.
Copy file name to clipboardExpand all lines: src/docs/Modules/Repository-Defaults.md
+42-14Lines changed: 42 additions & 14 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
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
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.
5
+
The implementation standard still lives in [PowerShell module standard](Standards.md). Type-specific conventions for integration (API) and data modules live in [Module types](Module-Types.md). This page covers repository defaults: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution.
6
6
7
7
## Scope
8
8
@@ -15,6 +15,8 @@ They do not apply directly to:
15
15
- Template repositories other than `Template-PSModule`.
16
16
- Test, archive, service, or infrastructure repositories that are not published as module artifacts.
17
17
18
+
Two baseline expectations still apply to every PSModule repository, including the types listed above. Each repository stands on its own: it carries its own governance and community files instead of relying on the organization `.github` fallback, and each repository ships the [agent onboarding files](#agent-onboarding-files) so an agent can work in it without prior context. What differs by type is the concrete file set and layout: the required files, README shape, and framework wiring on the rest of this page are module defaults, and non-module repositories keep only the equivalent baseline appropriate to their own type. This repository, `PSModule/docs`, follows those two baseline expectations itself.
19
+
18
20
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
21
20
22
## Repository creation
@@ -62,10 +64,13 @@ Module repositories use the PSModule framework layout:
62
64
| ---- | --------------- |
63
65
|`README.md`| Concise start page for the module. |
64
66
|`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. |
67
+
|`CONTRIBUTING.md`|Self-contained contribution workflow for this repository. Does not rely on an organization-level fallback. |
66
68
|`SECURITY.md`| Security support policy and private vulnerability reporting instructions. |
67
69
|`SUPPORT.md`| Support expectations and where users ask for help. |
68
70
|`CODE_OF_CONDUCT.md`| Community conduct expectations. |
71
+
|`AGENTS.md`| Agent onboarding entry point. Points agents to the canonical guidance in `PSModule/docs`. |
72
+
|`CLAUDE.md`| Claude Code entry point. Imports `AGENTS.md` so Claude reads the same instructions. |
73
+
|`.github/copilot-instructions.md`| VS Code and GitHub Copilot repository instructions. Points to the same documentation. |
|`.github/dependabot.yml`| Dependency and supply-chain update configuration. |
@@ -102,10 +107,13 @@ Required baseline files for module repositories:
102
107
| ---- | ------------------ |
103
108
|`README.md`| Repository landing page and evergreen context for humans and agents. |
104
109
|`LICENSE`| Clear legal terms for reuse, packaging, and redistribution. |
105
-
|`CONTRIBUTING.md`|Shared contribution workflow and expectations. |
110
+
|`CONTRIBUTING.md`|Self-contained contribution workflow and expectations for this repository. |
106
111
|`SECURITY.md`| Private vulnerability reporting and latest-version support policy. |
107
112
|`SUPPORT.md`| Support channel and issue-routing expectations. |
108
113
|`CODE_OF_CONDUCT.md`| Community participation rules. |
114
+
|`AGENTS.md`| Cross-tool agent instructions pointing to the canonical guidance in `PSModule/docs`. |
115
+
|`CLAUDE.md`| Claude Code entry point that imports `AGENTS.md`. |
116
+
|`.github/copilot-instructions.md`| VS Code and GitHub Copilot repository instructions pointing to the documentation. |
109
117
|`.github/dependabot.yml`| Supply-chain maintenance for GitHub Actions and PowerShell dependencies. |
110
118
|`.github/CODEOWNERS`| Review routing for source, docs, and GitHub workflow files. |
111
119
|`.github/pull_request_template.md`| Consistent PR Manager-style PR descriptions and change classification. |
@@ -118,24 +126,44 @@ Required baseline files for module repositories:
118
126
119
127
Repositories can add local files, but they should not remove these baseline files unless the repository is explicitly outside the module standard.
120
128
129
+
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.
130
+
131
+
## Agent onboarding files
132
+
133
+
Every repository must be usable by an agent that has never seen it before, without special configuration. Each repository carries its own agent entry points that point to the authoritative documentation instead of restating it:
134
+
135
+
-`AGENTS.md`: the cross-tool entry point, read by the GitHub Copilot coding agent, VS Code, and other AGENTS.md-aware tools. It names what the repository is in a line or two and points to the canonical agent guidance in [`PSModule/docs`](https://github.com/PSModule/docs).
136
+
-`CLAUDE.md`: a thin file that imports `AGENTS.md` with `@AGENTS.md` so Claude Code reads the same instructions. Claude-specific notes, if any, go below the import.
137
+
-`.github/copilot-instructions.md`: repository instructions for VS Code and GitHub Copilot that point to the same documentation.
138
+
139
+
These files are the agent equivalent of the README: pointers, not copies. Keep them short so the linked documentation stays the single source of truth. Like the other governance files, they live in the repository itself so it can stand on its own.
140
+
121
141
## Managed file distribution
122
142
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.
143
+
Shared repository files are managed through [`PSModule/Distributor`](https://github.com/PSModule/Distributor). Distributor is the source of truth for managed file content and file-set membership.
144
+
145
+
Managed-file distribution follows this contract:
146
+
147
+
-`Type` maps a repository to its file-set root (for example `Module` or `Action`).
148
+
-`SubscribeTo` declares which optional managed file sets the repository receives.
149
+
- Organization-wide mandatory file sets define non-optional governance and supply-chain files for each applicable repository type.
150
+
- Distributor delivers changes through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request.
151
+
- Receiving repositories treat managed files as generated artifacts from Distributor. Local edits in the receiving repository are replaced on the next sync and must be made in Distributor instead.
152
+
- Removing a file from a file set does not implicitly delete previously synced copies; deletion is an explicit managed change.
124
153
125
-
The current Distributor model is subscription-based:
154
+
This page defines what files must exist in repositories. Distributor defines how those files are distributed and kept aligned.
126
155
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.
156
+
### Migration for existing repositories
132
157
133
-
Two follow-up Distributor capabilities define the desired direction:
158
+
Repositories that still reflect older distribution behavior should be aligned to this contract:
134
159
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.
160
+
1. Set or correct repository `Type` and `SubscribeTo` properties.
161
+
2. Ensure mandatory governance and supply-chain files from this standard exist in the repository.
162
+
3. Move any intended local edits in managed files into Distributor source file sets.
163
+
4. Sync from Distributor and merge the `managed-files/update` pull request.
164
+
5. Remove unmanaged duplicates or stale files explicitly when they are no longer part of an active file set.
137
165
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.
166
+
After migration, the repository keeps the required files from this standard, and managed-file content changes are made through Distributor-first updates.
0 commit comments