Skip to content

HOWTO: Make a release

Jump to bottom
Mark Dickinson edited this page Jul 30, 2021 · 8 revisions

How to make a Traits Futures feature release

These are notes on the steps involved in a making a Traits Futures release. Right now, Traits Futures is a fairly lightweight project, so we tend to make releases directly from the master branch (or almost directly from the master branch; see below for details).

Pre-release

Ideally, the code in the main branch should never be that far away from being releasable. Here's a checklist of things to think about:

  • Review issues for anything that should go into the release
  • Review outstanding PRs to decide which ones should go into the release
  • Make sure that the changelog is up-to-date
    • Does the changelog need migration guidelines?
    • Is there a release date included in the changelog?
  • Do all tests pass with current versions of dependencies?
  • Are there significant portions of the code missing test coverage?
  • Do all the documentation examples work as expected?
  • Does the documentation build have any obvious problems?

Once you're satisfied that the code is in releasable state, move on to the release process.

Release stage 1

Here we assume that the version number for the release is 0.3.0.

  • On the main branch, bump the version number from "0.3.0.dev0" to "0.4.0.dev0"

    • git checkout main
    • git checkout -b bump-version-for-continued-development
    • Now edit the version number in version.py
    • git add traits_futures/version.py
    • git commit -m "Bump version for continued development"
    • git push --set-upstream origin bump-version-for-continued-development
    • gh pr create --fill
    • Await appropriate levels of human and machine review

  • From the commit immediately before the version bump commit above on main, create a target branch for the release:

    • git checkout main # assuming you haven't yet pulled in the new commit on main
    • git checkout -b maint/0.3
    • Push the branch: git push --set-upstream origin maint/0.3

  • From the maint/0.3 branch, create a new release branch that we'll use for the release PR:

    • git checkout -b release/0.3.0

  • On the release/0.3.0 branch, edit version.py to the correct release version (e.g., from "0.3.0.dev0" to "0.3.0")

  • Stage, commit and push:

    • git add traits_futures/version.py
    • git commit -m "Bump version for release"
    • git push --set-upstream origin release/0.3.0

  • Create a PR against the release branch, e.g., using gh: gh pr create --base maint/0.3 --fill --draft. Note that we're not going to merge this PR: we're only making it a PR to get the benefit of the CI checks and human review.

  • After appropriate levels of human and machine review, DO NOT MERGE the PR!

  • Prepare a draft release on the GitHub releases page

Building gh-pages documentation

  • Install documentation packages: pip install .[docs]
  • Build the docs:
    • cd docs
    • python -m sphinx -b html -d doctrees source build
    • cd ..
  • Checkout the gh-pages branch, and create a new branch for the changes
    • git checkout gh-pages
    • git checkout -b gh-pages-0.3
  • Move the docs to a new directory, and stage the changes
    • mv docs/build 0.3
  • Edit the top-level index.html file to add a reference to the new 0.3 docs; stage changes
    • git add 0.3
    • git add index.html
  • Create a PR
    • git commit -m "Update gh-pages documentation for the 0.3 release"
    • git push --set-upstream origin gh-pages-0.3
    • gh pr create --base gh-pages --fill
    • After appropriate levels of human and machine review, merge the PR: gh pr merge gh-pages-0.3

Release stage 2

Following suitable reviews and tests, if all looks okay:

  • Tag the release, using an annotated tag
    • Make sure you're on the release/0.3.0 branch
    • git tag -a 0.3.0 -m "Release Traits Futures version 0.3.0"
    • git push --tags
  • Merge the PR against the main branch:
    • gh pr merge bump-version-for-continued-development -s
  • Merge the PR against gh-pages
  • DO NOT MERGE the PR against the maint/0.3 branch
  • Edit the release notes on GitHub and publish the release.
  • Check that the PyPI uploads workflow has successfully uploaded wheels and sdists to PyPI
  • Update Read the Docs config

Post release

  • Announce the release via all appropriate channels. It's nice to acknowledge all contributors at this point. Get the list of contributors with: git shortlog 0.2.0..HEAD -ns --group=author --group=trailer:co-authored-by
    • Enthought Portal
    • ets-users mailing list
    • Slack
  • Make a buildsystem request for new eggs.
Clone this wiki locally