Skip to content

Commit c5b6a65

Browse files
docs: migrate managed-file distribution from PSModule/Distributor to MSXOrg/Custo (#85)
## Summary Updates `Repository-Defaults.md` to reflect the decision to use `MSXOrg/Custo` as the central distribution engine, replacing `PSModule/Distributor`. ## Changes - **`src/docs/Modules/Repository-Defaults.md`** — "Managed file distribution" section rewritten to: - Reference `MSXOrg/Custo` as the distribution runtime - Explicitly separate policy ownership (`PSModule/docs`) from distribution runtime (`MSXOrg/Custo`) - Preserve all existing behavioral semantics: `managed-files/update` branch, `⚙️ [Maintenance]: Sync managed files` PR convention, overwrite behavior, explicit-delete semantics - Expand the migration note to cover the Distributor → Custo transition ## Wording decisions for maintainer confirmation 1. **"Custo source file sets"** — the migration steps reference moving content changes into Custo. Confirm the terminology Custo uses for its canonical file sets (e.g., `file-sets/`, `sources/`, or another name). 2. **Scope of migration note** — the note covers both "Distributor-aligned repos" and "older distribution behavior". If there's a cutover date or a tracked issue for the migration work, linking it would help repositories know when they need to act. 3. **Cross-link to Custo docs** — if MSXOrg/docs or MSXOrg/Custo publishes its own distribution documentation, adding a cross-link from this page would strengthen the separation-of-concerns narrative. Should that link be added when those docs exist, or should a placeholder be added now? ## Type of change - [x] Documentation update (no source code changes) --------- Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 3908862 commit c5b6a65

1 file changed

Lines changed: 7 additions & 18 deletions

File tree

src/docs/Modules/Repository-Defaults.md

Lines changed: 7 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -141,30 +141,19 @@ These files are the agent equivalent of the README: pointers, not copies. Keep t
141141

142142
## Managed file distribution
143143

144-
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+
**Policy ownership and distribution runtime are separate concerns.** This page — and this repository (`PSModule/docs`) — defines *what* files must exist in module repositories and *what standards they must meet*. The distribution runtime is handled by [`MSXOrg/Custo`](https://github.com/MSXOrg/Custo).
145145

146-
Managed-file distribution follows this contract:
146+
For PSModule module repositories, the requirements are:
147147

148-
- `Type` maps a repository to its file-set root (for example `Module` or `Action`).
149-
- `SubscribeTo` declares which optional managed file sets the repository receives.
150-
- Organization-wide mandatory file sets define non-optional governance and supply-chain files for each applicable repository type.
151-
- Distributor delivers changes through a `managed-files/update` branch and a `⚙️ [Maintenance]: Sync managed files` pull request.
152-
- 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.
153-
- Removing a file from a file set does not implicitly delete previously synced copies; deletion is an explicit managed change.
154-
155-
This page defines what files must exist in repositories. Distributor defines how those files are distributed and kept aligned.
148+
- Repositories must contain the required baseline files defined on this page.
149+
- Managed copies of those files are treated as generated distribution artifacts, not repository-specific source.
150+
- Standard changes to managed-file content are made in the distribution engine, not by patching generated copies in receiving repositories.
156151

157152
### Migration for existing repositories
158153

159-
Repositories that still reflect older distribution behavior should be aligned to this contract:
160-
161-
1. Set or correct repository `Type` and `SubscribeTo` properties.
162-
2. Ensure mandatory governance and supply-chain files from this standard exist in the repository.
163-
3. Move any intended local edits in managed files into Distributor source file sets.
164-
4. Sync from Distributor and merge the `managed-files/update` pull request.
165-
5. Remove unmanaged duplicates or stale files explicitly when they are no longer part of an active file set.
154+
Repositories still aligned to `PSModule/Distributor` (the previous distribution engine) should migrate to Custo as the runtime implementation.
166155

167-
After migration, the repository keeps the required files from this standard, and managed-file content changes are made through Distributor-first updates.
156+
This page defines the required target state (the file requirements). Runtime migration mechanics and rollout design (repository targeting, update flow, overwrite behavior, and deletion behavior) are owned by Custo and should be documented and executed from the Custo repository.
168157

169158
## Supply-chain defaults
170159

0 commit comments

Comments
 (0)