Planet maintainers only

Releasing is a two-step process: (1) releasing on GitHub and test.pypi and (2) releasing to PyPI. Releasing on GitHub will automatically trigger a release on test.pypi via a GitHub Action. Following manual confirmation of a successful and satisfactory release on test.pypi, release on PyPI is triggered manually with the Github Action Autopublish to TestPyPI. There is also an option to publish to test.pypi and PyPI from your local machine.

NOTE: the version is detected from git using the tag name. There is no need to modify a version file.

If the repository is not on tag, the version will be computed using the default versioning scheme of setuptools_scm.

The SDK follows Semantic Versioning and therefore only major releases should break compatibility. Minor versions may include new functionality and patch versions address bugs or trivial changes (like documentation).

1. Create a new GitHub release:
   • From the GitHub UI:
     • Navigate to the releases UI, and select "Draft a new release".
     • Choose or create a tag for the release version. The is expected to simply be the PEP 440 compliant semantic version number, without any prefix or other adornments. Examples, from most to least mature:
       • Production release: 2.3.4
       • Release candidate: 2.3.4rc1
       • Beta release: 2.3.4b1
       • Alpha release: 2.3.4a1
       • Alpha development pre-release build: 2.3.4a1.dev1
     • Set target the release branch. This should normally be main for production releases.
     • Set title to tag release version
     • Describe the change(s) that are shipping with this version in the release description
   • Alternatively, create a release from the GitHub CLI:
     • Make sure the pre-requisite gh CLI is installed, and optionally review the docs for CLI command gh release create
     • By default, gh release create will automatically tag releases from the latest state of the default branch
     • Run CLI command gh release create {VERSION} --notes "{RELEASE NOTES}" where VERSION is the release version and RELEASE NOTES is the description of changes
2. Verify the successful run of the Github Action Autopublish to TestPyPI and validate the test release on test.pypi.org
3. Run the Github Action Publish on PyPI
4. Verify the successful run of the Github Action Publish on PyPI and validate the release on pypi.org
5. Verify the successful and correct publishing of documentation to Read the Docs. Read the Docs publishing should be triggered automatically by Github project webhooks. Correct publishing includes verifying that the default, stable, and latest versions of the documentation point to the correct versions, and that the version specific documentation URL also works as expected. The management of these symbolic documentation versions is handled by Read the Docs automation rules.
   • Published to planet-sdk-for-python (Note the new version-less project slug in DNS name).
     • default: https://planet-sdk-for-python.readthedocs.io/ - Should point to same version as stable.
     • stable: https://planet-sdk-for-python.readthedocs.io/en/stable/ - Should point to the highest stable release version.
     • latest: https://planet-sdk-for-python.readthedocs.io/en/latest/ - Should point to the most recent build from main.
     • version: https://planet-sdk-for-python.readthedocs.io/en/X.YY.ZZ/ - Should point to version X.YY.ZZ.
   • Published to planet-sdk-for-python-v2 (Note the older "v2" in the project slug in the DNS name).
     • default: https://planet-sdk-for-python-v2.readthedocs.io/ - Should point to same version as stable.
     • stable: https://planet-sdk-for-python-v2.readthedocs.io/en/stable/ - Should point to the highest stable release version.
     • latest: https://planet-sdk-for-python-v2.readthedocs.io/en/latest/ - Should point to the most recent build from main.
     • version: https://planet-sdk-for-python-v2.readthedocs.io/en/X.YY.ZZ/ - Should point to version X.YY.ZZ.
   • Pre-release versions should not impact the default version of the documentation. Pre-release version may be published as the latest version.

Publishing to testpypi and pypi can also be performed locally with:

  $ nox -s build publish-testpypi

then

  $ nox -s publish-pypi

This approach requires specifying the pypi/testpypi api token as the password at the prompt.

When stable, not pre-release, files are uploaded to PyPI, a bot will detect them and make an automated PR to https://github.com/conda-forge/planet-feedstock/pulls. When a Conda-forge maintainer merges that PR, a package will be built for the new version and will be published to https://anaconda.org/conda-forge/planet/files.