docs: maintain API versions through release PRs

.github/PULL_REQUEST_TEMPLATE

@@ -4,4 +4,5 @@ _Give a narrative description of what has been changed._
 ## Checklist
 - [ ] This PR represents a single feature, fix, or change.
 - [ ] All applicable changes have been documented.
+- [ ] If this is a stable release introducing a new major/minor version line, its tag has been added to `api-docs/versions.json` (patch releases and prereleases do not add entries).
 - [ ] Any `TO DO` items (or similar) have been entered as GitHub issues and the link to that issue has been included in a comment.

.github/workflows/publish-docs.yml

@@ -6,15 +6,6 @@ on:
 
   workflow_dispatch:
 
-  push:
-    branches: [main]
-    paths:
-      - 'api-docs/**'
-      - 'scripts/generate_api_docs.py'
-      - 'scripts/generate_versioned_api_docs.py'
-      - 'requirements-dev.txt'
-      - '.github/workflows/publish-docs.yml'
-
 permissions:
   contents: read
   pages: write
@@ -26,10 +17,6 @@ concurrency:
 
 jobs:
   deploy:
-    permissions:
-      contents: write
-      pages: write
-      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
@@ -40,26 +27,7 @@ jobs:
           filter: tree:0
           fetch-depth: 0
           ref: main
-
-      - name: Add release to versioned documentation
-        if: github.event_name == 'release' && !github.event.release.prerelease
-        env:
-          RELEASE_TAG: ${{ github.event.release.tag_name }}
-        run: |
-          if [[ ! "$RELEASE_TAG" =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*)?$ ]]; then
-            echo "::error::Release tags must use the format vX.Y.Z with an optional prerelease suffix (e.g. v1.2.3-alpha)"
-            exit 1
-          fi
-          jq --arg tag "$RELEASE_TAG" '.versions = [$tag] + (.versions - [$tag])' \
-            api-docs/versions.json > api-docs/versions.json.tmp
-          mv api-docs/versions.json.tmp api-docs/versions.json
-          git add api-docs/versions.json
-          if ! git diff --cached --quiet; then
-            git config user.name "github-actions[bot]"
-            git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
-            git commit -m "docs: add $RELEASE_TAG to the versioned docs"
-            git push origin HEAD:main
-          fi
+          persist-credentials: false
 
       - name: Setup Pages
         uses: actions/configure-pages@v5

README.md

@@ -102,7 +102,8 @@ API documentation is published at [github.io/c2pa-python/api/c2pa](https://conte
 
 Use the documentation version dropdown to choose a published release.
 The versions are selected in `api-docs/versions.json`; the first entry is the default at the existing documentation URL.
-Publishing a stable GitHub release automatically adds its tag as the default while retaining older versions.
+For a stable release introducing a new major/minor version line, update this list in the release PR before tagging and publishing; patch releases and prereleases do not add entries.
+Documentation is deployed when a GitHub release is published or when the documentation workflow is manually run, without committing or pushing to `main`.
 
 To build documentation locally, see [Contributing to the project](https://github.com/contentauth/c2pa-python/blob/main/docs/project-contributions.md#api-reference-documentation).
 

docs/project-contributions.md

@@ -161,9 +161,16 @@ This uses `sphinx-autoapi` to parse `src/c2pa` directly, avoiding imports of nat
 Edit [api-docs/versions.json](../api-docs/versions.json) to choose the exact
 GitHub release tags shown in the sidebar dropdown. Entries must be unique
 tags such as `v0.38.0`. The first entry is the default served at the existing
-documentation URL. When a stable GitHub release is published, the publishing
-workflow prepends its tag and commits the updated list to `main` before building
-the site. Older entries are retained; pre-releases are not automatically added.
+documentation URL.
+
+For a stable release introducing a new major/minor version line, include the
+version-list update in the release PR alongside the package version bump.
+For example, add `v0.39.0` after `v0.38.0`, or `v1.0.0` after `v0.39.0`;
+patch releases such as `v0.38.1` and prereleases do not add entries.
+Prepend a newer line to make it the default and retain older entries.
+If adding an older maintenance line, place it after the newer default.
+Merge the release PR through normal review and required checks, then tag the
+merged release commit and publish the GitHub release.
 
 Fetch the release tags and build the complete site:
 
@@ -192,9 +199,13 @@ The complete site is written to `api-docs/_build/versioned/`:
 
 The publishing workflow always checks out `main` for the release list and
 build tooling, including when triggered by a release. It rebuilds all selected
-versions when a release is published, when relevant documentation files change
-on `main`, or when manually dispatched. The workflow needs permission to push
-the version-list commit to `main`, including under any branch protection rules.
-The same release-triggered run builds and deploys the updated list; it does not
-rely on the bot's push triggering another workflow. Publish manual changes to
-the list on `main` to add, remove, or reorder dropdown entries.
+versions when a GitHub release is published or when manually dispatched.
+It reads the committed version list without changing it and requires only
+read access to repository contents, plus GitHub Pages deployment permissions.
+It does not run on pushes to `main`: a merged release PR can list a tag before
+its GitHub release exists, and the builder intentionally rejects unpublished
+releases. Do not manually dispatch a build while a listed release is unpublished.
+Patch releases and prereleases rebuild the existing selection without adding
+entries. For documentation-only changes or changes to existing dropdown entries,
+merge a PR into `main`, then manually run **Build and publish docs** from the
+Actions tab to deploy without waiting for another release.