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 (regular 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 (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.
• Update pre-commit hooks with pre-commit autoupdate.
• Make sure that package requirements are consistent in setup.py and requirements.txt.
• 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. Click "Save draft", not "Publish release" for now.
• 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.
• Merge the release branch's pull request into master (see instructions).
• Publish release on GitHub from master (which should be pointing to the commit from the merged PR).
• Check that the PyPI package has been updated.
• 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).
• Close the GitHub milestone.

Checklist (hotfix release)

WARNING: INSTRUCTIONS FOR HOTFIX RELEASES ARE UNTESTED.

• Create release branch (see instructions below)
• Push release branch
• Merge individual hotfixes from branches (hotfix/issue-xxx) via PRs
• Finalize changelog entries (review commits to ensure completeness).
• 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.
• Bump version with bumpversion patch command and push.
• Check TestPyPI package builds and review README.
• Apply any last minute changes if needed.
• Publish release on GitHub directly from release branch
• Check that the PyPI package has been updated.
• 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).
• Resolve conflicts and merge the release branch's via pull request into master (see instructions).

Create release branch

Regular release

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

Hotfix release

git fetch origin
git checkout <tag-from-which-to-create-patch-release>
git pull
git checkout -b release/X.X.X
git commit --allow-empty -m "Create release branch for vX.X.X ."
git push -u origin release/X.X.X

Merge release branch

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