Releasing

Making a feature release

Feature releases (bumping either the major or the minor part of the version number trio) can typically be made directly from the main branch of the repository, without the need for a separate release branch. Here's a summary of the process:

0. [The hard part] Verify that the codebase is in a fit state to release; review open issues and PRs, check that tests pass, etc. From this point onwards we assume that PRs intended for inclusion in the release have been reviewed and merged, and that the main branch is ready for release.
1. Create a PR to update the CHANGES.txt changelog file and bump the version information in the setup.py file.
   • For the changelog, python etstool.py changelog build assembles the changelog snippets from docs/releases/upcoming and adds them to the CHANGES.txt file. That file will typically then require some manual cleanup and editing.
   • For the version information, IS_RELEASED should be changed to True, and the MAJOR and MINOR constants should have the appropriate values for the intended release. For a feature release, MICRO should be 0. Merge the PR (using squash-merge as normal) after suitable human and automated reviews.
2. Update the main branch for the PR merged in the previous step.
3. Tag the merge commit with an annotated tag of the form <major>.<minor>.<micro> (e.g., git tag -a 6.7.0). Ideally, include the release notes for the release in the tag message. Push the tag to GitHub (git push --tags).
4. Go to the GitHub releases page and create a release from the tag; paste the release notes into the release description, and adjust formatting from reST to MarkDown. Publish the release.
5. Double check that the automated PyPI release workflow worked as intended, and that the new release is visible at https://pypi.org/project/apptools/.
6. Make a new PR to bump the version again: MINOR should be updated to the correct value for the next release, and IS_RELEASED should be changed to False. Merge after suitable human and bot review.
7. Updating documentation:
   • Check out the release tag.
   • Run python etstool.py install
   • Run python etstool.py docs
   • Check out the gh-pages branch; the docs built in the previous step will now be visible as untracked files under docs/build; other untracked files can safely be deleted.
   • Remove docs/build/.doctrees, docs/build/.nojekyll and docs/build/.buildinfo; we don't need these.
   • Make a new directory for the old contents of the top-level directory if necessary, move those contents into that directory.
   • Copy new content from docs/build to the top level directory.
   • Commit changes.
   • Test docs locally by running python -m http.server and going to localhost:8000 in a browser.
   • Make a PR against the gh-pages branch.
   • Once the PR is merged, check that the content at https://docs.enthought.com/apptools/ has been successfully updated.