diff --git a/RELEASE.md b/RELEASE.md index be69ca39..b0aedbdb 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -16,18 +16,43 @@ The SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and t 1. Create a new GitHub release: * From the GitHub UI: - * Navigate to the releases UI - * Set tag to release version - * Set target to `main` + * Navigate to the [releases UI](https://github.com/planetlabs/planet-client-python/releases), and select "Draft a new release". + * Choose or create a tag for the release version. The is expected to simply be the [PEP 440](https://peps.python.org/pep-0440/) + 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](https://cli.github.com/manual/gh) CLI is installed, and optionally review the docs for CLI command [gh release create](https://cli.github.com/manual/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](https://test.pypi.org/project/planet/) -3. Run the Github Action `Publish on PyPI` +2. Verify the successful run of the Github Action [`Autopublish to TestPyPI`](https://github.com/planetlabs/planet-client-python/actions/workflows/autopublish-testpypi.yml) and validate the test release on [test.pypi.org](https://test.pypi.org/project/planet/) +3. Run the Github Action [`Publish on PyPI`](https://github.com/planetlabs/planet-client-python/actions/workflows/publish-pypi.yml) 4. Verify the successful run of the Github Action `Publish on PyPI` and validate the release on [pypi.org](https://pypi.org/project/planet/) +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](https://github.com/planetlabs/planet-client-python/settings/hooks). + 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](https://app.readthedocs.org/dashboard/planet-sdk-for-python/rules/). + * Published to [planet-sdk-for-python](https://planet-sdk-for-python.readthedocs.io/en/latest/) (Note the new version-less project slug in DNS name). + * _`default`_: [https://planet-sdk-for-python.readthedocs.io/](https://planet-sdk-for-python.readthedocs.io/) - Should point to same version as `stable`. + * `stable`: [https://planet-sdk-for-python.readthedocs.io/en/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/](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/](https://planet-sdk-for-python.readthedocs.io/en/X.YY.Z/) - Should point to version `X.YY.ZZ`. + * Published to [planet-sdk-for-python-v2](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) (Note the older "v2" in the project slug in the DNS name). + * _`default`_: [https://planet-sdk-for-python-v2.readthedocs.io/](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/](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/](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/](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. ## Local publishing diff --git a/design-docs/content-plan.md b/design-docs/content-plan.md index 5880e64e..abaa284b 100644 --- a/design-docs/content-plan.md +++ b/design-docs/content-plan.md @@ -1,6 +1,6 @@ # Content Plan Planet SDK (v2) -This document is a response to the issue #353: Quantify 'accurate and complete documentation' required for initial release. After a review of existing content, the following recommendations have been accepted as part of the V2 release. Documentation tickets will be derived from the recommendations, below. +This document is a response to the [issue #353](https://github.com/planetlabs/planet-client-python/issues/353): Quantify 'accurate and complete documentation' required for initial release. After a review of existing content, the following recommendations have been accepted as part of the V2 release. Documentation tickets will be derived from the recommendations, below. ## Overview @@ -19,7 +19,7 @@ The SDK and CLI are low-level interfaces mirroring much of the API, itself. Whil We are currently publishing documentation on [planet.com](https://docs.planet.com/develop/sdks/#planet-sdk-for-python-and-cli), [github.com](https://github.com/planetlabs/planet-client-python), and on [readthedocs.com](https://planet-sdk-for-python-v2.readthedocs.io). Providing a single source of truth (SSoT) ensures one definitive source of documentation, reducing the dilution of information, errors, and maintenance efforts. -### Ticket to be filed +### Tickets to be filed Implement mkdocs to leverage features of readthedocs.com, but publish only on one platform. This would be planet.com unless we are making a concerted effort to recruit 3rd party contributors to the SDK, in which case, it could stay on readthedocs.com. So the publication landscape would be as follows: diff --git a/design-docs/content-readthedocs.md b/design-docs/content-readthedocs.md new file mode 100644 index 00000000..5bdba43f --- /dev/null +++ b/design-docs/content-readthedocs.md @@ -0,0 +1,29 @@ +# _ReadTheDocs.io_ Content Management + +## Overview +Pursuant to the [Content Plan](./content-plan.md) developed as part of the +v2.0 release of the SDK, [_ReadTheDocs.io_](https://planet-sdk-for-python.readthedocs.io/) +is used to host the single source of truth for SDK documentation. SDK documentation +is largely confined to the specifics of using the SDK. More general Planet Platform +narrative and HTTP API documentation should be hosted on the Planet documentation site +at [docs.planet.com](https://docs.planet.com/). + +## Version Management +_ReadTheDocs.io_ hosts multiple versions of the documentation simultaneously. +All versions of the documentation will be published under a _ReadTheDocs.io_ +URL that explicitly includes the SDK version so that PyPi published packages +will always have corresponding _ReadTheDocs.io_ documentation for users. + +Additionally, the following symbolic names are maintained: +* [**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 the current mainline major version branch. + +Version management is handled by _ReadTheDocs.io_ [automation rules](https://app.readthedocs.org/dashboard/planet-sdk-for-python/rules/). + +## _ReadTheDocs.io_ Planet PBC Account +Planet currently publishes to _ReadTheDocs.io_ as a [community](https://about.readthedocs.com/pricing/#/community) +project. It is understood that this means that ads may be displayed on hosted documentation. (Ref: cleared +with Planet Engineering Management in April 2025.) + +---- diff --git a/docs/custom_theme/home.html b/docs/custom_theme/home.html index 89d6fdcc..dfbc899f 100644 --- a/docs/custom_theme/home.html +++ b/docs/custom_theme/home.html @@ -5,7 +5,11 @@
{{ config.site_description }}
Get started @@ -30,11 +34,11 @@