Skip to content

Commit 20b4cf1

Browse files
Document release branch workflow
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
1 parent 120554a commit 20b4cf1

1 file changed

Lines changed: 41 additions & 0 deletions

File tree

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

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -43,6 +43,47 @@ The label names are configurable through `Publish.Module.MajorLabels`, `MinorLab
4343

4444
Exactly one branch is authorized to publish stable releases, so consumers always have one unambiguous latest version.
4545

46+
## Release branch pattern
47+
48+
For a larger release made up of several independent features, use a release branch to
49+
collect the changes before promoting them to `main`. This is different from a
50+
[stacked pull request](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests),
51+
where each layer depends on the preceding layer.
52+
53+
Before creating the release branch, make sure the module repository's caller workflow
54+
triggers on it as well as `main`. The standard example filters pull requests to `main`:
55+
56+
```yaml
57+
on:
58+
pull_request:
59+
branches:
60+
- main
61+
- 'release/**'
62+
```
63+
64+
Then:
65+
66+
1. Cut a release branch such as `release/v1` from `main`.
67+
2. Open a draft release pull request from the release branch to `main`.
68+
3. Cut each independent feature branch from the release branch and open its pull request
69+
against the release branch.
70+
4. Merge feature pull requests into the release branch as they become ready. Use a
71+
[stack](https://msx.no/docs/Ways-of-Working/Branching-and-Merging/#stacked-pull-requests)
72+
only when two features genuinely depend on each other.
73+
5. When the release branch is complete and all checks pass, mark the release pull request
74+
ready and merge it into `main`.
75+
76+
Pull requests targeting the release branch can publish preview versions when they carry
77+
the `Prerelease` label. Only the final merge into the repository's default branch can
78+
produce the stable release, because the workflow authorizes stable publication only when
79+
the merged pull request targets that branch.
80+
81+
Each feature pull request follows the
82+
[MSX PR Format](https://msx.no/docs/Ways-of-Working/PR-Format/) and closes its own
83+
scoped issue. The release pull request should summarize the combined user-facing
84+
release and link the included feature pull requests; it must not replace their
85+
issue-closing references with a second aggregate closure.
86+
4687
## Prereleases
4788

4889
A pull request labelled `Prerelease` publishes a prerelease version (for example `v1.2.3-pr.1.5`) that is installable

0 commit comments

Comments
 (0)