How to make a feature release

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

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.

Pre-release

• Review outstanding issues and outstanding PRs; decide which PRs and which issues need to be resolved prior to the release.
• Resolve those issues and PRs appropriately!
• Make sure the changelog is up to date. It should include:
  • A release date!
  • A detailed list of PR-by-PR changes: git log is a useful starting point. For example:

    $ git log 6.1.1..HEAD --pretty="* %s"
    

  • A list of contributors: the git shortlog command is useful here. For example:

    $ git shortlog 6.1.1..HEAD -ns --group=author --group=trailer:co-authored-by
    

• Be confident that:
  • All tests pass.
  • The documentation builds properly, and there aren't obvious issues with the documentation pages.
  • The ETS demo contributions work.

At this point, all the hard work should be done: the main branch should contain all the content that's destined for the release.

Release

The next set of steps is more or less mechanical.

• Double check that the changelog is up to date, and has the correct release date.

• Double check that your local checkout is up to date with respect to the GitHub remote, and that you're on the latest commit on the main branch.

• Make a PR against the main branch to bump the version number in setup.py for continued development towards the next feature release. Note that IS_RELEASED will be False in the main branch, and it should stay False. Typically, only the value for MINOR will need to be changed. Merge that PR (after the usual review and approval).

• From the commit immediately preceding the version number bump in the PR in the previous step, create a new branch with name of the form maint/<major.minor>. We'll use this branch for the release and subsequent bugfix releases. Note that any branch name starting with maint/ automatically has branch protections applied, so all changes to the release branch will need to go through a PR.

  $ git checkout HEAD~1
  $ git checkout -b maint/6.2
  $ git push --set-upstream origin maint/6.2
  

• Make a draft PR against the new maint/6.2 branch to bump the version number for the release: typically the only change needed here is to set IS_RELEASED to True. For example:

  $ git checkout -b bump-version-for-release
  $ <edit setup.py to change IS_RELEASED to True>
  $ git commit -m "Bump version number for release"
  $ git push --set-upstream origin bump-version-for-release
  

  We won't actually merge this PR: we're just making it to get review from humans and from CI.

• Once the CI has completed, the PR has been reviewed, and you're satisfied that everything else is ready for release, tag the final commit (usually the only commit) of the PR as 6.2.0. Always use an annotated tag for this.

• Push the tag to GitHub (git push --tags). The draft PR can be closed (and the branch deleted) at this point.

• Make a PR against the gh-pages branch with documentation for the release, following the instructions. Merge that PR once reviewed.

• Edit the release page on GitHub.

• Once you press "publish" on the release page, wheels should automatically be built and uploaded to PyPI.

• Check that the sdist and wheels for the release have been successfully uploaded to PyPI.

• Double check that you can install manually from PyPI, and that tests pass.

• Request new eggs from the buildsystem team.

• Announce the release on suitable channels (portal, mailing list, Slack)