Document namespaced release defaults

Author: MariusStorhaug

.github/workflows/workflow.yml

@@ -251,7 +251,7 @@ jobs:
       Settings: ${{ needs.Plan.outputs.Settings }}
 
   # Runs on:
-  # - ✅ Open/Updated PR - Only with prerelease label: publishes prerelease version
+  # - ✅ Open/Updated PR - With prerelease intent and a resolved bump: publishes a prerelease
   # - ✅ Default push    - Publishes a stable release when all tests/coverage/build succeed
   # - ✅ Closed PR       - Cleans up prereleases for the closed branch (no version published)
   # - ✅ Manual run      - Publishes a stable default-branch release

docs/content/get-started/repository-setup.md

@@ -63,7 +63,7 @@ permissions:
 
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v9
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}

docs/content/get-started/your-first-release.md

@@ -29,24 +29,26 @@ release with commit-based notes. It has no pull-request labels or body to use as
 
 | Label | Effect |
 | --- | --- |
-| `major` / `breaking` | Bump `MAJOR`. |
-| `minor` / `feature` | Bump `MINOR`. |
-| `patch` / `fix` | Bump `PATCH`. This is the default for an unlabeled PR when `AutoPatching` is enabled. |
-| `Prerelease` | Publish a prerelease version from the pull request, before it is merged. |
-| `NoRelease` | Run the pipeline but skip publication. |
+| `release:major` | Bump `MAJOR`. |
+| `release:minor` | Bump `MINOR`. |
+| `release:patch` | Bump `PATCH`. This is the default for an unlabeled PR when `AutoPatching` is enabled. |
+| `release:pre-release` | Publish a prerelease version from the pull request, before it is merged. |
+| `release:skip` | Run the pipeline but skip publication. |
 
-Conflicting labels (for example `major` together with `NoRelease`) are rejected and block the merge. The label names are
-configurable — see [Settings](../reference/settings.md).
+Conflicting labels (for example `release:major` together with `release:skip`) are rejected whenever that run resolves a
+release. A prerelease conflict fails the pull-request check; a stable conflict fails the resulting release run. These
+are the defaults; every label mapping remains configurable — see [Settings](../reference/settings.md).
 
 For the full model, including prerelease promotion and what a release produces, see
 [Versioning and releases](../guides/versioning-and-releases.md).
 
 ## Testing before you merge
 
-Add the `Prerelease` label to publish a prerelease version from the open pull request. The prerelease is installable
-from the PowerShell Gallery but is not promoted as the latest stable version, so it can be validated before the pull
-request is merged. When the pull request is closed without merging, the prerelease versions and tags created for it are
-cleaned up automatically.
+With the default `AutoPatching: true`, add `release:pre-release` to publish a patch prerelease from the open pull
+request. When AutoPatching is disabled, also apply one configured bump label. The prerelease is installable from the
+PowerShell Gallery but is not promoted as the latest stable version, so it can be validated before the pull request is
+merged. When the pull request is closed without merging, the prerelease versions and tags created for it are cleaned up
+automatically.
 
 ## When nothing is released
 

docs/content/guides/calling-the-workflow.md

@@ -46,7 +46,7 @@ permissions:
 
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v9
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
@@ -92,7 +92,7 @@ changes:
 ```yaml
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v9
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
@@ -121,7 +121,7 @@ content lines stay at the same indentation level:
 ```yaml
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v9
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}
@@ -233,7 +233,7 @@ You can also pass patterns via the workflow input:
 ```yaml
 jobs:
   Process:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v9
     with:
       ImportantFilePatterns: |
         ^src/
@@ -246,7 +246,7 @@ To disable triggering via the workflow input, pass an explicit empty string:
 ```yaml
 jobs:
   process:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v9
     with:
       ImportantFilePatterns: ''
 ```

docs/content/guides/github-app-authentication.md

@@ -23,7 +23,7 @@ names. Map the caller's secrets explicitly:
 ```yaml
 jobs:
   Process-PSModule:
-    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v8
+    uses: PSModule/Process-PSModule/.github/workflows/workflow.yml@v9
     secrets:
       PSGALLERY_API_KEY: ${{ secrets.PSGALLERY_API_KEY }}
       GitHubAppClientId: ${{ secrets.SHELLY_CLIENT_ID }}

docs/content/guides/versioning-and-releases.md

@@ -6,8 +6,8 @@ description: How Process-PSModule resolves a version from pull-request labels, p
 # Versioning and releases
 
 Process-PSModule orchestrates the module lifecycle through GitHub Actions. Version progression is label-driven in pull
-requests and resolved once, in the Plan stage, before anything is built. Stable publication occurs only from a push to
-the configured default branch.
+requests and resolved once, in the Plan stage, before anything is built. Stable publication occurs from a push or
+manual dispatch on the configured default branch.
 
 ## Flow
 
@@ -29,18 +29,20 @@ The bump comes from the pull-request label; the next version is computed as `cur
 
 | Label | Effect |
 | --- | --- |
-| `major` / `breaking` | Breaking change; bump `MAJOR`. |
-| `minor` / `feature` | New feature; bump `MINOR`. |
-| `patch` / `fix` | Bugfix; bump `PATCH`. |
-| `Prerelease` | Publish as a prerelease; not promoted to latest. |
-| `NoRelease` | Run the pipeline, skip publication. |
-
-Multiple or conflicting version labels (for example `major` together with `NoRelease`) are rejected and block the merge.
+| `release:major` | Breaking change; bump `MAJOR`. |
+| `release:minor` | New feature; bump `MINOR`. |
+| `release:patch` | Bugfix; bump `PATCH`. |
+| `release:pre-release` | Publish as a prerelease; not promoted to latest. |
+| `release:skip` | Run the pipeline, skip publication. |
+
+Multiple or conflicting version labels (for example `release:major` together with `release:skip`) are rejected whenever
+a release is resolved. A prerelease conflict fails the pull-request check; a stable conflict fails the resulting
+default-branch release run.
 With `AutoPatching: true`, an unlabeled pull request defaults to `Patch`; otherwise it needs an explicit version label.
 Direct pushes and manual dispatches on the default branch always use `Patch`, regardless of `AutoPatching`.
 
-The label names are configurable through `Publish.Module.MajorLabels`, `MinorLabels`, `PatchLabels`, and
-`IgnoreLabels` — see [Settings](../reference/settings.md).
+These are default names. They remain configurable through `Publish.Module.MajorLabels`, `MinorLabels`, `PatchLabels`,
+`PrereleaseLabels`, and `IgnoreLabels` — see [Settings](../reference/settings.md).
 
 ## Branch types
 
@@ -54,9 +56,10 @@ Exactly one branch is authorized to publish stable releases, so consumers always
 
 ## Prereleases
 
-A pull request labelled `Prerelease` publishes a prerelease version (for example `v1.2.3-pr.1.5`) that is installable
-but not promoted as latest. When that pull request is merged with a version label, the stable version is computed from
-the label and the current version on the release branch.
+With `AutoPatching: true`, a pull request labeled with the default `release:pre-release` name publishes a patch
+prerelease version (for example `v1.2.3-pr.1.5`) that is installable but not promoted as latest. When AutoPatching is
+disabled, the pull request also needs one configured bump label. When that pull request is merged with a version label,
+the stable version is computed from the label and the current version on the release branch.
 
 When a pull request closes, the prerelease versions and tags created for it are removed, so abandoned or promoted work
 leaves no orphaned prereleases. This is controlled by `Publish.Module.AutoCleanup`.

docs/content/reference/powershell-module-standard.md

@@ -117,8 +117,8 @@ versions — security fixes go on the current tip of `main` only.
 
 ### Release and feature branches
 
-For large work, open a release branch and target it from feature branches. Apply the `Prerelease` label on the release
-branch PR to publish preview versions before its final merge creates the stable default-branch push.
+For large work, open a release branch and target it from feature branches. Apply the default `release:pre-release` label
+on the release branch PR to publish preview versions before its final merge creates the stable default-branch push.
 
 ## CI/CD pipeline
 
@@ -200,13 +200,18 @@ The **Plan** job resolves the next version before any build occurs. This means t
 
 | Labels (configurable) | Bump type | Default label values |
 | --------------------- | --------- | -------------------- |
-| Major | Major (`X.0.0`) | `major`, `breaking` |
-| Minor | Minor (`x.Y.0`) | `minor`, `feature` |
-| Patch | Patch (`x.y.Z`) | `patch`, `fix` |
-| Ignore | No release | `NoRelease` |
+| Major | Major (`X.0.0`) | `release:major` |
+| Minor | Minor (`x.Y.0`) | `release:minor` |
+| Patch | Patch (`x.y.Z`) | `release:patch` |
+| Ignore | No release | `release:skip` |
 | None of the above | Patch (when `AutoPatching: true`) | — |
 
-**Prerelease versions:** Adding a `Prerelease` label to the PR produces a prerelease tag (e.g., `1.2.3-preview0001`). The format is controlled by `IncrementalPrerelease` (sequential numbering) or `DatePrereleaseFormat` (.NET DateTime format string).
+**Prerelease versions:** With `AutoPatching: true`, adding the default `release:pre-release` label to the PR produces a
+patch prerelease tag (e.g., `1.2.3-preview0001`). When AutoPatching is disabled, also apply one configured bump label.
+The format is controlled by `IncrementalPrerelease` (sequential numbering) or `DatePrereleaseFormat` (.NET DateTime
+format string).
+
+All five label mappings remain configurable in `.github/PSModule.yml`.
 
 An important direct default-branch push and a default-branch manual dispatch always resolve to `Patch`, regardless of
 `AutoPatching`. A push that exactly matches a merged pull request uses that PR's version label instead.
@@ -263,10 +268,11 @@ Publish:
     IncrementalPrerelease: true  # Sequential prerelease numbering
     DatePrereleaseFormat: ''     # Alternative: .NET DateTime format for prerelease
     VersionPrefix: 'v'          # Git tag prefix
-    MajorLabels: 'major, breaking'
-    MinorLabels: 'minor, feature'
-    PatchLabels: 'patch, fix'
-    IgnoreLabels: 'NoRelease'
+    MajorLabels: 'release:major'
+    MinorLabels: 'release:minor'
+    PatchLabels: 'release:patch'
+    IgnoreLabels: 'release:skip'
+    PrereleaseLabels: 'release:pre-release'
     UsePRTitleAsReleaseName: false
     UsePRBodyAsReleaseNotes: true
     UsePRTitleAsNotesHeading: true
@@ -291,7 +297,7 @@ The publish step only runs when:
 
 - All tests and code coverage pass (or are skipped)
 - An important push reaches the default branch (stable release), or
-- The PR carries the `Prerelease` label (prerelease from the feature/release branch)
+- The PR carries the configured prerelease label and resolves a bump
 
 On any closed PR, the pipeline cleans up any prerelease tags created for that branch. A closed pull request cannot
 create a stable release.

docs/content/reference/repository-standard.md

@@ -376,8 +376,9 @@ Module repositories use the Process-PSModule workflow. Version and release behav
 
 Default expectations:
 
-- `Major`, `Minor`, `Patch`, and `Prerelease` labels determine release behavior.
-- Documentation-only README standardization PRs use the `Docs`/`NoRelease` behavior when available.
+- `release:major`, `release:minor`, `release:patch`, and `release:pre-release` are the default release labels.
+- Documentation-only README standardization PRs use the default `release:skip` behavior when available.
+- Module repositories may override these defaults through `.github/PSModule.yml`.
 - 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.
 

docs/content/reference/scenario-matrix.md

@@ -28,7 +28,7 @@ execution; other pages link here rather than repeating it.
 
 - \* Only when `Publish.Site.Skip` is `false`.
 - † Requires an important change and all required build, test, and coverage gates to succeed. An open PR also requires
-  the `Prerelease` label. A default-branch push uses labels and notes only when its SHA exactly matches a merged pull
+  the configured prerelease label (`release:pre-release` by default) and a resolved bump. A default-branch push uses labels and notes only when its SHA exactly matches a merged pull
   request; otherwise it releases a Patch version with commit-based notes. A default-branch manual run is also a Patch
   release with commit-based notes.
 - ‡ Cleans up prerelease versions and tags for the closed pull request when `Publish.Module.AutoCleanup` is enabled;

docs/content/reference/settings.md

@@ -65,10 +65,11 @@ For worked examples, see [Configuring the pipeline](../guides/configuring-the-pi
 | `Publish.Module.IncrementalPrerelease`    | `Boolean` | Use incremental prerelease versioning                                                                                                                                | `true`              |
 | `Publish.Module.DatePrereleaseFormat`     | `String`  | Format for date-based prerelease (uses [.NET DateTime format strings](https://learn.microsoft.com/dotnet/standard/base-types/standard-date-and-time-format-strings)) | `''`                |
 | `Publish.Module.VersionPrefix`            | `String`  | Prefix for version tags                                                                                                                                              | `'v'`               |
-| `Publish.Module.MajorLabels`              | `String`  | Labels indicating a major version bump                                                                                                                               | `'major, breaking'` |
-| `Publish.Module.MinorLabels`              | `String`  | Labels indicating a minor version bump                                                                                                                               | `'minor, feature'`  |
-| `Publish.Module.PatchLabels`              | `String`  | Labels indicating a patch version bump                                                                                                                               | `'patch, fix'`      |
-| `Publish.Module.IgnoreLabels`             | `String`  | Labels indicating no release                                                                                                                                         | `'NoRelease'`       |
+| `Publish.Module.MajorLabels`              | `String`  | Labels indicating a major version bump                                                                                                                               | `'release:major'`   |
+| `Publish.Module.MinorLabels`              | `String`  | Labels indicating a minor version bump                                                                                                                               | `'release:minor'`   |
+| `Publish.Module.PatchLabels`              | `String`  | Labels indicating a patch version bump                                                                                                                               | `'release:patch'`   |
+| `Publish.Module.IgnoreLabels`             | `String`  | Labels indicating no release                                                                                                                                         | `'release:skip'`    |
+| `Publish.Module.PrereleaseLabels`         | `String`  | Labels indicating a prerelease                                                                                                                                       | `'release:pre-release'` |
 | `Publish.Module.UsePRTitleAsReleaseName`  | `Boolean` | Use the PR title as the GitHub release name instead of version string                                                                                                | `false`             |
 | `Publish.Module.UsePRBodyAsReleaseNotes`  | `Boolean` | Use the PR body as the release notes content                                                                                                                         | `true`              |
 | `Publish.Module.UsePRTitleAsNotesHeading` | `Boolean` | Prepend PR title as H1 heading with PR number link before the body                                                                                                   | `true`              |
@@ -147,10 +148,11 @@ Publish:
     IncrementalPrerelease: true
     DatePrereleaseFormat: ''
     VersionPrefix: 'v'
-    MajorLabels: 'major, breaking'
-    MinorLabels: 'minor, feature'
-    PatchLabels: 'patch, fix'
-    IgnoreLabels: 'NoRelease'
+    MajorLabels: 'release:major'
+    MinorLabels: 'release:minor'
+    PatchLabels: 'release:patch'
+    IgnoreLabels: 'release:skip'
+    PrereleaseLabels: 'release:pre-release'
     UsePRTitleAsReleaseName: false
     UsePRBodyAsReleaseNotes: true
     UsePRTitleAsNotesHeading: true