python-kasa/RELEASING.md

Releasing

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

Requirements

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

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, or edit CHANGELOG.md in the release PR.

Normal releases

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.

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