Release#

To make a new release, follow the process below.

Before a Release#

Before making a release, review the following maintenance tasks:

Consider updating the development dependencies in pyproject.toml, especially the packaging tools: build and twine.

Check if any backwards compatability code can be dropped. Run:

$ { \
     echo "file:line number:comment"; \
     echo "----:-----------:-------"; \
     git grep \
       --line-number \
       --only-matching \
       --ignore-case \
       --recursive \
       -- \
       "# backwards compatibility.*$" \
       . \
     | grep --invert-match "\.rst:"; \
  } | column -t -s':'

The command produces a table summarizing all backwards compatibility code in the codebase.

Making a Release#

Decide the next version based off the Changelog using Semantic Versioning. Let ${VERSION} denote the version to release. For example:

$ VERSION="v1.0.0"

Then:

Create a new branch:

$ git checkout -b "bump-version-to-${VERSION}"

Update and commit any changes to CHANGELOG.rst:
1. Clean up and combine existing entries if appropriate.
2. Follow the instructions from the source code comment in CHANGELOG.rst to finalize the “Unreleased” section for a new release.
3. Commit the changes with the message: "Finalize changelog for release ${VERSION}".
Update the project.version key to ${VERSION} in pyproject.toml, and commit the change with the message: "Bump version to ${VERSION}".
Open and merge a pull request for the branch.

Update the main branch:

$ git checkout main && git pull
$ git branch --delete "bump-version-to-${VERSION}" && git fetch --prune

Tag the merge commit with git:

$ git tag --annotate "${VERSION}" --message "Release ${VERSION}"

Then push the tag back to the remote:

$ git push origin "${VERSION}"

Check that the release workflow completes successfully.
View the documentation that the release workflow just deployed.
Download the package artifact, dist, that the release workflow built for the tag. You may also inspect the packages’ contents by viewing the logs from Build and test artifacts. > Package the source. > List the packages' contents..

Once you have the artifact, unzip it in your repository to the dist/ directory:
```
$ rm -rf dist/
$ unzip -d "dist/" dist.zip && rm dist.zip
```
Ensure the TWINE_USERNAME, TWINE_TESTPYPI_PASSWORD, and TWINE_PYPI_PASSWORD environment variables are available. See the PyPA documentation for details. Then, run the release session with nox:
```
$ nox --session release -- dist/
```
This session will upload the package to TestPyPI, validate it from TestPyPI, then upload to PyPI, and finally validate it from PyPI.
Make a GitHub Release out of the new tag.
1. Select the tag for the release.
2. Use the tag’s name, ${VERSION}, for the release title.
3. Copy and paste the changelog into the release description. Edit the text so that it’s properly formatted.
4. Acknowledge anyone who contributed to the release at the end of the description.
5. Submit the release.

Congratulations! The release is complete!