devtools/release.py prepare opens a release PR with the version bump and the changelog section generated by git-cliff (cliff.toml).
- Merging the PR runs the
Draft Release workflow, which creates a draft GitHub release from CHANGELOG.md.
- Publishing the draft creates the tag and runs
Publish Packages, which uploads to PyPI.
- Tests for the script:
uv run pytest devtools/release.py.
git, uv and the github client (gh auth login).
- Push access to the
upstream remote, set REMOTE to use another name.
- The
release-prep label exists, PRs with it are left out of the changelog.
- Every PR merged since the previous release is an entry, titled like the PR.
- The label selects the section, first match wins:
breaking change, enhancement, bug, new device, documentation, maintenance/dependencies.
- Other PRs go to
Other changes, so fix the labels first.
- Left out:
duplicate, question, invalid, wontfix, release-prep, stale.
- To fix an entry, relabel or retitle the PR and prepare again, or edit
CHANGELOG.md in the release PR.
devtools/release.py prepare x.y.z # preview, nothing is pushed
devtools/release.py prepare --push x.y.z # push release/x.y.z and open the PR
- Optional, in a separate PR before releasing:
uv lock --upgrade and pre-commit autoupdate.
- Add the release summary at the top of the new section in
CHANGELOG.md on the PR branch.
- Squash-merge the PR once CI passes, promptly: PRs merged later are not in the section.
- Open the draft release linked in the
Draft Release run, check it and click Publish release.
- If the workflow fails, re-run it from the
Actions tab.
- Close the release PR and delete the
release/x.y.z branch on upstream.
- Run
prepare again, then rewrite the summary.
- Made from the
patch branch, git commit signing must be enabled.
- Only the given commits are included, they are cherry-picked with
-x and signed.
# First patch after a release only, the release must contain cliff.toml and the workflows
git fetch upstream --tags
git push upstream x.y.z:refs/heads/patch
devtools/release.py prepare --base patch x.y.z.n commitSHA1 commitSHA2 # preview
devtools/release.py prepare --base patch --push x.y.z.n commitSHA1 commitSHA2
- If a commit conflicts, cherry-pick it on your own branch, resolve it and pass that commit.
- The entries have no PR information and all land in
Other changes, sort them in the PR.
- Merge the PR with a merge commit, not a squash.
- Publish the draft as above.
- Patches are not merged back, so add the new section to
CHANGELOG.md on master by hand:
- paste it above the release the patch is based on,
- open a PR labelled
release-prep,
- skipping this only leaves the patch out of the changelog on master.