diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 85541bf9..7c30d45e 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 semantic +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..1d439f8f 100644 --- a/README.md +++ b/README.md @@ -23,11 +23,69 @@ 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). + +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 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/), +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 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. +* **`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 | 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