diff --git a/src/docs/Modules/Module-Types.md b/src/docs/Modules/Module-Types.md index be97843..9a93e42 100644 --- a/src/docs/Modules/Module-Types.md +++ b/src/docs/Modules/Module-Types.md @@ -103,4 +103,4 @@ The `Hashtable` module demonstrates the full set: `ConvertFrom-Hashtable`, `Conv ## Where this connects - [PowerShell module standard](Standards.md): layout, private functions, and the mandatory context parameter. -- [Repository Defaults](Repository-Defaults.md): repository files, README shape, and agent onboarding. +- [Repository Standard](Repository-Standard.md): repository files, README shape, and agent onboarding. diff --git a/src/docs/Modules/Process-PSModule/module-build-validation.md b/src/docs/Modules/Process-PSModule/module-build-validation.md index 032d19b..f3db03e 100644 --- a/src/docs/Modules/Process-PSModule/module-build-validation.md +++ b/src/docs/Modules/Process-PSModule/module-build-validation.md @@ -29,7 +29,7 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR Check: - - `README.md` still answers the start-page questions and reflects any user-visible behavior, prerequisites, or setup changes from [Repository Defaults](../Repository-Defaults.md#readme-default) + - `README.md` still answers the start-page questions and reflects any user-visible behavior, prerequisites, or setup changes from [Repository Standard](../Repository-Standard.md#readme-default) - the relevant public command-group overview page (`src/functions/public//.md`) exists or is updated when the change affects that group's purpose or usage, per [PowerShell module standard](../Standards.md#repository-layout) - any module-level documentation under `docs/` or other published surfaces is updated when the change adds or changes guidance that should not live only in comment-based help @@ -90,5 +90,5 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR - [PowerShell module standard](../Standards.md) - [Module types](../Module-Types.md) - [Module Anatomy](module-anatomy.md) -- [Repository Defaults](../Repository-Defaults.md) +- [Repository Standard](../Repository-Standard.md) - [MSX Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) diff --git a/src/docs/Modules/Repository-Defaults.md b/src/docs/Modules/Repository-Standard.md similarity index 85% rename from src/docs/Modules/Repository-Defaults.md rename to src/docs/Modules/Repository-Standard.md index 36dbf8e..1c4ce3d 100644 --- a/src/docs/Modules/Repository-Defaults.md +++ b/src/docs/Modules/Repository-Standard.md @@ -1,21 +1,23 @@ -# PowerShell module repository defaults +# Repository Standard -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. +This is the PSModule organization's Repository Standard. It applies to the PSModule organization and is the standard for PowerShell module repositories. 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. -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. +This standard operates at the same altitude as the [MSX Enterprise Repository Standard](https://msxorg.github.io/docs/Ways-of-Working/Repository-Standard/): MSX sets the enterprise-wide default, and this standard adds to and adjusts that default for PowerShell module repositories. Rules this standard does not change are inherited from the MSX default; where this standard adds or overrides a rule, it governs PowerShell module repositories. + +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 the repository standard for module repositories: files, metadata, README shape, release integration, placeholder handling, shared community files, and managed-file distribution. ## Scope -These defaults apply to repositories whose primary artifact is a PowerShell module published through the PSModule framework. +This standard applies to repositories whose primary artifact is a PowerShell module published through the PSModule framework. -They do not apply directly to: +It does not apply directly to: - GitHub Action repositories such as `Build-PSModule`, `Invoke-Pester`, or `Publish-PSModule`. - Documentation repositories such as `PSModule/docs`. - Template repositories other than `Template-PSModule`. - Test, archive, service, or infrastructure repositories that are not published as module artifacts. -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. +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 the module standard, and non-module repositories keep only the equivalent baseline appropriate to their own type. This repository, `PSModule/docs`, follows those two baseline expectations itself. Each initiative should keep its own repository standards in its central documentation repository. For the PSModule organization, this repository is the source of truth. @@ -70,14 +72,13 @@ Module repositories use the PSModule framework layout: | `CODE_OF_CONDUCT.md` | Community conduct expectations. | | `AGENTS.md` | Agent onboarding entry point. Points agents to the canonical guidance in `PSModule/docs`. | | `CLAUDE.md` | Claude Code entry point. Imports `AGENTS.md` so Claude reads the same instructions. | -| `.github/copilot-instructions.md` | VS Code and GitHub Copilot repository instructions. Points to the same documentation. | | `.github/PSModule.yml` | Module workflow configuration overrides. | | `.github/workflows/workflow.yml` | Reusable Process-PSModule workflow entry point. | -| `.github/dependabot.yml` | Dependency and supply-chain update configuration. | +| `.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. | | `.github/CODEOWNERS` | Ownership routing for reviews and protected areas. | -| `.github/pull_request_template.md` | PR Manager-compatible pull request template. | -| `.gitattributes` | Git line-ending and file handling defaults. | -| `.gitignore` | Shared ignore rules. | +| `.github/pull_request_template.md` | Scaffolds pull requests in the MSX PR Format (PR Manager) style — an icon + change-type + user-facing-outcome title, user-facing description sections, an optional technical-details block, and a related-issues block. | +| `.gitattributes` | Normalizes line endings and declares text/binary handling so the module can be developed and built consistently on Linux, macOS, and Windows. | +| `.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. | | `src/` | Module source compiled into the shipped artifact. | | `src/functions/public/` | Exported commands, grouped by domain. | | `src/functions/private/` | Internal helper commands, grouped by domain. | @@ -96,7 +97,7 @@ Detailed source layout rules live in [PowerShell module standard](Standards.md#r 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: - agents and humans need the files in the repository they are changing, not only inherited through GitHub UI behavior; -- tools such as Dependabot, linters, CODEOWNERS, and release automation read repository-local files; +- 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; - reviews need diffs against the actual managed file in the target repository; - repository-local files make the standard portable to other initiatives such as MSXOrg, where each initiative should define its own standards and managed files; - central fallback files in `PSModule/.github` do not provide a reliable enforcement or update workflow across all repositories. @@ -113,16 +114,12 @@ Required baseline files for module repositories: | `CODE_OF_CONDUCT.md` | Community participation rules. | | `AGENTS.md` | Cross-tool agent instructions pointing to the canonical guidance in `PSModule/docs`. | | `CLAUDE.md` | Claude Code entry point that imports `AGENTS.md`. | -| `.github/copilot-instructions.md` | VS Code and GitHub Copilot repository instructions pointing to the documentation. | -| `.github/dependabot.yml` | Supply-chain maintenance for GitHub Actions and PowerShell dependencies. | +| `.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. | | `.github/CODEOWNERS` | Review routing for source, docs, and GitHub workflow files. | -| `.github/pull_request_template.md` | Consistent PR Manager-style PR descriptions and change classification. | -| `.github/release.yml` | Release-note and changelog categorization where the repository creates GitHub releases. | +| `.github/pull_request_template.md` | Scaffolds pull requests in the MSX PR Format (PR Manager) style — an icon + change-type + user-facing-outcome title, user-facing description sections, an optional technical-details block, and a related-issues block. | | `.github/PSModule.yml` | Module workflow defaults and overrides. | -| `.github/linters/.markdown-lint.yml` | Markdown linting defaults. | -| `.github/linters/.powershell-psscriptanalyzer.psd1` | PSScriptAnalyzer defaults. | -| `.gitattributes` | Git attribute defaults. | -| `.gitignore` | Shared ignore rules. | +| `.gitattributes` | Normalizes line endings and declares text/binary handling so the module can be developed and built consistently on Linux, macOS, and Windows. | +| `.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. | Repositories can add local files, but they should not remove these baseline files unless the repository is explicitly outside the module standard. diff --git a/src/docs/Modules/index.md b/src/docs/Modules/index.md index d0e6baa..2bc52cd 100644 --- a/src/docs/Modules/index.md +++ b/src/docs/Modules/index.md @@ -10,7 +10,7 @@ This section is the local source of truth for: ## Sections -- [Repository Defaults](Repository-Defaults.md) +- [Repository Standard](Repository-Standard.md) - [Standards](Standards.md) - [Module types](Module-Types.md) - [Test Specification](Test-Specification.md) diff --git a/src/zensical.toml b/src/zensical.toml index edce6c5..917bee6 100644 --- a/src/zensical.toml +++ b/src/zensical.toml @@ -19,7 +19,7 @@ watch = ["includes"] nav = [ {"Modules" = [ "Modules/index.md", - {"Repository Defaults" = "Modules/Repository-Defaults.md"}, + {"Repository Standard" = "Modules/Repository-Standard.md"}, {"Standards" = "Modules/Standards.md"}, {"Module types" = "Modules/Module-Types.md"}, {"Test Specification" = "Modules/Test-Specification.md"},