Skip to content

Commit 175fe4c

Browse files
authored
docs: add steps for creating release candidates (#2687)
We've done release candidates for the last couple releases and I think it's gone well, so document how to do them.
1 parent dea960a commit 175fe4c

File tree

1 file changed

+38
-7
lines changed

1 file changed

+38
-7
lines changed

RELEASING.md

+38-7
Original file line numberDiff line numberDiff line change
@@ -2,12 +2,16 @@
22

33
Start from a clean checkout at `main`.
44

5-
Before running through the release it's good to run the build and the tests locally, and make sure CI is passing. You can
6-
also test-drive the commit in an existing Bazel workspace to sanity check functionality.
5+
Before running through the release it's good to run the build and the tests
6+
locally, and make sure CI is passing. You can also test-drive the commit in an
7+
existing Bazel workspace to sanity check functionality.
78

89
## Releasing from HEAD
910

11+
These are the steps for a regularly scheduled release from HEAD.
12+
1013
### Steps
14+
1115
1. [Determine the next semantic version number](#determining-semantic-version).
1216
1. Update CHANGELOG.md: replace the `v0-0-0` and `0.0.0` with `X.Y.0`.
1317
1. Replace `VERSION_NEXT_*` strings with `X.Y.0`.
@@ -16,12 +20,26 @@ also test-drive the commit in an existing Bazel workspace to sanity check functi
1620
```
1721
git branch --no-track release/X.Y upstream/main && git push upstream release/X.Y
1822
```
19-
1. Create a tag and push:
23+
24+
The next step is to create tags to trigger release workflow, **however**
25+
we start by using release candidate tags (`X.Y.Z-rcN`) before tagging the
26+
final release (`X.Y.Z`).
27+
28+
1. Create release candidate tag and push. Increment `N` for each rc.
29+
```
30+
git tag X.Y.0-rcN upstream/release/X.Y && git push upstream --tags
31+
```
32+
2. Announce the RC release: see [Announcing Releases]
33+
3. Wait a week for feedback.
34+
* Follow [Patch release with cherry picks] to pull bug fixes into the
35+
release branch.
36+
* Repeat the RC tagging step, incrementing `N`.
37+
4. Finally, tag the final release tag:
2038
```
2139
git tag X.Y.0 upstream/release/X.Y && git push upstream --tags
2240
```
23-
**NOTE:** Pushing the tag will trigger release automation.
24-
1. Release automation will create a GitHub release and BCR pull request.
41+
42+
Release automation will create a GitHub release and BCR pull request.
2543

2644
### Determining Semantic Version
2745

@@ -55,9 +73,22 @@ each.
5573
Once the release branch is in the desired state, use `git tag` to tag it, as
5674
done with a release from head. Release automation will do the rest.
5775

58-
### After release creation in Github
76+
### Announcing releases
77+
78+
We announce releases in the #python channel in the Bazel slack
79+
(bazelbuild.slack.com). Here's a template:
80+
81+
```
82+
Greetings Pythonistas,
83+
84+
rules_python X.Y.Z-rcN is now available
85+
Changelog: https://rules-python.readthedocs.io/en/X.Y.Z-rcN/changelog.html#vX-Y-Z
86+
87+
It will be promoted to stable next week, pending feedback.
88+
```
5989

60-
1. Announce the release in the #python channel in the Bazel slack (bazelbuild.slack.com).
90+
It's traditional to include notable changes from the changelog, but not
91+
required.
6192

6293
## Secrets
6394

0 commit comments

Comments
 (0)