How to make a bugfix release

This page outlines the procedure for making a bugfix Traits release (for example, releasing Traits 6.1.1).

Notes

1. This differs in some details from the official ETS release guidelines.
2. We consistently use squash-and-merge when merging Traits PRs. All references to merging PRs below assume squash-and-merge.

Assumptions

• We assume that a release branch named something like maint/traits-6.1.x already exists, and that on the head of that branch the value IS_RELEASED in the setup.py file is set to False.

Release preparation

The aim of this section is to get the codebase to a releasable state.

• Review bugfix PRs to the master branch since the last release and decide which bugfixes should be backported to the release branch. (Note: since this is a bugfix release, only bugfixes should be backported, but that doesn't necessarily mean that every bugfix should be backported: some fixes may have a combination of high risk and low benefit, and be better left to the next feature release.)
• Review recently-opened issues of type "bug" to see if there's anything urgent enough that it should be fixed, and the fix included in this release.
• Fix the identified issues in the master branch. (It's helpful to also label the PRs for those fixes with the appropriate backport label.)
• Create a branch from maint/traits-6.1.x for holding backports; for the purposes of this document, let's assume that you called it pr-backports.
• Cherry-pick the relevant master-branch commits back to the pr-backports branch. Note that since we're using squash-and-merge, each PR is represented by a single commit in the master branch. To avoid unnecessarily pain with conflicts, cherry-pick the commits in the order that they were merged into the master branch. Hints: use git cherry-pick -x to include a reference to the original commit. Remove any "backport-to-6.1" labels as you go.
• In the pr-backports branch, update the changelog for the backported PRs. Make sure to include a release date! (We'll pull the changelog changes back into the master branch later.)
• Make a PR for pr-backports against the maint/traits-6.1.x branch. Wait for CI and code review, then merge.

The last four steps above may occur several times - it's fine to backport just a few PRs at a time, over a period of days or weeks.

Make checks

At this point, you should be ready to make a release of the code in exactly its current state (modulo version number changes). Allocate yourself a decent amount of time to make checks:

• Run the test suite.
• Double check that relevant PRs have been backported and all relevant issues solved. If not, go back to the previous section.
• Double check that the changelog is complete; if not, make a PR against the release branch to fix (wait for CI + code review, merge).
• Double check that the release date is correct; if not, make a PR against the release branch to fix (wait for CI + code review, merge).
• Run the tests one more time. Run the test suites of other relevant projects.

Bump version and tag

Now you're ready to make the release.

• Create a new branch make-release from the maint/6.1.x branch (double check that you're on the HEAD of that branch first!)
• On that branch, change the IS_RELEASED line in setup.py from IS_RELEASED = False to IS_RELEASED = True
• Make a Draft PR for that branch against maint/6.1.x. We're not going to merge this PR!
• Wait for CI to complete and get a review for that PR. (Yes, really!)
• DO NOT MERGE THE PR!
• Tag the single commit of the PR branch as 6.1.1, making sure to use an annotated tag. Double check the tag commit is the correct one. Push the tag.
• STILL DO NOT MERGE THE PR!
• DELETE THE PR BRANCH WITHOUT MERGING IT!

Bump version on release branch

• Make a branch bump-version from the maint/6.1.x branch. Note that because you didn't merge the PR in the previous section (you didn't, did you? I told you not to!), the HEAD of the release branch still has IS_RELEASED=False.
• In the bump-version branch, bump the micro version, e.g., from MICRO=1 to MICRO=2. If you did merge the PR in the previous section, then you'll also want to change IS_RELEASED=True to IS_RELEASED=False.
• Make PR, wait for CI to complete, wait for review, merge.

Note that there's a possible race condition in the last two sections: if someone merges a PR to the release branch after you've tagged the 6.1.1 release but before you make the version bump, you'll end up with a commit where setup.py that has MICRO=1 but whose content is not in the 6.1.1 release. If this possibility worries you, you can switch the sections above around and bump the version first. You then just need to be careful to create the make-release branch from the commit immediately preceding the version bump.

Post-release steps

• If there were any documentation changes since the previous release, make a new documentation build PR against the gh-pages branch. Note that the new documentation should replace the existing documentation: don't store the old documentation in a separate directory as you would for a new feature release. Wait for review and merge. Check that docs.enthought.com/traits has been updated.
• Update release tag information on GitHub.
• Check that wheels and sdist were built and uploaded to PyPI.
• Check that Read the Docs has picked up the new release.
• Trigger a manual run of the "Test installation from PyPI" workflow.
• Request buildsystem update.
• Announce the release on all appropriate channels (including ets-users mailing list, Enthought portal).
• Make a PR to cherry-pick any relevant changes from the release branch back into master (e.g., changelog updates).