From 20b4cf122e45fb857bd54029e8021ab8e44efb0a Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sun, 9 Aug 2026 11:49:57 +0200 Subject: [PATCH 1/2] Document release branch workflow Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .../content/guides/versioning-and-releases.md | 41 +++++++++++++++++++ 1 file changed, 41 insertions(+) diff --git a/docs/content/guides/versioning-and-releases.md b/docs/content/guides/versioning-and-releases.md index 682bd3d5..a4964f92 100644 --- a/docs/content/guides/versioning-and-releases.md +++ b/docs/content/guides/versioning-and-releases.md @@ -43,6 +43,47 @@ The label names are configurable through `Publish.Module.MajorLabels`, `MinorLab Exactly one branch is authorized to publish stable releases, so consumers always have one unambiguous latest version. +## Release branch pattern + +For a larger release made up of several independent features, use a release branch to +collect the changes before promoting them to `main`. This is different from a +[stacked pull request](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests), +where each layer depends on the preceding layer. + +Before creating the release branch, make sure the module repository's caller workflow +triggers on it as well as `main`. The standard example filters pull requests to `main`: + +```yaml +on: + pull_request: + branches: + - main + - 'release/**' +``` + +Then: + +1. Cut a release branch such as `release/v1` from `main`. +2. Open a draft release pull request from the release branch to `main`. +3. Cut each independent feature branch from the release branch and open its pull request + against the release branch. +4. Merge feature pull requests into the release branch as they become ready. Use a + [stack](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests) + only when two features genuinely depend on each other. +5. When the release branch is complete and all checks pass, mark the release pull request + ready and merge it into `main`. + +Pull requests targeting the release branch can publish preview versions when they carry +the `Prerelease` label. Only the final merge into the repository's default branch can +produce the stable release, because the workflow authorizes stable publication only when +the merged pull request targets that branch. + +Each feature pull request follows the +[MSX PR Format](https://msx.no/docs/Ways-of-Working/PR-Format/) and closes its own +scoped issue. The release pull request should summarize the combined user-facing +release and link the included feature pull requests; it must not replace their +issue-closing references with a second aggregate closure. + ## Prereleases A pull request labelled `Prerelease` publishes a prerelease version (for example `v1.2.3-pr.1.5`) that is installable From 76bf167bd326171eee9993e442c424302b23e604 Mon Sep 17 00:00:00 2001 From: Marius Storhaug Date: Sun, 9 Aug 2026 11:50:21 +0200 Subject: [PATCH 2/2] Link release guidance from branch docs Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- docs/content/get-started/module-bootstrap.md | 2 +- docs/content/reference/powershell-module-standard.md | 4 +++- docs/content/specification/principles-and-practices.md | 3 ++- 3 files changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/content/get-started/module-bootstrap.md b/docs/content/get-started/module-bootstrap.md index 496234e6..6e1e5af0 100644 --- a/docs/content/get-started/module-bootstrap.md +++ b/docs/content/get-started/module-bootstrap.md @@ -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://msx.no/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, uses the [release branch pattern](../guides/versioning-and-releases.md#release-branch-pattern) to batch independent features, or uses 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://msx.no/docs/Ways-of-Working/Branching-and-Merging/). diff --git a/docs/content/reference/powershell-module-standard.md b/docs/content/reference/powershell-module-standard.md index 749310b0..1360aeac 100644 --- a/docs/content/reference/powershell-module-standard.md +++ b/docs/content/reference/powershell-module-standard.md @@ -115,7 +115,9 @@ The release process treats each merged PR as a release on a single linear ancest ### 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 the final merge to `main`. +For large work, follow the [release branch pattern](../guides/versioning-and-releases.md#release-branch-pattern): +open a release branch and target it from feature branches. Apply the `Prerelease` label on +the release branch PR to publish preview versions before the final merge to `main`. ## CI/CD pipeline diff --git a/docs/content/specification/principles-and-practices.md b/docs/content/specification/principles-and-practices.md index 06e806d2..ea816dc0 100644 --- a/docs/content/specification/principles-and-practices.md +++ b/docs/content/specification/principles-and-practices.md @@ -14,7 +14,8 @@ patch. ## Release and feature branches -If you need to work forth a bigger release, create a branch representing the release (a release branch) and open a PR towards `main` for this branch. +If you need to work toward a bigger release, follow the [release branch pattern](../guides/versioning-and-releases.md#release-branch-pattern): +create a branch representing the release and open a PR toward `main` for this branch. For each topic or feature to add to the release, open a new branch representing the feature (a feature branch) and open a PR towards the release branch. Optionally add the `Prerelease` label on the PR for the release branch, to release preview versions before merging and releasing a published version of the PowerShell module.