Merge branch 'carl/initial-drop-from-internal--cicd' into carl/initial-drop-from-internal--docs

Author: carl-adams-planet

.github/workflows/release-publish.yml

@@ -1,6 +1,6 @@
 name: Publish Release
 
-# TODO: create a github release?
+# TODO: create a github release. This is needed to trigger webhooks.
 
 permissions:
   actions: read
@@ -113,26 +113,27 @@ jobs:
           # TODO: re-enable. Disabled for pipeline development
           # nox -s pkg_publish_pypi_prod
 
-  release-readthedocs:
-    name: "Release documentation to readthedocs.com"
-    # needs: release-checkpoint
-    runs-on: ubuntu-latest
-    # environment: production
-    steps:
-      - name: "Checkout code"
-        uses: actions/checkout@v4
-      - name: "Prepare common Python build environment"
-        uses: ./.github/actions/python-build-env-setup
-        with:
-          python-version: ${{ env.PYTHON_VERSION }}
-      - name: "Download Built Documentations"
-        uses: actions/download-artifact@v4
-        with:
-          name: planet-auth-mkdocs-site
-          # github-token: ${{ secrets.GH_PAT }}
-          # repository: '${{ github.repository }}'
-          # run-id: '${{ github.run_id }}'
-          path: site
-      - name: "Nox: Publish to ReadTheDocs"
-        run: |
-          nox -s mkdocs_publish_readthedocs
+  # Read the docs is published via webhook GitHub webhook
+  # release-readthedocs:
+  #   name: "Release documentation to readthedocs.com"
+  #   # needs: release-checkpoint
+  #   runs-on: ubuntu-latest
+  #   # environment: production
+  #   steps:
+  #     - name: "Checkout code"
+  #       uses: actions/checkout@v4
+  #     - name: "Prepare common Python build environment"
+  #       uses: ./.github/actions/python-build-env-setup
+  #       with:
+  #         python-version: ${{ env.PYTHON_VERSION }}
+  #     - name: "Download Built Documentations"
+  #       uses: actions/download-artifact@v4
+  #       with:
+  #         name: planet-auth-mkdocs-site
+  #         # github-token: ${{ secrets.GH_PAT }}
+  #         # repository: '${{ github.repository }}'
+  #         # run-id: '${{ github.run_id }}'
+  #         path: site
+  #     - name: "Nox: Publish to ReadTheDocs"
+  #       run: |
+  #         nox -s mkdocs_publish_readthedocs

RELEASE.md

@@ -0,0 +1,52 @@
+# Version Release
+
+*Planet maintainers only*
+
+Releasing consists of publishing new packages to PyPi and ReadTheDocs, and
+is automated using Github workflows, actions, and webhooks.  Once initiated,
+the release orchestration pipeline will automatically take care of building,
+testing, tagging, and publishing the release.
+
+## Versions and Stability
+
+This library 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).
+
+## Release Workflow
+
+The `main` branch is intended to be kept stable with the most up-to-date
+feature set, and should normally be the branch used for new feature releases.
+Patch branches may be necessary when the need to fix older versions arises.
+
+To release a new version, complete the following steps:
+
+1. Create a release branch off of `main` that bumps the version number in
+   [version.txt](./version.txt), and updates the
+   [changelog.md](./docs/changelog.md).
+2. Collect all features targeted for the intended release in the branch, and
+   create a PR to merge the release branch into `main`.
+3. Ensure that all tests are passing on `main` branch after all merges.
+4. Determine the type of release that should be performed.  This will be passed
+   to the release workflow pipeline as the `build-variant` argument:
+   * `release` - The final build for a new release version.
+   * `rc` - A candidate for the final release.
+   * `beta` - A beta release.
+   * `alpha` - An alpha release
+   * `dev` - A development release.  This is the default.
+5. Initiate a release by activating the [Release Orchestration Workflow](./.github/workflows/release-orchestrate.yml) pipeline:
+   * The release pipeline may be initiated in the GUI.
+   * The release pipeline may be initiated by the `gh` CLI as follows:
+     ```bash
+     gh workflow run .github/workflows/release-orchestrate.yml -f build-variant=_selected_release_variation_
+     ```
+
+## Local Publishing
+
+Most actions taken by the release pipeline are coded into the [noxfile.py](./noxfile.py),
+and so available for local execution.  However, under normal circumstances 
+releases should be driven by the CI/CD release pipeline and not performed 
+locally.  Local publishing skips the mechanism used to generate unique build
+numbers (which is not in the `noxfile.py`), and circumvents audit and review
+processes implemented by the CI/CD system and repository configuration.

noxfile.py

@@ -167,5 +167,9 @@ def mkdocs_serve(session):
 @nox.session(python=_DEFAULT_PYTHON)
 def mkdocs_publish_readthedocs(session):
     session.install("-e", ".[build, docs]")
-    # TODO
+    # TODO - Manual doc publushing
+    print(
+        "ERROR: Read The Docs publishing not implemented in the noxfile."
+        "  Documentation publishing is triggered via GitHub webhook."
+    )
     assert False