MAINTAINERS.rst: update 'cutting a release branch'

Updates for clarity and to match current practice.

Reflect some practical changes that I've been doing in the past couple
of release that cut down on review latency once it's been agreed that
it's release time. In particular, we are cutting out the review cycles
for forking the release branch, changing the versions, and tagging the
main branch after it's moved from the release branch.

Rework the section in to step 1-2-3 style while we're here, to make it
easier to follow along with.

Signed-off-by: Martí Bolívar <marti.bolivar@nordicsemi.no>
This commit is contained in:
Martí Bolívar 2021-08-05 10:10:20 -07:00 committed by Marti Bolivar
parent 6c8a16f289
commit f69c734662
1 changed files with 48 additions and 27 deletions

View File

@ -99,42 +99,63 @@ Create and push a GPG signed tag. ::
Cutting a release branch Cutting a release branch
------------------------ ------------------------
To cut a new release branch, just get confirmation from the other This is how to cut a new release branch for minor version vX.Y.
maintainers that it's time and push it manually to GitHub.
The release branch for minor version vX.Y.0 should be named "vX.Y-branch". Summary of what happens:
Subsequent fixes for patch versions vX.Y.Z should go to vX.Y-branch after - before:
being backported from main (or the other way around in case of an urgent
hotfix).
In vX.Y-branch, in src/west/version.py, set __version__ to X.Y.0a1. - vX.Y-branch does not exist
Don't include this commit in the main branch. - main branch is at version X.(Y-1).99
Summary of the outcome: - after:
- precondition: vX.Y-branch does not exist, main is at version X.(Y-1).99 - vX.Y-branch exists and is at version X.Y.0a1
- postcondition: v.X.Y-branch exists and is at version vX.Y.0a1, main is at - main is at version X.Y.99
version vX.Y.99 - west.manifest.SCHEMA_VERSION may be updated
Check if west.manifest.SCHEMA_VERSION also needs an update. The rule is that 1. Check the git logs since the last release::
SCHEMA_VERSION should be updated to X.Y if this release is introducing
manifest schema changes that earlier versions of west cannot parse.
Don't change SCHEMA_VERSION from its current value if the manifest syntax is git log vX.(Y-1).99..origin/main
fully compatible with what west X.(Y-1) can handle.
Don't introduce incompatible manifest changes in patch versions. That violates Decide if west.manifest.SCHEMA_VERSION needs an update:
semantic versioning. If v0.7.3 can parse it, v0.7.2 should be able to parse it,
too.
Send this as a pull request to the newly created release branch. (This - SCHEMA_VERSION should be updated to X.Y if release vX.Y will have manifest
requires a PR and review because getting the release number wrong would syntax changes that earlier versions of west cannot parse.
upload potentially buggy software to anyone who runs 'pip install west'.)
In main (but not the release branch), set __version__ to X.Y.99. Send this - SCHEMA_VERSION should *not* be changed for west vX.Y if the manifest
commit as a PR to main. Make sure any SCHEMA_VERSION updates are reflected in syntax is fully compatible with what west vX.(Y-1) can handle.
main too.
If you want to change SCHEMA_VERSION, send this as a pull request to the
main branch and get it reviewed and merged. (This requires a PR and review
even though the rest of the steps don't.)
**Don't** introduce incompatible manifest changes in patch versions.
That violates semantic versioning. Example: if v0.7.3 can parse a manifest,
v0.7.2 should be able to parse it, too, and with the same results.
2. Create and push the release branch for minor version vX.Y.0, which is named
"vX.Y-branch"::
git checkout -b vX.Y-branch origin/main
git push origin vX.Y-branch
This should already contain the SCHEMA_VERSION change if one is needed.
Subsequent fixes for patch versions vX.Y.Z should go to vX.Y-branch after
being backported from main (or the other way around in case of an urgent
hotfix).
3. In vX.Y-branch, in src/west/version.py, set __version__ to X.Y.0a1.
Push this to origin/vX.Y-branch. You don't need a PR for this.
4. In the main branch, set __version__ to X.Y.99.
Push this to origin/main. You don't need a PR for this.
5. Create an annotated tag vX.Y.99 which points to the main branch commit you
just created in the previous step. Push it to origin/main. You don't need a
PR for this. See refs/tags/v0.12.99 for an example. (This makes 'git
describe' output easy to read during development.)
From this point forward, the main branch is moving independently from the From this point forward, the main branch is moving independently from the
release branch. release branch. Do the release prep work in the release branch.