Skip to content

Releasing Instructions

Jump to bottom
Adam J. Stewart edited this page Jan 25, 2026 · 61 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 required and migration is not possible with deprecation, the major version is incremented. Major releases should involve a series of release candidates preceding the final release.

In addition to all of the steps required for a minor release, major releases should also:

  • Remove all deprecated features and deprecation warnings
  • Remove all versionadded and versionchanged directives

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 are in the X.Y.0 milestone (hint: use -author:app/dependabot no:milestone is:merged)
  • 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 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
  • Update docs/_static/switcher.json with new version and set as "preferred" after ReadTheDocs build completes
  • 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
  • Create a new milestone for X.Y.Z+1
  • Move all unfinished items from the X.Y.Z milestone to X.Y.Z+1
  • Make sure all PRs are in the X.Y.Z milestone (hint: use -author:app/dependabot no:milestone is:merged)
  • 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, make sure there is nothing that belongs in X.Y.Z
  • 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 (hint: go in order from earliest to newest PR, some may require manual handling)
  • Push these updates to GitHub, no need to open a PR
  • 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
  • Update docs/_static/switcher.json with new version and set as "preferred" after ReadTheDocs build completes
  • 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

TorchGeo uses continuous distribution (CD) to automatically publish the release to PyPI once the release is published on GitHub.

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-packages

Announcing

References

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

Clone this wiki locally