# Releasing

- `devtools/release.py prepare` opens a release PR with the version bump and the changelog section generated by [git-cliff](https://git-cliff.org) (`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`.

## Requirements

- `git`, `uv` and the [github client](https://github.com/cli/cli#installation) (`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.

## Changelog entries

- 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](#preparing-again), or edit `CHANGELOG.md` in the release PR.

## Normal releases

```bash
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.

## Preparing again

- Close the release PR and delete the `release/x.y.z` branch on `upstream`.
- Run `prepare` again, then rewrite the summary.

## Patch releases

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

```bash
# 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.