Creating a release

Release types

Major releases

A major release must be created for change sets that either break backwards compatibility in a significant manner or are otherwise representing a major overhaul of the library such as a significant change in available features or significant code base rewrites.

Minor releases

Minor releases are backwards compatible and introduce new features and fixes. 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.

Patch releases

A patch releases is a change that does not break backwards compatibility nor introduces new features, but only introduces bug fixes or other fixes related to the package structure. Any release that increments the third component of the semantic version is a patch release. A hotfix release is a patch release that is created directly from a previous release and is not part of the regular version history on the default branch.

A patch release should be created to release changes that fix critical issues such as security related issues, issues that are blocking for users including, but not limited to, any issues that prevent installation, may lead to data corruption, break workflows, are related to a major regression, or are otherwise time-sensitive.

Authors and contributors

The main citation metadata is stored in the CITATION.cff file. The authors listed here should only contain the core contributors and the main PI(s).

The contributors.yaml contains additional contributors who will be listed as part of the Zenodo record, but would not be listed by name in citations.

Notes

bumpversion is configured to not make a tag. GitHub's release tool will make the tag when you click "Publish Release."

Checklist

• Create release branch (see instructions below).
• Finalize changelog entries (review commits to ensure completeness).
• Update version and release date in changelog.
• Review and update CITATION.cff and contributors.yaml.
• Update Zenodo metadata (.zenodo.json) by running ./.sync-zenodo-metadata.py --in-place.
• Make sure that package requirements are consistent in setup.py and requirements.txt.
• Draft release on GitHub (put changelog in description, see past releases for format). Click "Save draft", not "Publish release" for now.
• [not for hotfix] Merge master into release branch.
• Bump version with bumpversion [patch|minor|major] command.
• Push release branch.
• Create a pull request for the release branch.
• Check TestPyPI package builds and review README.
• Apply any last minute changes if needed.
• [not for hotfix] Merge the release branch's pull request into master (see instructions).
• [not for hotfix] Publish release on GitHub from master (which should be pointing to the commit from the merged PR).
• [hotfix] Publish release on GitHub from the release branch.
• 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.
• Check that the conda packages have been updated.
• Review and create Zenodo release (see instructions).

Create release branch

Major/minor/regular patch releases:

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

Hotfix releases

git fetch origin
git checkout <tag-from-which-to-create-patch-release>
git pull
git checkout -b release/X.X.X
git push -u origin release/X.X.X

Merge release branch

Does not apply to hotfix releases!

git checkout release/X.X.X
git pull
git checkout master
git pull
git merge --no-ff release/X.X.X
git push
git branch -d release/X.X.X

Upload to Zenodo

In case that the automatic upload failed, please use the upload-zenodo script:

upload-zenodo glotzerlab signac vX.X.X --new-version --deposit-id 2594024