Skip to content

Creating a release

Jump to bottom
Bradley Dice edited this page Jul 12, 2023 · 24 revisions

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 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.
  • Make sure that package requirements are consistent in pyproject.toml 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. Add the tag name vX.Y.Z. Click "Save draft", not "Publish release" for now.
  • Merge main 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. The bumpversion command is available from https://github.com/c4urself/bump2version (bump2version is a maintained fork of the original bumpversion).
  • Push release branch.
  • Create a pull request for the release branch.
  • Check TestPyPI (signac, signac-flow, signac-dashboard) package builds and review README.
  • Apply any last minute changes if needed.
  • Merge the release branch's pull request into main (see instructions).
  • Publish release on GitHub from main (which should be pointing to the commit from the merged PR).
  • Check that the PyPI (signac, signac-flow, signac-dashboard) package has been updated.
  • Update conda-forge feedstock (signac, signac-flow, signac-dashboard). 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.
  • 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.
  • 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 (signac, signac-flow) package builds and review README.
  • Apply any last minute changes if needed.
  • Publish release on GitHub directly from release branch
  • Check that the PyPI (signac, signac-flow) package has been updated.
  • Update conda-forge feedstock (signac, signac-flow). 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.
  • Resolve conflicts and merge the release branch's via pull request into main (see instructions).

Create release branch

Regular release

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

Hotfix release

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

Merge release branch

git checkout release/X.Y.Z
git pull
git checkout main
git pull
git merge --no-ff release/X.Y.Z
git push
git branch -d release/X.Y.Z
Clone this wiki locally