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/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 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.