Skip to content

Releasing Instructions

Jump to bottom
Adam J. Stewart edited this page Aug 31, 2024 · 52 revisions

Below is a list of instructions for creating a new release of TorchGeo. In these instructions, assume the release you are creating is for version X.Y.Z.

Code Updates

The exact steps to follow depend on which type of release you are making (which version number you are incrementing).

Major Release (X.0.0)

When a backwards-incompatible API change is made, the major version is incremented. However, TorchGeo is still in alpha, so until a 1.0.0 release is made, the major version will not be incremented and users should expect backwards-incompatible API changes.

Minor Release (X.Y.0)

When a new feature is added, the minor version is incremented. To create a minor release, complete the following steps:

  • Create a new discussion titled "X.Y.0 Release Timeline" and pin it
  • Issue a "last call" for new features in this discussion and on Slack
  • Create new milestones for X.Y.1 and X.Y+1.0
  • Move all unfinished items from the X.Y.0 milestone to X.Y+1.0
  • Move all unfinished items from the X.Y-1.* milestone to X.Y.1
  • Make sure all PRs worth mentioning in release notes are in the X.Y.0 milestone (hint: use -author:app/dependabot)
  • Use sphinx-build linkcheck to check for broken links and redirects
  • Update https://torchgeo.readthedocs.io/en/latest/user/alternatives.html with new stats
  • Create a new release branch: git switch main; git checkout -b releases/vX.Y
  • Increment the __version__ in torchgeo/__init__.py from X.Y.0.dev0 to X.Y.0
  • Commit this change: git commit -am "X.Y.0 release"
  • git push upstream and open a draft PR
  • Ensure that dependency versions are still correct
  • Ensure that all new features are marked with versionadded or versionchanged
  • Ensure that all unit and integration tests pass with no warnings
  • Mark the PR as "Ready for review" and merge once approved
  • Write a draft of the release notes and share with other maintainers
  • Publish the release when ready
  • The release branch will be automatically deleted, restore it for future use
  • Close the X.Y.0 milestone, unpin the X.Y.0 discussion
  • Return to the main branch: git switch main; git pull
  • Increment the __version__ in torchgeo/__init__.py from X.Y.0 to X.Y+1.0.dev0
  • Submit a PR and merge this change

Patch Release (X.Y.Z)

When bug fixes are made to a release, the patch version is incremented. To create a patch release, complete the following steps:

  • Create a new discussion titled "X.Y.Z Release Timeline" and pin it
  • Issue a "last call" for new bug fixes in this discussion and on Slack
  • Inspect the X.Y.Z milestone, make sure that only bug fixes are included, no new features or API changes
  • Inspect the X.Y+1.0 milestone and issues/PRs that don't have a milestone, make sure there is nothing that belongs in X.Y.Z
  • Create a new milestone for X.Y.Z+1, move all unfinished items from the X.Y.Z milestone to this
  • Switch to the release branch: git switch releases/vX.Y
  • Increment the __version__ in torchgeo/__init__.py from X.Y.Z-1 to X.Y.Z, commit
  • Use git cherry-pick to add commits from the X.Y.Z milestone to this branch, some may require manual handling
  • Push these updates to GitHub, no need to open a PR
  • Ensure that dependency versions are still correct
  • Ensure that all unit and integration tests pass with no warnings
  • Write a draft of the release notes and share with other maintainers
  • Publish the release when ready
  • Close the X.Y.Z milestone, unpin the X.Y.Z discussion

Releasing

GitHub

Follow the instructions at https://help.github.com/en/github/administering-a-repository/creating-releases

Format of the release notes should generally follow prior release notes. List of contributors to a specific release can be gathered from:

$ git shortlog -se vX.Y.Z...

However, this lists actual names and emails, not GitHub handles. It's also not very accurate, it will included patch releases prior to a minor release due to the way we handle branches. A better way is to look through all PRs in the milestone. This script makes up for some of these shortcomings.

PyPI

Follow the instructions at https://packaging.python.org/en/latest/tutorials/packaging-projects/#generating-distribution-archives

Make sure you are on the releases/vX.Y branch when building the dist.

Conda

Submit a PR to https://github.com/conda-forge/torchgeo-feedstock

If you wait long enough, a bot will open a PR for you, you just need to make sure the dependency versions are updated and the linter passes.

Spack

Submit a PR to https://github.com/spack/spack

Announcing

References

The following external references may be useful to understand how releasing works:

Clone this wiki locally