versioning guidance

CONTRIBUTING.md

@@ -5,19 +5,40 @@ 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
 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).
 

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