Merge pull request #714 from planetlabs/release-contributing-691

Update release process and add development branch info for contributing

Author: jreiberkyle

CONTRIBUTING.md

@@ -15,11 +15,32 @@ In the issue, provide the following:
 1. Installed dependencies / versions
 1. Error traceback
 
+### Development
+
+#### Development Branch
+
+Most work should start with the latest instance of the `main` branch and be performed in a development branch:
+
+```console
+git checkout main
+git pull
+git checkout -b new-branch-name
+```
+
+#### Branch Naming
+
+Please use the following naming convention for development branchs:
+
+`{up to 3-word summary of topic, separated by a dash)-{ticket number}`
+
+For example: `release-contributing-691` for [ticket 691](https://github.com/planetlabs/planet-client-python/issues/691).
+
 ### Pull Requests
 
 Pull Request (PR) Requirements:
 
 1. Must have a descriptive title. This populates the release changelog.
+1. Must provide a summary of changes and examples of usage input / output in the case of user-interface changes.
 1. Must include updates to relative documentation in docstrings and `docs` folder. See [Documentation](#documentation) section for information on docstring formatting and building.
 1. Must pass all Continuous Integration (CI) checks. See below for more information on CI checks.
 1. Must have at least one approval by a planet maintainer.
@@ -39,45 +60,7 @@ To minimize the feedback loop, we have configured Nox so that it can be used to
 
 ### Releasing
 
-*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.py, release on pypi is triggered manually with the Github Action "Automatically Publish on TestPyPi".
-
-###### Step 1: Release on Github
-
-1. Create a PR with the following:
-  * Update `CHANGES.txt` (**PROPOSAL**: change this to `docs/CHANGELOG.md`)
-    * Include added, changed, depricated or removed features and bug fixes.
-       A list of merged PRs and their titles since the last release can be obtained with `git log <RELEASE_TAG>..HEAD | awk '/Merge pull request/{print;getline;getline;print}`
-    * Sort according to importance
-    * **PROPOSAL**: Adhere to [Keep a Changelog](https://keepachangelog.com/)
-  * Bump version in `planet/__version__.py`
-    * **PROPOSAL**: Version number is determined by [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
-1. Merge the PR
-1. Create a new github release:
-  * Set Tag to the version number specified in `planet/__version__.py`
-  * Copy Description from the new entry in `docs/CHANGELOG.md`
-  * Select "This is a pre-release" if applicable
-  * Select "Create a discussion for this release"
-
-###### Step 2: Release on pypi
-
-1. Verify the test release on [test.pypi.org](https://test.pypi.org/project/planet/)
-1. Run the Github Action "Publish on PyPi"
-
-###### Local publishing
-
-Publishing to testpypi and pypi can also be performed locally with:
-
-```console
-  $ nox -s build publish-testpypi
-```
-then
-```console
-  $ nox -s publish-pypi
-```
-this approach requires specifying the pypi/testpypi api token as the password at the prompt.
-
+The release process is outlined in [RELEASE.md](RELEASE.md).
 
 ## <a name="development-tools"></a>Development Tools
 

RELEASE.md

@@ -0,0 +1,60 @@
+# Version Release
+
+*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 "Automatically Publish on TestPyPi".
+
+#### Release Naming Conventions
+
+The following are the release naming conventions:
+
+1. Current dev version: Bumped version of last release with `dev` added to the end
+    * **PROPOSAL**: Version number is determined by [Semantic Versioning](https://semver.org/spec/v2.0.0.html)
+1. Release version: Remove `dev` from current dev version
+
+Example:
+* If
+ * Previous Release Version ==  `1.0.0`
+* Then
+ * Current Dev Version: `1.0.1dev`
+ * Release Version: `1.0.1`
+ * Next Dev Version: `1.0.2dev`
+
+## Release Workflow
+
+#### Step 1: Release on Github
+*NOTE: This section refers to version names given in Release Naming Conventions section above.*
+1. Create a release branch named `release-{Release Version}`
+1. Make the following changes for the release
+  * Update `CHANGES.txt` (**PROPOSAL**: change this to `docs/CHANGELOG.md`)
+    * Include added, changed, depricated or removed features and bug fixes.
+       A list of merged PRs and their titles since the last release can be obtained with `git log <RELEASE_TAG>..HEAD | awk '/Merge pull request/{print;getline;getline;print}`
+    * Sort according to importance
+    * **PROPOSAL**: Adhere to [Keep a Changelog](https://keepachangelog.com/)
+  * Update `planet/__version__.py` to Release Version
+1. Create a PR for the release branch (named after release branch), wait for CI to pass
+1. Create a new github release:
+  * Set Tag to the version number specified in `planet/__version__.py`, aka Release Version
+  * Copy Description from the new entry in `docs/CHANGELOG.md`
+  * Select "This is a pre-release" if applicable
+  * Select "Create a discussion for this release"
+1. Update `planet/__version__.py` to Next Dev Version
+1. Merge PR for release branch
+
+###### Step 2: Release on pypi
+
+1. Verify the test release on [test.pypi.org](https://test.pypi.org/project/planet/)
+1. Run the Github Action "Publish on PyPi"
+
+###### Local publishing
+
+Publishing to testpypi and pypi can also be performed locally with:
+
+```console
+  $ nox -s build publish-testpypi
+```
+then
+```console
+  $ nox -s publish-pypi
+```
+this approach requires specifying the pypi/testpypi api token as the password at the prompt.