Creating a Release

Feature-freeze

Once a release due date has been established, the feature-freeze date should be communicated to all developers. Usually about 1 week prior to release.

Checklist

Pre-release

• Review open pull requests, issues, and milestones. Before making a release, every issue or pull request assigned to that release version should be completed or moved to a later milestone. Additionally, all resolved issues and merged pull requests since the last release should be assigned to the current milestone. Some exceptions can be made for simplicity, e.g. automated updates from Dependabot don't need to be assigned to the milestone.
• Create release branch named release/X.Y.Z, numbered according to Semantic Versioning (see commands below).
• Finalize changelog entries (review recent commits and pull requests to ensure completeness).
  • The changelog headers are Added, Fixed, Changed, Deprecated, and Removed (in that order).
• Update version and release date in changelog from next to vX.Y.Z - YYYY-MM-DD.
• Update git submodules in the extern directory (code example below).
• Update freud-examples submodule in doc/source/gettingstarted/examples (code example below).
  • All significant new features should have examples.
• Make sure that package requirements are consistent in setup.py and requirements.txt.
• Review Python version support (such as adding CI builds for new versions, dropping old versions no sooner than allowed by NEP 29).
• Make sure that installation instructions are up to date (check dependencies).
• Update and run pre-commit hooks, see below for code. This is typically handled by CI (which requires pre-commit hooks to succeed), but updated hooks may require a re-run.
• Update the contributors with git shortlog -sne > contributors.txt.
  • Check the git diff for that file. If any contributors are listed twice or misnamed, update the .mailmap file so that all contributors are recognized under a canonical name and email. Then re-run the previous command.

Release

• Merge master into release branch.
• Bump version with bumpversion [patch|minor|major] command. Bumpversion is configured NOT to make a tag. The tag will be made when the GitHub release is published.
• Push release branch.
• Create a pull request for the release branch.
• Check TestPyPI package builds and review README.
• Draft release on GitHub: Go to the "Releases" page from the sidebar on the repo home page, and click "Draft a new release." Put the new changelog entries in the description, see past releases for formatting. Add the tag name vX.Y.Z. Click "Save draft", not "Publish release" for now.
• Merge the release branch's pull request into master.
• Publish release on GitHub from master (which should be pointing to the commit from the merged PR).

Post-release

• Update the freud tarball archive using the private tarball-generator tool (requires private repository access and AFS webserver access).
• Update conda-forge feedstock. A pull request will be automatically created by the conda-forge autotick bot within a few hours. However, the recipe must be manually updated if dependencies have changed since the last release.
• Verify that ReadTheDocs, PyPI, and conda-forge have been updated to the newest version.
  • conda-forge may take 1 hour or so after the feedstock PR is merged for the CDN to update.
• Notify the Glotzer group via Slack and post the changelog on the freud-users Google Group. Follow the template from previous release notifications.

Create release branch

git fetch origin
git checkout master
git pull
git checkout -b release/X.Y.Z
git push -u origin release/X.Y.Z

How to update submodules

Example for the freud-examples submodule:

# Update freud-examples submodule:
cd doc/source/gettingstarted/examples
git pull
git checkout master
# Then go to the repository root and commit the changes.

Running pre-commit updates and hooks

# Update pre-commit hooks
pre-commit autoupdate

# Apply default pre-commit hooks (Python and generic formatters)
pre-commit run --all-files

# Apply C++ pre-commit hooks (requires local installation of clang-format and other tools)
pre-commit run --all-files --hook-stage manual