Document push-driven stable releases

Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>

Author: MariusStorhaug

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

@@ -38,6 +38,9 @@ on:
   workflow_dispatch:
   schedule:
     - cron: '0 0 * * *'
+  push:
+    branches:
+      - main
   pull_request:
     branches:
       - main
@@ -47,10 +50,11 @@ on:
       - reopened
       - synchronize
       - labeled
+      - unlabeled
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: false
 
 permissions:
   contents: write
@@ -68,8 +72,10 @@ jobs:
       GitHubAppPrivateKey: ${{ secrets.SHELLY_PRIVATE_KEY }}
 ```
 
-Every permission in that block is required. See [Workflow inputs](../reference/workflow-inputs.md) for what each one is
-used for, and [Calling the workflow](../guides/calling-the-workflow.md) for passing test secrets and variables.
+Every permission in that block is required. A push to `main` publishes a stable release after the full pipeline passes;
+the pull-request trigger handles CI, prereleases, and prerelease cleanup. See
+[Workflow inputs](../reference/workflow-inputs.md) for what each permission is used for, and
+[Calling the workflow](../guides/calling-the-workflow.md) for passing test secrets and variables.
 
 ## 4. Add the settings file
 

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

@@ -21,6 +21,9 @@ on:
   workflow_dispatch:
   schedule:
     - cron: '0 0 * * *'
+  push:
+    branches:
+      - main
   pull_request:
     branches:
       - main
@@ -30,10 +33,11 @@ on:
       - reopened
       - synchronize
       - labeled
+      - unlabeled
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
-  cancel-in-progress: true
+  cancel-in-progress: false
 
 permissions:
   contents: write
@@ -53,6 +57,10 @@ jobs:
 
 </details>
 
+Stable releases are evaluated from a push to the default branch. A merged pull request supplies its version label and
+release notes; a direct default-branch push or a manual dispatch uses the default `Patch` bump and commit-based notes.
+Keep the `pull_request` trigger for CI, prereleases, and prerelease cleanup.
+
 ## Passing test data
 
 The reusable workflow at `.github/workflows/workflow.yml` declares four workflow-call secrets,
@@ -175,9 +183,9 @@ Notes:
 
 ## Important file change detection
 
-The workflow automatically detects whether a pull request contains changes to "important" files that should enter the
-build, test, and publish path. This prevents unnecessary work and releases when only files outside the configured
-patterns are modified.
+The workflow automatically detects whether a pull request or default-branch push contains changes to "important" files
+that should enter the build, test, and publish path. This prevents unnecessary work and releases when only files outside
+the configured patterns are modified.
 
 ### Files that trigger the important-change path
 

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

@@ -1,12 +1,13 @@
 ---
 title: Versioning and releases
-description: How Process-PSModule resolves a version from pull-request labels, what a release produces, and how prereleases are published and cleaned up.
+description: How Process-PSModule resolves a version from pull-request labels, publishes stable releases from default-branch pushes, and cleans up prereleases.
 ---
 
 # 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.
+requests and resolved once, in the Plan stage, before anything is built. Stable publication occurs only from a push to
+the configured default branch.
 
 ## Flow
 
@@ -18,6 +19,10 @@ requests and resolved once, in the Plan stage, before anything is built.
 
 Test and lint stages run before the publish gates, and publish is blocked when required checks fail.
 
+An open labelled pull request can publish a prerelease. A closed pull request only cleans up its prereleases. When a
+pull request merges, the resulting push to the default branch resolves that pull request's labels and creates the
+stable release from the exact pushed commit.
+
 ## Version labels
 
 The bump comes from the pull-request label; the next version is computed as `current version + bump`.
@@ -26,18 +31,20 @@ The bump comes from the pull-request label; the next version is computed as `cur
 | --- | --- |
 | `major` / `breaking` | Breaking change; bump `MAJOR`. |
 | `minor` / `feature` | New feature; bump `MINOR`. |
-| `patch` / `fix` | Bugfix; bump `PATCH`. Applied by default when no label is present. |
+| `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.
+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).
 
 ## Branch types
 
-- **Main (stable)** — publishes stable releases. A prerelease label publishes a prerelease from `main`.
+- **Main (stable)** — pushes publish stable releases. A prerelease label on an open pull request publishes a prerelease.
 - **Development** — optional prerelease branch (for example `dev`). Each push publishes a prerelease.
 - **Feature branch** — optional feature branch. A prerelease label publishes a prerelease for testing.
 
@@ -49,8 +56,8 @@ A pull request labelled `Prerelease` publishes a prerelease version (for example
 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.
 
-When a pull request is closed without merging, the prerelease versions and tags created for it are removed, so
-abandoned work leaves no orphaned prereleases. This is controlled by `Publish.Module.AutoCleanup`.
+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`.
 
 ## What a release produces
 

docs/content/specification/design.md

@@ -11,8 +11,9 @@ The behaviour in the [spec](spec.md) is delivered by a **single reusable GitHub
 
 ### Single entry point
 
-The reusable workflow accepts a caller workflow and minimal caller configuration: a `pull_request`-triggered job that
-calls `workflow.yml` and passes the `PSGALLERY_API_KEY` secret. The full caller template is in
+The reusable workflow accepts a caller workflow and minimal caller configuration: a `pull_request`-triggered job for
+CI and prereleases plus a default-branch `push` trigger for stable publication. The caller calls `workflow.yml` and
+passes the required secrets. The full caller template is in
 [Repository setup](../get-started/repository-setup.md#3-add-the-caller-workflow), and the interface it targets is
 documented in [Workflow inputs](../reference/workflow-inputs.md).
 
@@ -46,8 +47,10 @@ That enriched object is an internal inter-workflow contract, not an authoring fo
 
 ## Scenario matrix
 
-Release intent comes from pull-request labels and is resolved once, in the Plan job. The label-to-bump mapping, the
-handling of conflicting labels, and the branch types that may publish are documented in
+Release intent comes from pull-request labels and is resolved once, in the Plan job. A default-branch push resolves the
+merged pull request for its labels, while a direct push or manual dispatch defaults to `Patch` regardless of
+`AutoPatching`. The label-to-bump
+mapping, handling of conflicting labels, and branch types that may publish are documented in
 [Versioning and releases](../guides/versioning-and-releases.md).
 
 Tests run on **Windows** (latest), **Linux** (Ubuntu latest), and **macOS** (latest). Failures on any platform block

docs/content/specification/spec.md

@@ -7,7 +7,7 @@ description: Requirements for Process-PSModule — an end-to-end PowerShell modu
 
 ## Premise
 
-A PowerShell module's lifecycle — from source code to versioned, published artifact — MUST be reliable, repeatable, and as automated as possible. Contributors focus on code and tests; the pipeline focuses on build, test, quality, documentation, and release. The pipeline MUST be driven entirely by pull-request labels and merge events, never by manual intervention or external tooling. The result is a versioned, immutable artifact — a module package in the PowerShell Gallery and its documentation site — paired with a GitHub Release and a git tag.
+A PowerShell module's lifecycle — from source code to versioned, published artifact — MUST be reliable, repeatable, and as automated as possible. Contributors focus on code and tests; the pipeline focuses on build, test, quality, documentation, and release. The pipeline MUST use GitHub pull-request labels and default-branch pushes for release decisions, with direct pushes and workflow dispatch as supported GitHub-native release paths. The result is a versioned, immutable artifact — a module package in the PowerShell Gallery and its documentation site — paired with a GitHub Release and a git tag.
 
 ### Principles
 
@@ -43,7 +43,7 @@ The pipeline MUST generate module documentation from the source (cmdlet help, RE
 
 ### FR5 — Support label-driven versioning and publication { #fr5 }
 
-The pipeline MUST read pull-request labels (`Major`, `Minor`, `Patch`, `Prerelease`, `NoRelease`) to decide the semantic-version bump. It MUST compute the next version automatically, never reading or writing a hand-edited version file. A merge to the release branch MUST trigger publication to the PowerShell Gallery and documentation site; a prerelease label MUST result in a prerelease version available for testing before stable release.
+The pipeline MUST read pull-request labels (`Major`, `Minor`, `Patch`, `Prerelease`, `NoRelease`) to decide the semantic-version bump. It MUST compute the next version automatically, never reading or writing a hand-edited version file. A push to the release branch MUST trigger publication to the PowerShell Gallery and documentation site; a prerelease label MUST result in a prerelease version available for testing before stable release.
 
 ### FR6 — Produce immutable, linkable releases { #fr6 }