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..c25013b 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@v8 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..f065f70 --- /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 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 + 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. 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()]