diff --git a/.github/actions/update-index/src/Helper.psm1 b/.github/actions/update-index/src/Helper.psm1 index 627e3672..3b768321 100644 --- a/.github/actions/update-index/src/Helper.psm1 +++ b/.github/actions/update-index/src/Helper.psm1 @@ -831,7 +831,7 @@ function Update-ModuleList { $moduleRepos = $Repos | Where-Object { $_.Type -eq 'Module' -and $_.Owner -eq 'PSModule' } | Sort-Object Name - $catalogFolderPath = Join-Path 'docs\content\Modules\Catalog' 'Repositories' + $catalogFolderPath = Join-Path 'docs\content\Modules' 'Repositories' if (-not (Test-Path $catalogFolderPath)) { Write-Host "Creating catalog folder [$catalogFolderPath]" $null = New-Item -Path $catalogFolderPath -ItemType Directory @@ -921,7 +921,7 @@ function Update-ModuleList { LogGroup 'Write module catalog table to docs index' { $moduleTable = $moduleCatalogTableTemplate.Replace('{{ ROWS }}', $moduleTableRows.TrimEnd()) - Update-MDSection -Path '.\docs\content\Modules\Catalog\index.md' -Name 'MODULE_CATALOG' -Content $moduleTable + Update-MDSection -Path '.\docs\content\Modules\index.md' -Name 'MODULE_CATALOG' -Content $moduleTable Write-Host 'Module catalog table update completed' } } diff --git a/.github/actions/update-index/templates/module-catalog/v2-table.html b/.github/actions/update-index/templates/module-catalog/v2-table.html index 2429e73b..dcd2623f 100644 --- a/.github/actions/update-index/templates/module-catalog/v2-table.html +++ b/.github/actions/update-index/templates/module-catalog/v2-table.html @@ -3,10 +3,10 @@ - - - - - + + + + + {{ ROWS }}
NameVersionProcess versionIssuesPull requestsStarsVersionProcess versionIssuesPull requestsStars
diff --git a/.github/actions/update-index/tests/Update-Index.Helpers.Tests.ps1 b/.github/actions/update-index/tests/Update-Index.Helpers.Tests.ps1 new file mode 100644 index 00000000..dfa266d1 --- /dev/null +++ b/.github/actions/update-index/tests/Update-Index.Helpers.Tests.ps1 @@ -0,0 +1,59 @@ +[Diagnostics.CodeAnalysis.SuppressMessageAttribute( + 'PSUseDeclaredVarsMoreThanAssignments', + '', + Justification = 'The temporary path is assigned before assertions and cleanup.' +)] +[CmdletBinding()] +param() + +BeforeAll { + Import-Module -Name (Join-Path -Path $PSScriptRoot -ChildPath '../src/Helper.psm1') -Force +} + +Describe 'Update-ModuleList' { + Context 'catalog page at the Modules root' { + It 'Update-ModuleList - writes the catalog index and repository page to the new Modules paths' { + $testRoot = Join-Path ([System.IO.Path]::GetTempPath()) ("update-index-test-$([guid]::NewGuid())") + $modulesPath = Join-Path $testRoot 'docs/content/Modules' + $catalogIndexPath = Join-Path $modulesPath 'index.md' + New-Item -ItemType Directory -Path $modulesPath -Force | Out-Null + Set-Content -Path $catalogIndexPath -Value @( + '# Modules' + '' + '' + '' + ) + + try { + Push-Location $testRoot + InModuleScope Helper { + Mock Get-RepositoryVersion { '1.2.3' } + Mock Get-RepositoryReadmeContent { '# Example`nExample module summary.' } + Mock Get-MarkdownSummary { 'Example module summary.' } + Mock Get-WorkflowReference { 'v1.2.3' } + Mock Get-ProcessReferenceStatus { 'up-to-date' } + Mock Get-OpenItemCount { 0 } + + Update-ModuleList -Repos @( + [pscustomobject]@{ + Type = 'Module' + Owner = 'PSModule' + Name = 'Example' + Description = 'Example module.' + DefaultBranch = 'main' + Stars = 1 + } + ) + } + + $catalogContent = Get-Content -Path $catalogIndexPath -Raw + Test-Path (Join-Path $modulesPath 'Repositories/Example.md') | Should -BeTrue + $catalogContent | Should -Match '\./Repositories/Example\.md' + $catalogContent | Should -Match '\.\./assets/images/module-catalog/githubtags\.svg' + } finally { + Pop-Location + Remove-Item -LiteralPath $testRoot -Recurse -Force -ErrorAction SilentlyContinue + } + } + } +} diff --git a/.github/workflows/Test-Actions.yml b/.github/workflows/Test-Actions.yml index cfc4f9e8..08c857ed 100644 --- a/.github/workflows/Test-Actions.yml +++ b/.github/workflows/Test-Actions.yml @@ -36,6 +36,7 @@ jobs: run: | Install-PSResource -Name Pester -Version '[5.7.1,6.0.0)' -Repository PSGallery -TrustRepository Install-PSResource -Name PSSemVer -Repository PSGallery -TrustRepository + Install-PSResource -Name GitHub -Version '[0.43.1,0.44.0)' -Repository PSGallery -TrustRepository - name: Run action unit tests shell: pwsh diff --git a/AGENTS.md b/AGENTS.md index 44244354..1bc74e3d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,7 +15,7 @@ If you find a problem or improvement, fix if small; otherwise open an issue. Regarding repo structure, module source code, and how the Process-PSModule workflow works. For PSModule-specific build, layout, and process guidance: -- [Process-PSModule docs](https://psmodule.github.io/docs/Modules/Process-PSModule/) — +- [Process-PSModule docs](https://psmodule.io/docs/) — repository structure, module anatomy, and the build/test/pack/publish pipeline. - [Repository defaults](https://psmodule.github.io/docs/Modules/Repository-Defaults/) — the expected repository layout and required files. @@ -28,11 +28,11 @@ works. For PSModule-specific build, layout, and process guidance: For cross-cutting ways of working and standards: -- [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/) — +- [Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/) — how agents and humans collaborate in this ecosystem. -- [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) — contribution +- [Ways of Working](https://msx.no/docs/Ways-of-Working/) — contribution workflow, branching, PRs, issues. -- [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) — language-level +- [Coding Standards](https://msx.no/docs/Coding-Standards/) — language-level conventions. - [MSXOrg/memory](https://github.com/MSXOrg/memory) — durable agent working memory: gotchas, knowledge, and agent role notes. diff --git a/docs/content/Modules/Catalog/index.md b/docs/content/Modules/Catalog/index.md deleted file mode 100644 index 5db88f7b..00000000 --- a/docs/content/Modules/Catalog/index.md +++ /dev/null @@ -1,21 +0,0 @@ -# Module Catalog - -This catalog tracks modules maintained in the PSModule organization and what each module does. - -## Scope - -Each module page should capture: - -- purpose and problem statement -- install and import baseline -- key exported capabilities -- owner and maintenance notes -- lifecycle status - -## Catalog generation - -The module list and linked module pages are generated from PSModule repository metadata and README content, then refreshed automatically. - - - - diff --git a/docs/content/Modules/Process-PSModule/index.md b/docs/content/Modules/Process-PSModule/index.md deleted file mode 100644 index e142be31..00000000 --- a/docs/content/Modules/Process-PSModule/index.md +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Process-PSModule -description: An end-to-end PowerShell module pipeline that builds, tests, versions, documents, and publishes a module from a single reusable GitHub Actions workflow. ---- - -# Process-PSModule - -An end-to-end PowerShell module pipeline that automates the entire lifecycle of a module: building from source, running -cross-platform tests, enforcing code quality and coverage, generating documentation, and publishing the versioned module -to the PowerShell Gallery and its documentation site to GitHub Pages. It is the core workflow used across all PowerShell -modules in the [PSModule organization](https://github.com/PSModule), ensuring reliable, automated, and maintainable -delivery of PowerShell projects. - -## How it works - -The workflow is triggered on pull requests to the repository's default branch. When a pull request is opened, closed, -reopened, synchronized (push), or labeled, the workflow runs. Depending on the labels on the pull request, the -[workflow results in different outcomes](reference/scenario-matrix.md). - -Everything is packaged into a single reusable workflow so that a module repository only needs a small caller workflow -and one settings file. A user configures the behaviour by editing `.github/PSModule.yml`. - -![Process diagram](media/Process-PSModule.png) - -## Start here - -New to Process-PSModule? Work through these in order. - -| Page | Description | -| --- | --- | -| [Get started](get-started/index.md) | Create a module repository from the template and get the pipeline running. | -| [Repository setup](get-started/repository-setup.md) | Configure GitHub Pages, the PowerShell Gallery API key, permissions, and the caller workflow. | -| [Your first release](get-started/your-first-release.md) | The pull request flow, version labels, and what happens on merge. | - -## Guides - -Task-oriented deep dives into the pipeline's functionality. - -| Page | Description | -| --- | --- | -| [Calling the workflow](guides/calling-the-workflow.md) | The caller workflow, passing test secrets and variables with `TestData`, and important-file change detection. | -| [Configuring the pipeline](guides/configuring-the-pipeline.md) | Worked examples for coverage targets, rapid testing, linting, and PR-based release notes. | -| [Structuring your module](guides/structuring-your-module.md) | The repository and module source layout the workflow expects, and how to declare dependencies. | -| [Writing module tests](guides/writing-module-tests.md) | Test discovery, setup and teardown phases, and shared test infrastructure. | -| [Skipping framework tests](guides/skipping-framework-tests.md) | Skip individual framework tests on a per-file basis. | -| [Versioning and releases](guides/versioning-and-releases.md) | Label-driven versioning, prereleases, and what a release produces. | -| [Validating before review](guides/validating-before-review.md) | The PSModule validation pass before a draft pull request is marked ready. | - -## Reference - -Look up the exact contract. - -| Page | Description | -| --- | --- | -| [Settings](reference/settings.md) | Every available setting in `.github/PSModule.yml` and the full defaults. | -| [Workflow inputs](reference/workflow-inputs.md) | Inputs, secrets, and permissions of the reusable workflow. | -| [Pipeline stages](reference/pipeline-stages.md) | The job-by-job breakdown, from Plan through Publish Docs. | -| [Scenario matrix](reference/scenario-matrix.md) | Which jobs run for each trigger scenario. | -| [Framework test IDs](reference/framework-test-ids.md) | The framework tests enforced on source code and on the built module. | -| [Dependencies](reference/dependencies.md) | The actions, modules, and services the workflow composes. | - -## Specification - -The requirements and architecture behind the pipeline. Primarily for those maintaining Process-PSModule itself. - -| Page | Description | -| --- | --- | -| [Specification](specification/index.md) | Spec, design, and the principles that guide both. | diff --git a/docs/content/Modules/index.md b/docs/content/Modules/index.md index 5ce52fb1..120be4b0 100644 --- a/docs/content/Modules/index.md +++ b/docs/content/Modules/index.md @@ -1,19 +1,23 @@ # Modules -Process-PSModule now hosts PSModule-org module documentation. +This page indexes modules maintained in the PSModule organization and what each module does. -This section is the local source of truth for: +Modules are separate from the [Process-PSModule framework](../index.md). Use the framework documentation to build and release a module; use this page to discover the modules available to install and use. -- module catalog and module-level specs -- Process-PSModule structure and build flow -- repository anatomy and template onboarding +## Scope -## Sections +Each module page should capture: -- [Repository Standard](Repository-Standard.md) -- [Standards](Standards.md) -- [Module types](Module-Types.md) -- [Test Specification](Test-Specification.md) -- [Versioning](Versioning.md) -- [Catalog](Catalog/index.md) (auto-generated from PSModule repo metadata, release data, and README summaries) -- [Process-PSModule](Process-PSModule/index.md) +- purpose and problem statement +- install and import baseline +- key exported capabilities +- owner and maintenance notes +- lifecycle status + +## Module index generation + +The module list and linked module pages are generated from PSModule repository metadata and README content, then refreshed automatically. + + + + diff --git a/docs/content/Modules/Process-PSModule/get-started/index.md b/docs/content/get-started/index.md similarity index 97% rename from docs/content/Modules/Process-PSModule/get-started/index.md rename to docs/content/get-started/index.md index cff6ec17..7b4f0b8b 100644 --- a/docs/content/Modules/Process-PSModule/get-started/index.md +++ b/docs/content/get-started/index.md @@ -34,4 +34,4 @@ If the module needs several interdependent commands before it is usable at all, | [Your first release](your-first-release.md) | The pull request flow, version labels, and what happens on merge. | | [Module bootstrap](module-bootstrap.md) | Getting a brand-new module to its first release with an integration branch. | -For framework-level practices, refer to [MSX Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/). +For framework-level practices, refer to [MSX Ways of Working](https://msx.no/docs/Ways-of-Working/). diff --git a/docs/content/Modules/Process-PSModule/get-started/module-bootstrap.md b/docs/content/get-started/module-bootstrap.md similarity index 80% rename from docs/content/Modules/Process-PSModule/get-started/module-bootstrap.md rename to docs/content/get-started/module-bootstrap.md index c207aacb..496234e6 100644 --- a/docs/content/Modules/Process-PSModule/get-started/module-bootstrap.md +++ b/docs/content/get-started/module-bootstrap.md @@ -9,7 +9,7 @@ A brand-new module usually has a small **load-bearing core**: the piece(s) every ## Identify the load-bearing core first -What counts as "load-bearing" follows the module's archetype from [Module types](../../Module-Types.md): +What counts as "load-bearing" follows the module's archetype from [Module types](../reference/module-types.md): - **Data modules** — the conversion pivot: `ConvertFrom-` / `ConvertTo-` (and whatever parser/serializer they wrap). Every other function (`Import-`, `Export-`, `Format-`, `Merge-`, ...) is built on top of this pivot and is meaningless without it. - **Integration (API) modules** — a [`Context`](https://github.com/PSModule/Context)-backed credential/config store, the client setup that uses it, and at least one API function that consumes the context end-to-end. Every other API function needs the same context and client to do anything. @@ -19,13 +19,13 @@ Scope the integration branch to exactly that core, not to everything planned for ## Pattern 1. Cut one long-lived branch from the default branch for the initial release, named for the outcome, e.g. `build-thing-module`. -2. Open one pull request per function (or small group of related functions) targeting that branch instead of `main`. These PRs can land in parallel — there is no strict order between them, unlike a [stacked pull request](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests). +2. Open one pull request per function (or small group of related functions) targeting that branch instead of `main`. These PRs can land in parallel — there is no strict order between them, unlike a [stacked pull request](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests). 3. Once the load-bearing core is coherent and complete, open the pull request that merges the integration branch into `main`. This becomes the module's first real release (`v1.0.0`). 4. Smaller follow-up features (one more function, a formatter, an alias) can keep targeting the integration branch before it lands, the same way they targeted it during bootstrap. ## After the core lands -Once the core has merged as `v1.0.0`, ordinary [SemVer](../../Versioning.md) applies: a new function built on the stable core is a **minor** bump, a fix is a **patch** bump, and only a change to the core's own contract (signature, exported class shape, behavior) is a **major** bump. No special versioning exception is needed once the core is in place — the bootstrap phase exists only to get that core to a first release quickly. +Once the core has merged as `v1.0.0`, ordinary [SemVer](../reference/versioning.md) applies: a new function built on the stable core is a **minor** bump, a fix is a **patch** bump, and only a change to the core's own contract (signature, exported class shape, behavior) is a **major** bump. No special versioning exception is needed once the core is in place — the bootstrap phase exists only to get that core to a first release quickly. ```mermaid gitGraph @@ -60,6 +60,6 @@ A module bootstrapped this way: ## When to use this - The module has no usable release yet, and the load-bearing core hasn't landed. -- Use this only for the initial bootstrap. Once `main` has a first release, ongoing feature work targets `main` directly with ordinary topic branches, or a [stacked pull request](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests) when changes genuinely depend on each other. +- Use this only for the initial bootstrap. Once `main` has a first release, ongoing feature work targets `main` directly with ordinary topic branches, or a [stacked pull request](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests) when changes genuinely depend on each other. -For the general branching and merge model, see [MSX Branching and Merging](https://msxorg.github.io/docs/Ways-of-Working/Branching-and-Merging/). +For the general branching and merge model, see [MSX Branching and Merging](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/). diff --git a/docs/content/Modules/Process-PSModule/get-started/repository-setup.md b/docs/content/get-started/repository-setup.md similarity index 100% rename from docs/content/Modules/Process-PSModule/get-started/repository-setup.md rename to docs/content/get-started/repository-setup.md diff --git a/docs/content/Modules/Process-PSModule/get-started/your-first-release.md b/docs/content/get-started/your-first-release.md similarity index 100% rename from docs/content/Modules/Process-PSModule/get-started/your-first-release.md rename to docs/content/get-started/your-first-release.md diff --git a/docs/content/Modules/Process-PSModule/guides/calling-the-workflow.md b/docs/content/guides/calling-the-workflow.md similarity index 100% rename from docs/content/Modules/Process-PSModule/guides/calling-the-workflow.md rename to docs/content/guides/calling-the-workflow.md diff --git a/docs/content/Modules/Process-PSModule/guides/configuring-the-pipeline.md b/docs/content/guides/configuring-the-pipeline.md similarity index 100% rename from docs/content/Modules/Process-PSModule/guides/configuring-the-pipeline.md rename to docs/content/guides/configuring-the-pipeline.md diff --git a/docs/content/Modules/Process-PSModule/guides/skipping-framework-tests.md b/docs/content/guides/skipping-framework-tests.md similarity index 96% rename from docs/content/Modules/Process-PSModule/guides/skipping-framework-tests.md rename to docs/content/guides/skipping-framework-tests.md index f8955b76..61ecbb9b 100644 --- a/docs/content/Modules/Process-PSModule/guides/skipping-framework-tests.md +++ b/docs/content/guides/skipping-framework-tests.md @@ -165,7 +165,7 @@ function Format-ComplexData { Replace `` with the module's published name. If the public function belongs to a group, insert `/` between `Functions/` and `Get-ComplexData`. -The skip exempts only `FunctionCount`. Every function in the file must still follow the [PowerShell function standard](https://msxorg.github.io/docs/Coding-Standards/PowerShell/Functions/), including complete comment-based help, matching `[OutputType()]` and `.OUTPUTS` metadata, typed parameters, and implicit output. +The skip exempts only `FunctionCount`. Every function in the file must still follow the [PowerShell function standard](https://msx.no/docs/Coding-Standards/PowerShell/Functions/), including complete comment-based help, matching `[OutputType()]` and `.OUTPUTS` metadata, typed parameters, and implicit output. ## Best Practices diff --git a/docs/content/Modules/Process-PSModule/guides/structuring-your-module.md b/docs/content/guides/structuring-your-module.md similarity index 94% rename from docs/content/Modules/Process-PSModule/guides/structuring-your-module.md rename to docs/content/guides/structuring-your-module.md index 2f7710dc..b70100b2 100644 --- a/docs/content/Modules/Process-PSModule/guides/structuring-your-module.md +++ b/docs/content/guides/structuring-your-module.md @@ -54,13 +54,13 @@ The goal is a stable repository anatomy so both humans and automation know exact └── README.md # Repository overview rendered on GitHub and docs landing ``` -The tree shows the [Simple PowerShell test profile](https://msxorg.github.io/docs/Coding-Standards/PowerShell/Testing/#simple), not an exclusive test-file shape. Standard keeps one root-level `tests/.Tests.ps1` file per public function group. Advanced uses recursively discovered subdirectories, and layouts may mix across directories. Process-PSModule defines the exact [per-directory precedence and sibling suppression](writing-module-tests.md#test-discovery). +The tree shows the [Simple PowerShell test profile](https://msx.no/docs/Coding-Standards/PowerShell/Testing/#simple), not an exclusive test-file shape. Standard keeps one root-level `tests/.Tests.ps1` file per public function group. Advanced uses recursively discovered subdirectories, and layouts may mix across directories. Process-PSModule defines the exact [per-directory precedence and sibling suppression](writing-module-tests.md#test-discovery). These names describe repository conventions, not settings. `.github/PSModule.yml` does not select a test profile. The optional `tests/BeforeAll.ps1` and `tests/AfterAll.ps1` files are root-only workflow phases and are not discovered recursively. Key expectations: -- Keep at least one exported function under `src/functions/public/` and corresponding tests in `tests/` using a [documented test profile](https://msxorg.github.io/docs/Coding-Standards/PowerShell/Testing/#module-test-profiles). +- Keep at least one exported function under `src/functions/public/` and corresponding tests in `tests/` using a [documented test profile](https://msx.no/docs/Coding-Standards/PowerShell/Testing/#module-test-profiles). - Keep documentation site configuration in `.github/zensical.toml`. - Optional folders (`assemblies`, `formats`, `types`, `variables`, and others) are processed automatically when present. - Markdown files in `src/functions/public` subfolders become documentation pages alongside generated help. diff --git a/docs/content/Modules/Process-PSModule/guides/validating-before-review.md b/docs/content/guides/validating-before-review.md similarity index 77% rename from docs/content/Modules/Process-PSModule/guides/validating-before-review.md rename to docs/content/guides/validating-before-review.md index 74bc1150..ac6454c6 100644 --- a/docs/content/Modules/Process-PSModule/guides/validating-before-review.md +++ b/docs/content/guides/validating-before-review.md @@ -5,7 +5,7 @@ description: PSModule-specific validation checks that extend the shared MSXOrg B # Validating before review -Use this page after scaffolding a module change or implementing a function and before you finish self-review or mark a draft pull request ready. It extends the shared MSXOrg [Workflow Build step](https://msxorg.github.io/docs/Ways-of-Working/Workflow/#build) and [Implement guidance](https://msxorg.github.io/docs/Agents/implement/) with the PSModule-specific validation checks that module repositories must pass. +Use this page after scaffolding a module change or implementing a function and before you finish self-review or mark a draft pull request ready. It extends the shared MSXOrg [Workflow Build step](https://msx.no/docs/Ways-of-Working/Workflow/#build) and [Implement guidance](https://msx.no/docs/Agents/implement/) with the PSModule-specific validation checks that module repositories must pass. Do not repeat the shared workflow here. Follow the shared branch → draft PR → implement → test → self-review loop first, then run this PSModule pass to confirm the change still fits the module's design, documentation, and PowerShell standards. @@ -17,8 +17,8 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR Check: - - the module still follows the right archetype from [Module types](../../Module-Types.md) - - the change respects the layout, private-helper boundaries, context rules, and SOLID guidance in [PowerShell module standard](../../Standards.md) + - the module still follows the right archetype from [Module types](../reference/module-types.md) + - the change respects the layout, private-helper boundaries, context rules, and SOLID guidance in [PowerShell module standard](../reference/powershell-module-standard.md) - the function belongs in this module instead of a different module, a shared helper, or a follow-up issue A human contributor or agent should be able to explain why this change belongs in this module, in this shape, without inventing new local rules. @@ -29,8 +29,8 @@ 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 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) + - `README.md` still answers the start-page questions and reflects any user-visible behavior, prerequisites, or setup changes from [Repository Standard](../reference/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](../reference/powershell-module-standard.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 If the change teaches the user something new, confirm that the user can discover it from the published documentation surfaces, not only from the diff. @@ -42,7 +42,7 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR Check: - public functions live under `src/functions/public//` and private helpers live under `src/functions/private//` - - file placement, grouping, and exported surface match [Structuring your module](structuring-your-module.md) and the layout rules in [PowerShell module standard](../../Standards.md#repository-layout) + - file placement, grouping, and exported surface match [Structuring your module](structuring-your-module.md) and the layout rules in [PowerShell module standard](../reference/powershell-module-standard.md#repository-layout) - there are no nested helper functions, multi-function files, or naming shortcuts that break the "one declaration per file" rule This step is about shape, not behavior: the goal is that a reader or tool can find the module surface and its helpers exactly where PSModule expects them. @@ -54,7 +54,7 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR Check: - comment-based help is present for every changed function, including private helpers - - help sections, examples, `.INPUTS`, `.OUTPUTS`, and parameter documentation match the function contract from [MSX PowerShell Functions](https://msxorg.github.io/docs/Coding-Standards/PowerShell/Functions/) + - help sections, examples, `.INPUTS`, `.OUTPUTS`, and parameter documentation match the function contract from [MSX PowerShell Functions](https://msx.no/docs/Coding-Standards/PowerShell/Functions/) - public-function links and usage examples are current enough that generated documentation will stay accurate Do not treat help as optional cleanup. In PSModule repositories, the function help is part of the delivered behavior. @@ -65,8 +65,8 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR Check: - - advanced-function structure, parameter typing and validation, `ShouldProcess`, output behavior, and error handling align with [MSX PowerShell](https://msxorg.github.io/docs/Coding-Standards/PowerShell/) and [MSX PowerShell Functions](https://msxorg.github.io/docs/Coding-Standards/PowerShell/Functions/) - - the code also satisfies the PSModule-specific conventions in [PowerShell module standard](../../Standards.md), especially around private helpers, context handling, and repository layout + - advanced-function structure, parameter typing and validation, `ShouldProcess`, output behavior, and error handling align with [MSX PowerShell](https://msx.no/docs/Coding-Standards/PowerShell/) and [MSX PowerShell Functions](https://msx.no/docs/Coding-Standards/PowerShell/Functions/) + - the code also satisfies the PSModule-specific conventions in [PowerShell module standard](../reference/powershell-module-standard.md), especially around private helpers, context handling, and repository layout - PSScriptAnalyzer warnings are addressed or intentionally justified, but review does not stop there; also look for awkward parameter design, leaky transport details, non-idiomatic output, or code that technically passes lint but is not good PowerShell PSScriptAnalyzer is part of the validation loop, not the whole loop. @@ -77,18 +77,18 @@ Do not repeat the shared workflow here. Follow the shared branch → draft PR Check: - - naming, documentation, error handling, testing expectations, and security posture align with the relevant pages under [MSX Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) - - the change follows the shared "written once, referenced everywhere" rule by linking canonical guidance instead of copying it into local docs or code comments, as described in [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/) + - naming, documentation, error handling, testing expectations, and security posture align with the relevant pages under [MSX Coding Standards](https://msx.no/docs/Coding-Standards/) + - the change follows the shared "written once, referenced everywhere" rule by linking canonical guidance instead of copying it into local docs or code comments, as described in [Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/) - the draft PR description, issue progress, and any follow-up issues reflect what actually shipped and what still belongs out of scope This is the last author-side gate before a PSModule draft PR is ready for independent review. ## Where this connects -- [MSX Workflow Build step](https://msxorg.github.io/docs/Ways-of-Working/Workflow/#build) -- [MSX Implement guidance](https://msxorg.github.io/docs/Agents/implement/) -- [PowerShell module standard](../../Standards.md) -- [Module types](../../Module-Types.md) +- [MSX Workflow Build step](https://msx.no/docs/Ways-of-Working/Workflow/#build) +- [MSX Implement guidance](https://msx.no/docs/Agents/implement/) +- [PowerShell module standard](../reference/powershell-module-standard.md) +- [Module types](../reference/module-types.md) - [Structuring your module](structuring-your-module.md) -- [Repository Standard](../../Repository-Standard.md) -- [MSX Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) +- [Repository Standard](../reference/repository-standard.md) +- [MSX Coding Standards](https://msx.no/docs/Coding-Standards/) diff --git a/docs/content/Modules/Process-PSModule/guides/versioning-and-releases.md b/docs/content/guides/versioning-and-releases.md similarity index 97% rename from docs/content/Modules/Process-PSModule/guides/versioning-and-releases.md rename to docs/content/guides/versioning-and-releases.md index 006349cb..682bd3d5 100644 --- a/docs/content/Modules/Process-PSModule/guides/versioning-and-releases.md +++ b/docs/content/guides/versioning-and-releases.md @@ -74,4 +74,4 @@ pattern used for larger efforts. - [Your first release](../get-started/your-first-release.md) — the pull request flow end-to-end. - [Pipeline stages](../reference/pipeline-stages.md#publish-module) — what the publish job does. -- [Versioning](../../Versioning.md) — the PSModule versioning policy. +- [Versioning](../reference/versioning.md) — the PSModule versioning policy. diff --git a/docs/content/Modules/Process-PSModule/guides/writing-module-tests.md b/docs/content/guides/writing-module-tests.md similarity index 98% rename from docs/content/Modules/Process-PSModule/guides/writing-module-tests.md rename to docs/content/guides/writing-module-tests.md index 7558ba58..a5d161e3 100644 --- a/docs/content/Modules/Process-PSModule/guides/writing-module-tests.md +++ b/docs/content/guides/writing-module-tests.md @@ -24,7 +24,7 @@ flow in automatically while a new major stays a deliberate, reviewed change. ## Test discovery Simple, Standard, and Advanced are -[documentation profiles](https://msxorg.github.io/docs/Coding-Standards/PowerShell/Testing/#module-test-profiles), not +[documentation profiles](https://msx.no/docs/Coding-Standards/PowerShell/Testing/#module-test-profiles), not selectable workflow modes. The same discovery engine handles every profile. `.github/PSModule.yml` has no test-layout or suite-matrix setting; `Settings.Test.Module.Suites` is computed internally from the repository files. diff --git a/docs/content/index.md b/docs/content/index.md index 6ca954f9..8e126e11 100644 --- a/docs/content/index.md +++ b/docs/content/index.md @@ -1,28 +1,70 @@ --- -hide: - - navigation +title: Process-PSModule +description: An end-to-end PowerShell module pipeline that builds, tests, versions, documents, and publishes a module from a single reusable GitHub Actions workflow. --- -# Make it **easy**, to move **fast**, in a **safe** way +# Process-PSModule -Every decision — from architecture to commit message — is filtered through those three words. +An end-to-end PowerShell module pipeline that automates the entire lifecycle of a module: building from source, running cross-platform tests, enforcing code quality and coverage, generating documentation, and publishing the versioned module to the PowerShell Gallery and its documentation site to GitHub Pages. It is the core workflow used across all PowerShell modules in the [PSModule organization](https://github.com/PSModule), ensuring reliable, automated, and maintainable delivery of PowerShell projects. -## Easy +## How it works -Simplicity is a feature. Make the right thing the easy thing — for users, contributors, and agents alike. -Prefer the obvious and limited over the powerful and confusing. Automate what is mechanical so that human attention is saved for decisions that require judgment, context, and care. +The workflow is triggered on pull requests to the repository's default branch. When a pull request is opened, closed, reopened, synchronized (push), or labeled, the workflow runs. Depending on the labels on the pull request, the [workflow results in different outcomes](reference/scenario-matrix.md). -The safe and smart choice should be the default choice. Design systems, tools, and workflows so that doing the right thing requires no extra effort — while allowing a deliberate override when necessary. +Everything is packaged into a single reusable workflow so that a module repository only needs a small caller workflow and one settings file. A user configures the behaviour by editing `.github/PSModule.yml`. -## Fast +![Process diagram](media/Process-PSModule.png) -Shift left, ship early, learn fast, iterate. Work flows in small increments — draft PRs, micro-commits, quick reviews. -The faster we close the loop between intention and observation, the faster we improve and evolve what we are building. +## Start here -## Safe +New to Process-PSModule? Work through these in order. -Every decision should be reversible. Every release should be observable. Every failure should teach. -Speed requires safety — we can only iterate fast when changes are cheap to undo, easy to monitor, and failures produce learning rather than blame. +| Page | Description | +| --- | --- | +| [Get started](get-started/index.md) | Create a module repository from the template and get the pipeline running. | +| [Repository setup](get-started/repository-setup.md) | Configure GitHub Pages, the PowerShell Gallery API key, permissions, and the caller workflow. | +| [Your first release](get-started/your-first-release.md) | The pull request flow, version labels, and what happens on merge. | + +## Guides + +Task-oriented deep dives into the pipeline's functionality. + +| Page | Description | +| --- | --- | +| [Calling the workflow](guides/calling-the-workflow.md) | The caller workflow, passing test secrets and variables with `TestData`, and important-file change detection. | +| [Configuring the pipeline](guides/configuring-the-pipeline.md) | Worked examples for coverage targets, rapid testing, linting, and PR-based release notes. | +| [Structuring your module](guides/structuring-your-module.md) | The repository and module source layout the workflow expects, and how to declare dependencies. | +| [Writing module tests](guides/writing-module-tests.md) | Test discovery, setup and teardown phases, and shared test infrastructure. | +| [Skipping framework tests](guides/skipping-framework-tests.md) | Skip individual framework tests on a per-file basis. | +| [Versioning and releases](guides/versioning-and-releases.md) | Label-driven versioning, prereleases, and what a release produces. | +| [Validating before review](guides/validating-before-review.md) | The PSModule validation pass before a draft pull request is marked ready. | + +## Reference + +Look up the framework's exact contracts and the module-development standards it supports. + +| Page | Description | +| --- | --- | +| [Module development foundations](reference/module-development-foundations.md) | The full set of module-authoring conventions supported by the framework. | +| [Repository Standard](reference/repository-standard.md) | Required repository files, metadata, onboarding, and workflow wiring. | +| [PowerShell module standard](reference/powershell-module-standard.md) | Source layout, function design, and module-specific implementation conventions. | +| [Module types](reference/module-types.md) | Conventions for integration (API) and data modules. | +| [Test Specification](reference/test-specification.md) | Consistent Pester test structure and coverage expectations. | +| [Versioning](reference/versioning.md) | Semantic version changes based on public API impact. | +| [Settings](reference/settings.md) | Every available setting in `.github/PSModule.yml` and the full defaults. | +| [Workflow inputs](reference/workflow-inputs.md) | Inputs, secrets, and permissions of the reusable workflow. | +| [Pipeline stages](reference/pipeline-stages.md) | The job-by-job breakdown, from Plan through Publish Docs. | +| [Scenario matrix](reference/scenario-matrix.md) | Which jobs run for each trigger scenario. | +| [Framework test IDs](reference/framework-test-ids.md) | The framework tests enforced on source code and on the built module. | +| [Dependencies](reference/dependencies.md) | The actions, modules, and services the workflow composes. | + +## Specification + +The requirements and architecture behind the pipeline. Primarily for those maintaining Process-PSModule itself. + +| Page | Description | +| --- | --- | +| [Specification](specification/index.md) | Spec, design, and the principles that guide both. | ## A GitHub & PowerShell development framework @@ -31,20 +73,12 @@ The framework is two things in one: a collection of reusable PowerShell modules, We empower PowerShell-savvy developers to effortlessly transform their ideas into impactful solutions, automating the repetitive tasks so developers — whether consumers or contributors — can concentrate on coding without distractions. -Where we are headed is tracked as [objectives and initiatives](https://msxorg.github.io/docs/Ways-of-Working/Goal-Setting/). - -## PSModule documentation - -This site covers PSModule organization-specific documentation: - -- [Modules](Modules/index.md): module catalog and module-specific standards -- [Process-PSModule](Modules/Process-PSModule/index.md): how modules are structured and built -- [Template onboarding](Modules/Process-PSModule/get-started/index.md): how to start from the template +Where we are headed is tracked as [objectives and initiatives](https://msx.no/docs/Ways-of-Working/Goal-Setting/). ## Cross-org guidance -Cross-org standards and reusable solution documentation are now canonical in [MSXOrg/docs](https://msxorg.github.io/docs/): +Cross-org standards and reusable solution documentation are now canonical in [MSXOrg/docs](https://msx.no/docs/): -- [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) -- [Capabilities](https://msxorg.github.io/docs/Capabilities/) -- [Frameworks](https://msxorg.github.io/docs/Frameworks/) +- [Coding Standards](https://msx.no/docs/Coding-Standards/) +- [Capabilities](https://msx.no/docs/Capabilities/) +- [Frameworks](https://msx.no/docs/Frameworks/) diff --git a/docs/content/Modules/Process-PSModule/media/Process-PSModule.png b/docs/content/media/Process-PSModule.png similarity index 100% rename from docs/content/Modules/Process-PSModule/media/Process-PSModule.png rename to docs/content/media/Process-PSModule.png diff --git a/docs/content/Modules/Process-PSModule/media/pagesEnvironment.png b/docs/content/media/pagesEnvironment.png similarity index 100% rename from docs/content/Modules/Process-PSModule/media/pagesEnvironment.png rename to docs/content/media/pagesEnvironment.png diff --git a/docs/content/Modules/Process-PSModule/reference/dependencies.md b/docs/content/reference/dependencies.md similarity index 100% rename from docs/content/Modules/Process-PSModule/reference/dependencies.md rename to docs/content/reference/dependencies.md diff --git a/docs/content/Modules/Process-PSModule/reference/framework-test-ids.md b/docs/content/reference/framework-test-ids.md similarity index 100% rename from docs/content/Modules/Process-PSModule/reference/framework-test-ids.md rename to docs/content/reference/framework-test-ids.md diff --git a/docs/content/reference/module-development-foundations.md b/docs/content/reference/module-development-foundations.md new file mode 100644 index 00000000..566174d5 --- /dev/null +++ b/docs/content/reference/module-development-foundations.md @@ -0,0 +1,13 @@ +# Module development foundations + +Process-PSModule is the framework for building, testing, versioning, documenting, and publishing PowerShell modules. These foundations define the repository, source, test, and release conventions that the framework supports and validates. + +Start with the [Process-PSModule overview](../index.md) to understand the workflow. Use these pages when creating or maintaining a module that runs through it. + +| Page | Use it for | +| --- | --- | +| [Repository Standard](repository-standard.md) | Creating a module repository with the required metadata, files, and framework wiring. | +| [PowerShell module standard](powershell-module-standard.md) | Structuring source code, designing functions, and applying module-specific conventions. | +| [Module types](module-types.md) | Applying conventions for integration (API) and data modules. | +| [Test Specification](test-specification.md) | Writing consistent, comprehensive Pester tests for module functions. | +| [Versioning](versioning.md) | Choosing semantic version changes from the module's public API impact. | diff --git a/docs/content/Modules/Module-Types.md b/docs/content/reference/module-types.md similarity index 91% rename from docs/content/Modules/Module-Types.md rename to docs/content/reference/module-types.md index 390f8b98..6de0fa2b 100644 --- a/docs/content/Modules/Module-Types.md +++ b/docs/content/reference/module-types.md @@ -1,7 +1,7 @@ # Module types Most PSModule modules fall into one of a few archetypes. The general rules in -[PowerShell module standard](Standards.md) and [MSX PowerShell Standards](https://msxorg.github.io/docs/Coding-Standards/PowerShell/) always apply; this +[PowerShell module standard](powershell-module-standard.md) and [MSX PowerShell Standards](https://msx.no/docs/Coding-Standards/PowerShell/) always apply; this page adds the conventions that are specific to a module's type so that modules of the same kind feel the same to use. @@ -41,7 +41,7 @@ or hide this abstraction is a design choice: - **Private transport** (common): Keep REST, GraphQL, and HTTP helpers private. Public functions accept resolved inputs and typed objects. This follows the Dependency Inversion rule from - [Standards](Standards.md#solid-applied) applied to the network boundary. + [Standards](powershell-module-standard.md#solid-applied) applied to the network boundary. - **Public transport**: Expose REST or GraphQL functions publicly for power users or module composition. - **Public Context**: Expose the `Context` module as public so users can configure and manage @@ -102,5 +102,5 @@ 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 Standard](Repository-Standard.md): repository files, README shape, and agent onboarding. +- [PowerShell module standard](powershell-module-standard.md): layout, private functions, and the mandatory context parameter. +- [Repository Standard](repository-standard.md): repository files, README shape, and agent onboarding. diff --git a/docs/content/Modules/Process-PSModule/reference/pipeline-stages.md b/docs/content/reference/pipeline-stages.md similarity index 100% rename from docs/content/Modules/Process-PSModule/reference/pipeline-stages.md rename to docs/content/reference/pipeline-stages.md diff --git a/docs/content/Modules/Standards.md b/docs/content/reference/powershell-module-standard.md similarity index 99% rename from docs/content/Modules/Standards.md rename to docs/content/reference/powershell-module-standard.md index 27c29f29..749310b0 100644 --- a/docs/content/Modules/Standards.md +++ b/docs/content/reference/powershell-module-standard.md @@ -2,7 +2,7 @@ Standards for implementing and reviewing PowerShell modules in the PSModule organization. These rules apply to modules built with the [PSModule framework](https://github.com/PSModule/Process-PSModule). -For general PowerShell coding standards (naming, style, function structure, documentation, readability, error handling), see [MSX PowerShell Standards](https://msxorg.github.io/docs/Coding-Standards/PowerShell/). This page covers only module-specific conventions. +For general PowerShell coding standards (naming, style, function structure, documentation, readability, error handling), see [MSX PowerShell Standards](https://msx.no/docs/Coding-Standards/PowerShell/). This page covers only module-specific conventions. ## Supported PowerShell version diff --git a/docs/content/Modules/Repository-Standard.md b/docs/content/reference/repository-standard.md similarity index 94% rename from docs/content/Modules/Repository-Standard.md rename to docs/content/reference/repository-standard.md index dab95f63..dde5a31c 100644 --- a/docs/content/Modules/Repository-Standard.md +++ b/docs/content/reference/repository-standard.md @@ -2,9 +2,9 @@ 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. -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. +This standard operates at the same altitude as the [MSX Enterprise Repository Standard](https://msx.no/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. +The implementation standard still lives in [PowerShell module standard](powershell-module-standard.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 @@ -70,7 +70,7 @@ Local work should use the organization worktree convention: - `main/` tracks the default branch. - Feature worktrees use `-` directories and `/` branches. -For branch and worktree details, see [Git Worktrees](https://msxorg.github.io/docs/Ways-of-Working/Git-Worktrees/). +For branch and worktree details, see [Git Worktrees](https://msx.no/docs/Ways-of-Working/Git-Worktrees/). ## Default repository layout @@ -106,7 +106,7 @@ Module repositories use the PSModule framework layout: | `tests/` | Pester tests and test data. | | `icon/` | Module icon assets. | -Detailed source layout rules live in [PowerShell module standard](Standards.md#repository-layout). +Detailed source layout rules live in [PowerShell module standard](powershell-module-standard.md#repository-layout). ### Caller workflow and reusable workflow @@ -173,7 +173,7 @@ See [PSModule/Template-PSModule](https://github.com/PSModule/Template-PSModule) `AGENTS.md` and `CLAUDE.md` are the required set. `AGENTS.md` is the entry point that AGENTS.md-aware runtimes read directly, so a repository is usable by an agent without a per-runtime copy of the same pointer. -Runtime-specific adapter files such as `.github/copilot-instructions.md` and `.github/instructions/*.instructions.md` are optional. MSX treats them as client adapters that *may* add runtime-specific loading or path rules, described in [Agentic Development](https://msxorg.github.io/docs/Ways-of-Working/Agentic-Development/) and its [capability specification](https://msxorg.github.io/docs/Capabilities/agentic-development/spec/). Add one when a runtime needs loading or path rules that `AGENTS.md` cannot express, and keep it pointing at `AGENTS.md` rather than restating it. `Template-PSModule` ships without one. +Runtime-specific adapter files such as `.github/copilot-instructions.md` and `.github/instructions/*.instructions.md` are optional. MSX treats them as client adapters that *may* add runtime-specific loading or path rules, described in [Agentic Development](https://msx.no/docs/Ways-of-Working/Agentic-Development/) and its [capability specification](https://msx.no/docs/Capabilities/agentic-development/spec/). Add one when a runtime needs loading or path rules that `AGENTS.md` cannot express, and keep it pointing at `AGENTS.md` rather than restating it. `Template-PSModule` ships without one. 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. @@ -227,7 +227,7 @@ Dependabot PRs still go through normal review. Automated dependency updates are Dependabot's valid `package-ecosystem` values are enumerated in its configuration parser ([`common/lib/dependabot/config/file.rb`](https://github.com/dependabot/dependabot-core/blob/main/common/lib/dependabot/config/file.rb)) and listed in the [Dependabot options reference](https://docs.github.com/en/code-security/reference/supply-chain-security/dependabot-options-reference#package-ecosystem). Configure only values from that list: `powershell` is not among them, and an unsupported value makes `.github/dependabot.yml` invalid, which puts the repository's whole Dependabot configuration at risk, including the `github-actions` entry that does work. -PowerShell module dependencies are therefore declared with `#Requires -Modules` in the function files that use them, as described in [PowerShell module standard](Standards.md), and the build collects them into the compiled manifest. Keeping those declarations current is a review responsibility. +PowerShell module dependencies are therefore declared with `#Requires -Modules` in the function files that use them, as described in [PowerShell module standard](powershell-module-standard.md), and the build collects them into the compiled manifest. Keeping those declarations current is a review responsibility. A PowerShell ecosystem is proposed in [dependabot/dependabot-core#15501](https://github.com/dependabot/dependabot-core/issues/15501) and implemented in [dependabot/dependabot-core#15666](https://github.com/dependabot/dependabot-core/pull/15666), covering PowerShell's native declarations — `#Requires -Modules` in `.ps1` and `.psm1` files, and `RequiredModules` in a `.psd1` manifest — resolved against the PowerShell Gallery. Adopt it once it ships and `powershell` appears in the options reference, updating this section and the `dependabot.yml` that `Template-PSModule` distributes together. @@ -379,7 +379,7 @@ Default expectations: - Source changes under `src/` are module-impacting and should trigger the full module workflow. - README and documentation changes should update the site without pretending to be module API changes. -See [Versioning](Versioning.md) for semantic version rules and [PowerShell module standard](Standards.md#cicd-pipeline) for the Process-PSModule pipeline. +See [Versioning](versioning.md) for semantic version rules and [PowerShell module standard](powershell-module-standard.md#cicd-pipeline) for the Process-PSModule pipeline. ## Template maintenance diff --git a/docs/content/Modules/Process-PSModule/reference/scenario-matrix.md b/docs/content/reference/scenario-matrix.md similarity index 100% rename from docs/content/Modules/Process-PSModule/reference/scenario-matrix.md rename to docs/content/reference/scenario-matrix.md diff --git a/docs/content/Modules/Process-PSModule/reference/settings.md b/docs/content/reference/settings.md similarity index 100% rename from docs/content/Modules/Process-PSModule/reference/settings.md rename to docs/content/reference/settings.md diff --git a/docs/content/Modules/Test-Specification.md b/docs/content/reference/test-specification.md similarity index 100% rename from docs/content/Modules/Test-Specification.md rename to docs/content/reference/test-specification.md diff --git a/docs/content/Modules/Versioning.md b/docs/content/reference/versioning.md similarity index 100% rename from docs/content/Modules/Versioning.md rename to docs/content/reference/versioning.md diff --git a/docs/content/Modules/Process-PSModule/reference/workflow-inputs.md b/docs/content/reference/workflow-inputs.md similarity index 100% rename from docs/content/Modules/Process-PSModule/reference/workflow-inputs.md rename to docs/content/reference/workflow-inputs.md diff --git a/docs/content/Modules/Process-PSModule/specification/design.md b/docs/content/specification/design.md similarity index 100% rename from docs/content/Modules/Process-PSModule/specification/design.md rename to docs/content/specification/design.md diff --git a/docs/content/Modules/Process-PSModule/specification/index.md b/docs/content/specification/index.md similarity index 100% rename from docs/content/Modules/Process-PSModule/specification/index.md rename to docs/content/specification/index.md diff --git a/docs/content/Modules/Process-PSModule/specification/principles-and-practices.md b/docs/content/specification/principles-and-practices.md similarity index 100% rename from docs/content/Modules/Process-PSModule/specification/principles-and-practices.md rename to docs/content/specification/principles-and-practices.md diff --git a/docs/content/Modules/Process-PSModule/specification/spec.md b/docs/content/specification/spec.md similarity index 88% rename from docs/content/Modules/Process-PSModule/specification/spec.md rename to docs/content/specification/spec.md index dec61299..90db5d81 100644 --- a/docs/content/Modules/Process-PSModule/specification/spec.md +++ b/docs/content/specification/spec.md @@ -11,11 +11,11 @@ A PowerShell module's lifecycle — from source code to versioned, published art ### Principles -This capability rests on the [MSX principles](https://msxorg.github.io/docs/Ways-of-Working/Principles/): +This capability rests on the [MSX principles](https://msx.no/docs/Ways-of-Working/Principles/): -- **[Everything as Code](https://msxorg.github.io/docs/Ways-of-Working/Principles/Engineering-Practices/#everything-as-code).** The pipeline and versioning are version-controlled, never a GUI action or manual tag. -- **[Decision before change](https://msxorg.github.io/docs/Ways-of-Working/Principles/AI-First-Development/#decision-before-change).** The pull request is the decision point; its review and labels encode both code acceptance and release intent. -- **[Extensible by default](https://msxorg.github.io/docs/Ways-of-Working/Principles/Software-Design/#extensible-by-default).** The pipeline is technology-agnostic at its core, configurable via a single settings file. +- **[Everything as Code](https://msx.no/docs/Ways-of-Working/Principles/Engineering-Practices/#everything-as-code).** The pipeline and versioning are version-controlled, never a GUI action or manual tag. +- **[Decision before change](https://msx.no/docs/Ways-of-Working/Principles/AI-First-Development/#decision-before-change).** The pull request is the decision point; its review and labels encode both code acceptance and release intent. +- **[Extensible by default](https://msx.no/docs/Ways-of-Working/Principles/Software-Design/#extensible-by-default).** The pipeline is technology-agnostic at its core, configurable via a single settings file. ## Scope @@ -150,4 +150,4 @@ Scenario: Handle documentation generation failure - [Calling the workflow](../guides/calling-the-workflow.md) — how to invoke the workflow. - [Settings](../reference/settings.md) — the settings file and its options. - [Principles and practices](principles-and-practices.md) — versioning, branching, and development practices. -- [Documentation Model](https://msxorg.github.io/docs/Ways-of-Working/Documentation-Model/) — why this spec holds only the why and what. +- [Documentation Model](https://msx.no/docs/Ways-of-Working/Documentation-Model/) — why this spec holds only the why and what. diff --git a/docs/overrides/assets/stylesheets/navigation.css b/docs/overrides/assets/stylesheets/navigation.css new file mode 100644 index 00000000..b9a4c9fa --- /dev/null +++ b/docs/overrides/assets/stylesheets/navigation.css @@ -0,0 +1,9 @@ +/* Dictionary stays in the build navigation so glossary links remain published. */ +/* stylelint-disable selector-class-pattern -- Material navigation classes are external. */ +.md-tabs__item:has(.md-tabs__link[href*="Dictionary/"]), +.md-nav__item:has(.md-nav__link[href*="Dictionary/"]), +html:has(link[rel="canonical"][href*="/Dictionary/"]) .md-tabs__item--active, +html:has(link[rel="canonical"][href*="/Dictionary/"]) .md-nav__item--active { + display: none; +} +/* stylelint-enable selector-class-pattern */ diff --git a/docs/zensical.toml b/docs/zensical.toml index 3ca28f7d..cdd222bf 100644 --- a/docs/zensical.toml +++ b/docs/zensical.toml @@ -13,51 +13,48 @@ extra_javascript = [ "https://unpkg.com/tablesort@5.3.0/dist/tablesort.min.js", "assets/javascripts/tablesort.js", ] +extra_css = [ + "assets/stylesheets/navigation.css", +] watch = ["includes"] nav = [ - {"Modules" = [ - "Modules/index.md", - {"Repository Standard" = "Modules/Repository-Standard.md"}, - {"Standards" = "Modules/Standards.md"}, - {"Module types" = "Modules/Module-Types.md"}, - {"Test Specification" = "Modules/Test-Specification.md"}, - {"Versioning" = "Modules/Versioning.md"}, - {"Catalog" = [ - "Modules/Catalog/index.md", - ]}, - {"Process-PSModule" = [ - "Modules/Process-PSModule/index.md", - {"Get started" = [ - "Modules/Process-PSModule/get-started/index.md", - {"Repository setup" = "Modules/Process-PSModule/get-started/repository-setup.md"}, - {"Your first release" = "Modules/Process-PSModule/get-started/your-first-release.md"}, - {"Module bootstrap" = "Modules/Process-PSModule/get-started/module-bootstrap.md"}, - ]}, - {"Guides" = [ - {"Calling the workflow" = "Modules/Process-PSModule/guides/calling-the-workflow.md"}, - {"Configuring the pipeline" = "Modules/Process-PSModule/guides/configuring-the-pipeline.md"}, - {"Structuring your module" = "Modules/Process-PSModule/guides/structuring-your-module.md"}, - {"Writing module tests" = "Modules/Process-PSModule/guides/writing-module-tests.md"}, - {"Skipping framework tests" = "Modules/Process-PSModule/guides/skipping-framework-tests.md"}, - {"Versioning and releases" = "Modules/Process-PSModule/guides/versioning-and-releases.md"}, - {"Validating before review" = "Modules/Process-PSModule/guides/validating-before-review.md"}, - ]}, - {"Reference" = [ - {"Settings" = "Modules/Process-PSModule/reference/settings.md"}, - {"Workflow inputs" = "Modules/Process-PSModule/reference/workflow-inputs.md"}, - {"Pipeline stages" = "Modules/Process-PSModule/reference/pipeline-stages.md"}, - {"Scenario matrix" = "Modules/Process-PSModule/reference/scenario-matrix.md"}, - {"Framework test IDs" = "Modules/Process-PSModule/reference/framework-test-ids.md"}, - {"Dependencies" = "Modules/Process-PSModule/reference/dependencies.md"}, - ]}, - {"Specification" = [ - "Modules/Process-PSModule/specification/index.md", - {"Spec" = "Modules/Process-PSModule/specification/spec.md"}, - {"Design" = "Modules/Process-PSModule/specification/design.md"}, - {"Principles and practices" = "Modules/Process-PSModule/specification/principles-and-practices.md"}, - ]}, - ]}, + "index.md", + {"Get started" = [ + "get-started/index.md", + {"Repository setup" = "get-started/repository-setup.md"}, + {"Your first release" = "get-started/your-first-release.md"}, + {"Module bootstrap" = "get-started/module-bootstrap.md"}, + ]}, + {"Guides" = [ + {"Calling the workflow" = "guides/calling-the-workflow.md"}, + {"Configuring the pipeline" = "guides/configuring-the-pipeline.md"}, + {"Structuring your module" = "guides/structuring-your-module.md"}, + {"Writing module tests" = "guides/writing-module-tests.md"}, + {"Skipping framework tests" = "guides/skipping-framework-tests.md"}, + {"Versioning and releases" = "guides/versioning-and-releases.md"}, + {"Validating before review" = "guides/validating-before-review.md"}, + ]}, + {"Reference" = [ + {"Module development foundations" = "reference/module-development-foundations.md"}, + {"Repository Standard" = "reference/repository-standard.md"}, + {"PowerShell module standard" = "reference/powershell-module-standard.md"}, + {"Module types" = "reference/module-types.md"}, + {"Test Specification" = "reference/test-specification.md"}, + {"Versioning" = "reference/versioning.md"}, + {"Settings" = "reference/settings.md"}, + {"Workflow inputs" = "reference/workflow-inputs.md"}, + {"Pipeline stages" = "reference/pipeline-stages.md"}, + {"Scenario matrix" = "reference/scenario-matrix.md"}, + {"Framework test IDs" = "reference/framework-test-ids.md"}, + {"Dependencies" = "reference/dependencies.md"}, + ]}, + {"Specification" = [ + "specification/index.md", + {"Spec" = "specification/spec.md"}, + {"Design" = "specification/design.md"}, + {"Principles and practices" = "specification/principles-and-practices.md"}, ]}, + {"Modules" = "Modules/index.md"}, {"Dictionary" = [ "Dictionary/index.md", ]},