From 3ca94c41a858d822c00bb76804817246b37ea65c Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Mon, 7 Apr 2025 09:56:38 -0700 Subject: [PATCH 1/7] scratch --- RELEASE.md | 27 +++++++++++++++++++++++++++ 1 file changed, 27 insertions(+) diff --git a/RELEASE.md b/RELEASE.md index be69ca39..09150cbc 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -48,3 +48,30 @@ This approach requires specifying the pypi/testpypi api token as the password at ## Conda builds 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. + + +---- +# Scratch - Dump from Ian. Need to work into doc. Parking here for branch + +SDK versioning, maintenance, stability guidance + +current state: +github readme contains standard language re semantic versioning +new doc site notes v1 will remain accessible w/ no new development (and some mushy language re v2 and code-free CLI) + +challenges: +need to make breaking changes in CLI or SDK APIs soon - primary motivating example is removal of basic user email/pass authentication +we will also have unrelated service API breaking changes (eventual removal of basic user email/pass API in api.planet.com) +understand that clients will not always be able to immediately upgrade to a new version, so maintenance guidance is warranted +we don't strive to regularly make breaking changes, but we should have a mechanism for major release planning and updates +should have explicit guidance on SDK API surface stability, e.g. what is "internal" and open to implementation changes vs. stable API +release mechanics will need to be updated to support beta version major release + +proposal: +add new section(s) re versioning strategy and maintenance +continue in the short-term w/ the indefinite support for installation of older versions w/ out feature back-porting, etc. +add language re our support of python versions (stick w/ EOL schedule of upstream?) +ensure notable SDK changes/plans end up in main docs site (changelog or other?) as well as project github + +references: +python version EOL schedule https://devguide.python.org/versions/ From 25b14d48ccebc0c5dfb98c988f3be060a18957f1 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Tue, 8 Apr 2025 23:25:53 -0700 Subject: [PATCH 2/7] working on release lifecycle planning and statements --- CONTRIBUTING.md | 29 +++++++++++++++++++--- README.md | 65 +++++++++++++++++++++++++++++++++++++++++++++---- 2 files changed, 85 insertions(+), 9 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 92fc0b5a..6c345a36 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -5,11 +5,32 @@ document explains how to contribute successfully. ## Workflows -### Development +### Branches -#### Development Branch +#### Mainline Branches -The default branch is always `main` and should be always considered in-development. Feature enhancements, bug fixes, and other maintenance should be performed in a development branch, starting with the appropriate base branch and merged back into that branch: +The default branch is always `main`, and will correspond to the current stable major release version. +This branch should be considered in-development but with tests and other build steps kept in a passing +and stable state. + +Branches for future major releases will be named `main-X.0-dev` where `X.0` is the next major +release version. These branches will be kept current with the current stable major release +insofar as is practical within the scope of changes targeted to the next major release. Per symantec +versioning, major releases do not guarantee backwards compatibility. Stability is not guaranteed +during the development cycle. + +During the development cycle of a new major release, `RELEASE-PLANNING-X.0.md` should be maintained +with a brief summary of the major and breaking changes underpinning the reason for the upcoming +major release version. Upon release, this content is expected to be folded into package documentation +as appropriate, and this file should be removed. + +When a new major release is ready, the development mainline branch will be renamed to `main`, and the +old mainline branch will be renamed to `maint-X.0` and will be used as the base for maintenance releases. + +#### Development Branches + +Feature enhancements, bug fixes, and other maintenance should be performed in a development +branch, starting with the appropriate base branch and merged back into that branch: ```console git checkout main @@ -17,7 +38,7 @@ git pull git checkout -b new-branch-name ``` -#### Branch Naming +#### Development Branch Naming Branch names should describe the work performed within the branch, and include a ticket number if applicable. For example, a branch that corrects typos in documentation and is not ticketed could be named `fix-documentation-typos`, and a branch that adds a new feature and is ticketed could be named `new-feature-123` (where 'new-feature' is the name of the feature and '-123' is the ticket number). diff --git a/README.md b/README.md index 18ed81b3..655764f9 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,66 @@ remaining Planet APIs: [basemaps](https://developers.planet.com/docs/basemaps/), ## Versions and Stability -The SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and therefore only major releases should break compatibility. Minor versions may include new functionality and patch versions address bugs or trivial changes (like documentation). - -If depending upon official packages from PyPI, a developer should feel comfortable specifying `planet == 2.*` unless depending on a specific feature introduced at a minor version, in which case `planet == 2.x.*` (where x is the minor version of the new feature) should suffice. - -The default branch is always `main` and should be considered in-development but with tests and other build steps succeeding. +The SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and therefore only major releases +should break compatibility. Minor versions may include new functionality and +patch versions address bugs or trivial changes (like documentation). + +The Semantic Versioning stability scheme only applies APIs that +are considered part of the public API. This includes library APIs exported +from the `planet` package and documented in our +[SDK developer documentation](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/), +and the `planet` CLI interface used for scripts. It does not include +library interfaces below the top level `planet` Python package which are +considered internal and subject to change without notice. + +SDK semantic versioning does not apply to the underlying +[Planet APIs](https://docs.planet.com/develop/apis/), +which follow their own independent version and release lifecycles. + +If depending upon official packages from PyPI, a developer should feel +comfortable specifying `planet == 2.*` unless depending on a specific feature +introduced at a minor version, in which case `planet == 2.x.*` (where x is the +minor version of the new feature) should suffice. + +## Versions and Support Status + +Major versions are supported according to their designated support status, +as defined below. Planet Labs PBC makes no formal commitment +to a specific schedule, but will make every effort to provide reasonable +notice of upcoming changes to the support status of major versions. + +* `**development**` - Unstable. Under active development. Not recommend + for production use. API stability not guaranteed. New features from active + versions will be ported forward to the extent allowed by the scope of the + new major version under development. +* `**active**` - Actively maintained and supported. New features and bug fixes. + Suitable for production use. API stability guaranteed according to semantic + versioning, but subject to changes in the underlying Planet APIs. +* `**maintenance**` - Critical bug fixes only. +* `**end-of-life**` - No longer supported. Software packages will remain available. +* `**removed**` - No longer available. Removed from distribution channels. + +### Python Version Support +`Active` minor versions will support Python versions that have not reached +end-of-life at the time of release. + +See https://devguide.python.org/versions/ for current Python versions. + +## Branches + +The default branch is always `main`, and will correspond to the current stable +major release version. This branch should be considered in-development but +with tests and other build steps kept in a passing state. + +See [CONTRIBUTING.md](CONTRIBUTING.md#branches) for more information on branches. + +##### Current Mainline Versions and Branches + +| Version | Status | Branch | Initial Release | End of Active Development | End of Maintenance | Notes | +|---------|---------------|----------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------| +| 3.x | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | TBD | TBD | TBD | See [RELEASE-PLANNING-X.0.md](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev/RELEASE-PLANNING-3.0.md). | +| 2.x | `active` | [`main`](https://github.com/planetlabs/planet-client-python/tree/main) | April 2023 | TBD | TBD | | +| 1.x | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1) | April 2017 | April 2023 | TBD | | ## Installation and Quick Start From 2cf49310fe04c392eb8bc062ec2f91a1cddafa3b Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Wed, 9 Apr 2025 09:14:47 -0700 Subject: [PATCH 3/7] remove scratch notes --- RELEASE.md | 27 --------------------------- 1 file changed, 27 deletions(-) diff --git a/RELEASE.md b/RELEASE.md index 09150cbc..be69ca39 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -48,30 +48,3 @@ This approach requires specifying the pypi/testpypi api token as the password at ## Conda builds 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. - - ----- -# Scratch - Dump from Ian. Need to work into doc. Parking here for branch - -SDK versioning, maintenance, stability guidance - -current state: -github readme contains standard language re semantic versioning -new doc site notes v1 will remain accessible w/ no new development (and some mushy language re v2 and code-free CLI) - -challenges: -need to make breaking changes in CLI or SDK APIs soon - primary motivating example is removal of basic user email/pass authentication -we will also have unrelated service API breaking changes (eventual removal of basic user email/pass API in api.planet.com) -understand that clients will not always be able to immediately upgrade to a new version, so maintenance guidance is warranted -we don't strive to regularly make breaking changes, but we should have a mechanism for major release planning and updates -should have explicit guidance on SDK API surface stability, e.g. what is "internal" and open to implementation changes vs. stable API -release mechanics will need to be updated to support beta version major release - -proposal: -add new section(s) re versioning strategy and maintenance -continue in the short-term w/ the indefinite support for installation of older versions w/ out feature back-porting, etc. -add language re our support of python versions (stick w/ EOL schedule of upstream?) -ensure notable SDK changes/plans end up in main docs site (changelog or other?) as well as project github - -references: -python version EOL schedule https://devguide.python.org/versions/ From b195edde6abf650847a449ee9d1e0495a2978fa0 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Wed, 9 Apr 2025 09:20:02 -0700 Subject: [PATCH 4/7] formatting --- README.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index 655764f9..390ccbf4 100644 --- a/README.md +++ b/README.md @@ -51,16 +51,16 @@ as defined below. Planet Labs PBC makes no formal commitment to a specific schedule, but will make every effort to provide reasonable notice of upcoming changes to the support status of major versions. -* `**development**` - Unstable. Under active development. Not recommend +* **`development`** - Unstable. Under active development. Not recommend for production use. API stability not guaranteed. New features from active versions will be ported forward to the extent allowed by the scope of the new major version under development. -* `**active**` - Actively maintained and supported. New features and bug fixes. +* **`active`** - Actively maintained and supported. New features and bug fixes. Suitable for production use. API stability guaranteed according to semantic versioning, but subject to changes in the underlying Planet APIs. -* `**maintenance**` - Critical bug fixes only. -* `**end-of-life**` - No longer supported. Software packages will remain available. -* `**removed**` - No longer available. Removed from distribution channels. +* **`maintenance`** - Critical bug fixes only. +* **`end-of-life`** - No longer supported. Software packages will remain available. +* **`removed`** - No longer available. Removed from distribution channels. ### Python Version Support `Active` minor versions will support Python versions that have not reached From 7a14119c8228a8d7ba26ae0b8cf38281254dcda7 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Thu, 10 Apr 2025 09:09:22 -0700 Subject: [PATCH 5/7] Fix typo. --- CONTRIBUTING.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c345a36..8c8ab18a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -15,7 +15,7 @@ and stable state. Branches for future major releases will be named `main-X.0-dev` where `X.0` is the next major release version. These branches will be kept current with the current stable major release -insofar as is practical within the scope of changes targeted to the next major release. Per symantec +insofar as is practical within the scope of changes targeted to the next major release. Per semantic versioning, major releases do not guarantee backwards compatibility. Stability is not guaranteed during the development cycle. From 19374d182a6a8780bea6002ab3d57b856d377762 Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Wed, 16 Apr 2025 14:55:29 -0700 Subject: [PATCH 6/7] doc updates --- README.md | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 390ccbf4..ae8c8961 100644 --- a/README.md +++ b/README.md @@ -27,6 +27,9 @@ The SDK follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html) and t should break compatibility. Minor versions may include new functionality and patch versions address bugs or trivial changes (like documentation). +Packages will be released to [PyPi / Planet](https://pypi.org/project/planet/) +with semantic version identifiers that comply with [PEP 440](https://peps.python.org/pep-0440/). + The Semantic Versioning stability scheme only applies APIs that are considered part of the public API. This includes library APIs exported from the `planet` package and documented in our @@ -51,7 +54,7 @@ as defined below. Planet Labs PBC makes no formal commitment to a specific schedule, but will make every effort to provide reasonable notice of upcoming changes to the support status of major versions. -* **`development`** - Unstable. Under active development. Not recommend +* **`development`** - Unstable. Under active development. Not recommended for production use. API stability not guaranteed. New features from active versions will be ported forward to the extent allowed by the scope of the new major version under development. @@ -78,11 +81,11 @@ See [CONTRIBUTING.md](CONTRIBUTING.md#branches) for more information on branches ##### Current Mainline Versions and Branches -| Version | Status | Branch | Initial Release | End of Active Development | End of Maintenance | Notes | -|---------|---------------|----------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------| -| 3.x | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | TBD | TBD | TBD | See [RELEASE-PLANNING-X.0.md](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev/RELEASE-PLANNING-3.0.md). | -| 2.x | `active` | [`main`](https://github.com/planetlabs/planet-client-python/tree/main) | April 2023 | TBD | TBD | | -| 1.x | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1) | April 2017 | April 2023 | TBD | | +| Version | Status | Branch | Documentation | Initial Release | End of Active Development | End of Maintenance | Notes | +|---------|---------------|----------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------|-----------------|---------------------------|--------------------|------------------------------------------------------------------------------------------------------------------------------| +| 3.x | `development` | [`main-3.0-dev`](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev) | TBD | TBD | TBD | TBD | See [RELEASE-PLANNING-X.0.md](https://github.com/planetlabs/planet-client-python/tree/main-3.0-dev/RELEASE-PLANNING-3.0.md). | +| 2.x | `active` | [`main`](https://github.com/planetlabs/planet-client-python/tree/main) | [Planet Labs Python Client v2 on Readthedocs.io](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/) | April 2023 | TBD | TBD | | +| 1.x | `end-of-life` | [`v1`](https://github.com/planetlabs/planet-client-python/tree/v1) | [Planet Labs Python Client v1 on Github.io](https://planetlabs.github.io/planet-client-python/) | April 2017 | April 2023 | TBD | | ## Installation and Quick Start From 0477d15566afa14b6edaed5431f6507781aae3cc Mon Sep 17 00:00:00 2001 From: "Carl A. Adams" Date: Thu, 17 Apr 2025 08:19:07 -0700 Subject: [PATCH 7/7] fixing typo --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index ae8c8961..1d439f8f 100644 --- a/README.md +++ b/README.md @@ -30,7 +30,7 @@ patch versions address bugs or trivial changes (like documentation). Packages will be released to [PyPi / Planet](https://pypi.org/project/planet/) with semantic version identifiers that comply with [PEP 440](https://peps.python.org/pep-0440/). -The Semantic Versioning stability scheme only applies APIs that +The Semantic Versioning stability scheme only applies to APIs that are considered part of the public API. This includes library APIs exported from the `planet` package and documented in our [SDK developer documentation](https://planet-sdk-for-python-v2.readthedocs.io/en/latest/),