From 60ddd067a86bda898e52422cfee77d30e1a8b9cc Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 2 Sep 2026 07:24:30 +0200 Subject: [PATCH 1/4] Migrate to Process-PSModule v8.0.3 The caller workflow was pinned to @migrate-to-zensical, a branch that no longer exists upstream, so every scheduled and pull-request run has been failing. Move to the v8.0.3 release and adopt its breaking interface: - Rename the publish secret APIKey to PSGALLERY_API_KEY. - Pass the newly required GitHubAppClientId and GitHubAppPrivateKey from the SHELLY_* repository secrets. Repository API operations in Plan, Build-Module, and Publish-Module now use GitHub App installation tokens instead of github.token. - Reduce permissions to contents: read, pages: write, and id-token: write, scoped on the job with an empty workflow-level default. Writes now come from the App token, so contents: write, pull-requests: write, and statuses: write are no longer needed. - Key concurrency on the pull request number and stop cancelling in progress, so close-event cleanup and the resulting stable release do not serialize as one run and a release-capable run is never interrupted. - Add the unlabeled pull-request trigger so removing a version label re-evaluates the release. - Collapse TestData to a single-line folded scalar and encode the variable with toJSON, so GitHub registers one mask instead of one per line. Pin the reusable workflow to its commit SHA with the version tag in a trailing comment, matching Template-PSModule and letting Dependabot update it. Add AGENTS.md, CLAUDE.md, and CONTRIBUTING.md, which the v8 Repository Standard requires and README.md already linked to. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/PSModule.yml | 2 +- .github/workflows/Process-PSModule.yml | 32 +++++++------- .github/zensical.toml | 8 +++- AGENTS.md | 45 ++++++++++++++++++++ CLAUDE.md | 2 + CONTRIBUTING.md | 58 ++++++++++++++++++++++++++ 6 files changed, 126 insertions(+), 21 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 CONTRIBUTING.md diff --git a/.github/PSModule.yml b/.github/PSModule.yml index de33ac9..38bd24a 100644 --- a/.github/PSModule.yml +++ b/.github/PSModule.yml @@ -1,6 +1,6 @@ # This file is used to configure the Process-PSModule workflow. # Reference: -# - https://github.com/PSModule/Process-PSModule?tab=readme-ov-file#configuration +# - https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/settings.md Test: CodeCoverage: diff --git a/.github/workflows/Process-PSModule.yml b/.github/workflows/Process-PSModule.yml index c57fa15..60b98cd 100644 --- a/.github/workflows/Process-PSModule.yml +++ b/.github/workflows/Process-PSModule.yml @@ -16,29 +16,25 @@ on: - reopened - synchronize - labeled + - unlabeled concurrency: - group: ${{ github.workflow }}-${{ github.ref }} - cancel-in-progress: true + group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} + cancel-in-progress: false -permissions: - contents: write - pull-requests: write - statuses: write - pages: write - id-token: write +permissions: {} jobs: Process-PSModule: - uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@migrate-to-zensical + permissions: + contents: read + pages: write + id-token: write + uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@16419d018975ece156bbc07d92738dd441efcb2c # v8.0.3 secrets: - APIKey: ${{ secrets.APIKey }} + PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }} + GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }} + GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }} TestData: >- - { - "secrets": { - "TEST_SECRET": "${{ secrets.TEST_SECRET }}" - }, - "variables": { - "TEST_VARIABLE": "${{ vars.TEST_VARIABLE }}" - } - } + { "secrets": { "TEST_SECRET": "${{ secrets.TEST_SECRET }}" }, + "variables": { "TEST_VARIABLE": ${{ toJSON(vars.TEST_VARIABLE) }} } } diff --git a/.github/zensical.toml b/.github/zensical.toml index 6f0a6c2..eeac26d 100644 --- a/.github/zensical.toml +++ b/.github/zensical.toml @@ -1,5 +1,9 @@ -# Navigation behavior is injected centrally by Process-PSModule Build-Site. -# This file remains repo-local for theme and docs metadata only. +# Zensical configuration +# https://zensical.org/docs/setup/basics/ +# +# Navigation state is injected centrally by the Process-PSModule Build-Site stage, +# and site_dir is resolved during Structure-Site. This file stays repo-local for +# theme and docs metadata only. [project] site_name = "-{{ REPO_NAME }}-" repo_name = "-{{ REPO_OWNER }}-/-{{ REPO_NAME }}-" diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..7f86263 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,45 @@ +# Agents + +## Main directive + +Everything is a work in progress and can be improved. +If you find a problem or improvement, fix it if small; otherwise open an issue. + +## What this repository is + +`MariusTestModule` is a PowerShell module used to exercise the PSModule framework end to end. Changes here validate +that the [Process-PSModule](https://github.com/PSModule/Process-PSModule) pipeline behaves as documented, so treat the +CI/CD run as the primary output of the repository alongside the module itself. + +## Repo guidance + +- [`README.md`](README.md) — what the module does and how to use it. +- [`CONTRIBUTING.md`](CONTRIBUTING.md) — how to contribute to this repository. + +## PSModule framework guidance + +Repository structure, module source layout, and how the Process-PSModule workflow runs: + +- [Get started](https://github.com/PSModule/Process-PSModule/tree/main/docs/content/get-started) — repository setup and first release. +- [Guides](https://github.com/PSModule/Process-PSModule/tree/main/docs/content/guides) — calling the workflow, configuring the pipeline, writing module tests, versioning. +- [Reference](https://github.com/PSModule/Process-PSModule/tree/main/docs/content/reference) — settings, pipeline stages, workflow inputs. +- [Repository Standard](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/repository-standard.md) — expected layout and required files. +- [PowerShell module standard](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/powershell-module-standard.md) — source layout and coding conventions. + +## Org-wide guidance + +- [Ways of Working](https://msxorg.github.io/docs/Ways-of-Working/) — contribution workflow, branching, PRs, issues. +- [PR Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/) — pull request title and description format. +- [Coding Standards](https://msxorg.github.io/docs/Coding-Standards/) — language-level conventions. + +## Working in this repository + +- The caller workflow is [`.github/workflows/Process-PSModule.yml`](.github/workflows/Process-PSModule.yml). It calls the + shared reusable workflow and is pinned to a commit SHA with the version tag in a trailing comment so Dependabot can + update it. Do not replace the pin with a floating tag or branch. +- Pipeline behavior is configured in [`.github/PSModule.yml`](.github/PSModule.yml). Only override defaults the module + actually needs. +- The documentation site is built by the framework from [`.github/zensical.toml`](.github/zensical.toml). Navigation + state and `site_dir` are injected centrally during the build; keep this file to theme and metadata only. +- Tests live in `tests/`. `tests/Environment.Tests.ps1` asserts that the `TestData` secrets and variables the caller + workflow passes reach the module test phases, so keep it in sync with the `TestData` block in the caller workflow. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..da0659f --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,2 @@ + +@AGENTS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..b04de24 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,58 @@ +# Contributing + +Thank you for contributing to this module. +Read [`AGENTS.md`](AGENTS.md) first for the full guidance chain and documentation references. + +## Before you start + +1. Read [`README.md`](README.md) to understand what the module does. +2. Familiarize yourself with the [Repository Standard](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/repository-standard.md) that this repository must satisfy. +3. Check the open issues and pull requests to avoid duplicate work. + +## Workflow + +This project follows the [MSXOrg contribution workflow](https://msxorg.github.io/docs/Ways-of-Working/): + +1. Open or pick up an issue that describes the change. +2. Create a branch from `main` following the `/-` convention (for example `fix/42-token-scope`). +3. Make small, focused commits and push often. +4. Open a **draft PR** as soon as the change has a basic shape — early feedback is preferred. +5. Address review feedback, and file an issue for any out-of-scope findings rather than expanding the PR. +6. Mark the PR ready for review. It lands once the required checks pass and a reviewer approves. + +## Pull requests + +- Keep PRs small and focused on a single deliverable. +- Follow the [PR Format](https://msxorg.github.io/docs/Ways-of-Working/PR-Format/) for the title and description. +- The PR description becomes the release note, so write it for users of the module rather than for reviewers. +- Apply the label that sets the version bump: `Major`, `Minor`, `Patch`, or `NoRelease`. An unlabeled PR defaults to + `Patch`. Add the `prerelease` label to publish a prerelease from the branch. + +## Releases + +Releases are produced by the [Process-PSModule](https://github.com/PSModule/Process-PSModule) pipeline, not by hand. +A merge to `main` publishes a stable release once the full pipeline passes; the version comes from the merged PR's +label and the release notes come from its description. See +[Versioning and releases](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/guides/versioning-and-releases.md). + +By default only changes under `src/` and to `README.md` trigger the build, test, and publish path. Changes limited to +other paths are still reviewed and merged, but do not create a release. + +## Code standards + +PowerShell in this module follows the +[PowerShell module standard](https://github.com/PSModule/Process-PSModule/blob/main/docs/content/reference/powershell-module-standard.md) +and the [MSXOrg Coding Standards](https://msxorg.github.io/docs/Coding-Standards/). + +Run the tests locally before pushing: + +```powershell +Invoke-Pester -Path tests -Output Detailed +``` + +Note that `tests/Environment.Tests.ps1` asserts values supplied by the CI workflow through `TestData`; it is expected +to fail locally unless the matching environment variables are set. + +## Questions + +Open a GitHub Discussion or file an issue if something is unclear. From a6631108836d3e00e80f59884b70399bc1032e25 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 2 Sep 2026 07:30:07 +0200 Subject: [PATCH 2/4] Hyphenate end-to-end in AGENTS.md The repository textlint terminology rule requires "end-to-end". Verified with textlint against .github/linters/.textlintrc. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 7f86263..2523901 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -7,7 +7,7 @@ If you find a problem or improvement, fix it if small; otherwise open an issue. ## What this repository is -`MariusTestModule` is a PowerShell module used to exercise the PSModule framework end to end. Changes here validate +`MariusTestModule` is a PowerShell module used to exercise the PSModule framework end-to-end. Changes here validate that the [Process-PSModule](https://github.com/PSModule/Process-PSModule) pipeline behaves as documented, so treat the CI/CD run as the primary output of the repository alongside the module itself. From 1df1a2bdd0bff14fc86a0234eba9f5cd154fdde0 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 2 Sep 2026 07:39:00 +0200 Subject: [PATCH 3/4] Point public help links at the canonical psmodule.io domain The v8 source-code test suite asserts that the first .LINK in each public function's help is exactly https://psmodule.io//Functions// (ID: PublicHelpLink). These functions still pointed at MariusStorhaug.github.io, which failed the check on Linux, macOS, and Windows. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- src/functions/public/DateAndTime/Get-CurrentDateTime.ps1 | 2 +- src/functions/public/Get-PSModuleTest.ps1 | 2 +- src/functions/public/Greetings/Get-Greeting.ps1 | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/functions/public/DateAndTime/Get-CurrentDateTime.ps1 b/src/functions/public/DateAndTime/Get-CurrentDateTime.ps1 index c732d1a..b7a5bec 100644 --- a/src/functions/public/DateAndTime/Get-CurrentDateTime.ps1 +++ b/src/functions/public/DateAndTime/Get-CurrentDateTime.ps1 @@ -23,7 +23,7 @@ Returns the current date in a custom format like "Monday, January 20, 2026". .LINK - https://MariusStorhaug.github.io/MariusTestModule/Functions/DateAndTime/Get-CurrentDateTime/ + https://psmodule.io/MariusTestModule/Functions/DateAndTime/Get-CurrentDateTime/ #> [OutputType([string])] [CmdletBinding()] diff --git a/src/functions/public/Get-PSModuleTest.ps1 b/src/functions/public/Get-PSModuleTest.ps1 index fe4d4cc..fd22e35 100644 --- a/src/functions/public/Get-PSModuleTest.ps1 +++ b/src/functions/public/Get-PSModuleTest.ps1 @@ -14,7 +14,7 @@ "Hello, World!" .LINK - https://MariusStorhaug.github.io/MariusTestModule/Functions/Get-PSModuleTest/ + https://psmodule.io/MariusTestModule/Functions/Get-PSModuleTest/ #> [CmdletBinding()] param ( diff --git a/src/functions/public/Greetings/Get-Greeting.ps1 b/src/functions/public/Greetings/Get-Greeting.ps1 index f2ffe64..d836b58 100644 --- a/src/functions/public/Greetings/Get-Greeting.ps1 +++ b/src/functions/public/Greetings/Get-Greeting.ps1 @@ -23,7 +23,7 @@ Returns "Good Morning, Alice!" to the user. .LINK - https://MariusStorhaug.github.io/MariusTestModule/Functions/Greetings/Get-Greeting/ + https://psmodule.io/MariusTestModule/Functions/Greetings/Get-Greeting/ #> [OutputType([string])] [CmdletBinding()] From abac58bc650d462e238ffefd52de1bc27cf9af30 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Wed, 2 Sep 2026 07:44:37 +0200 Subject: [PATCH 4/4] Track the mutable v8 tag for the reusable workflow Follow the major tag so the module picks up framework fixes within v8 without a dependency bump. Update the AGENTS.md guidance to match, which previously told agents to keep a commit SHA pin. v8 currently resolves to 16419d0, the same commit the pipeline was validated against. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/workflows/Process-PSModule.yml | 2 +- AGENTS.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/Process-PSModule.yml b/.github/workflows/Process-PSModule.yml index 60b98cd..c25013b 100644 --- a/.github/workflows/Process-PSModule.yml +++ b/.github/workflows/Process-PSModule.yml @@ -30,7 +30,7 @@ jobs: contents: read pages: write id-token: write - uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@16419d018975ece156bbc07d92738dd441efcb2c # v8.0.3 + uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8 secrets: PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }} GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }} diff --git a/AGENTS.md b/AGENTS.md index 2523901..f065f70 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,8 +35,8 @@ Repository structure, module source layout, and how the Process-PSModule workflo ## Working in this repository - The caller workflow is [`.github/workflows/Process-PSModule.yml`](.github/workflows/Process-PSModule.yml). It calls the - shared reusable workflow and is pinned to a commit SHA with the version tag in a trailing comment so Dependabot can - update it. Do not replace the pin with a floating tag or branch. + shared reusable workflow and tracks the mutable `v8` major tag, so the module picks up framework fixes within v8 + automatically. Keep the reference on the major tag rather than pinning a patch version or a commit SHA. - Pipeline behavior is configured in [`.github/PSModule.yml`](.github/PSModule.yml). Only override defaults the module actually needs. - The documentation site is built by the framework from [`.github/zensical.toml`](.github/zensical.toml). Navigation