Skip to content

Releasing Instructions

Jump to bottom
Adam J. Stewart edited this page Jul 11, 2022 · 53 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.0 and X.Y.1
  • 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 X.Y.0 milestone
  • 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"
  • Push to GitHub and open a draft PR
  • Check to make sure that dependency versions are still correct
  • Ensure that all unit and integration tests pass
  • Mark the PR as "Ready for review" and merge once approved
  • Make sure the release branch didn't get automatically closed, restore if needed
  • Close the X.Y.0 milestone, unpin the X.Y.0 discussion
  • Return to the main branch: git switch main
  • Increment the __version__ in torchgeo/__init__.py from X.Y.0 to X.Y+1.0.dev0
  • Commit and push 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
  • Ensure that all unit and integration tests pass and that we have 100% coverage with no test/docs warnings
  • 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.

PyPI

Follow the instructions at https://packaging.python.org/tutorials/packaging-projects/

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

References

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

Clone this wiki locally