From 008a5bd76b5b6500ed87e90a02d422e9c8971796 Mon Sep 17 00:00:00 2001 From: Rand McKinney Date: Thu, 12 Nov 2026 11:28:36 -0800 Subject: [PATCH] docs: maintain API versions through release PRs Remove automatic version-list commits and push-triggered deployment. Publish the reviewed list after release publication or manual dispatch. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- .github/PULL_REQUEST_TEMPLATE | 1 + .github/workflows/publish-docs.yml | 34 +----------------------------- README.md | 3 ++- docs/project-contributions.md | 29 +++++++++++++++++-------- 4 files changed, 24 insertions(+), 43 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE b/.github/PULL_REQUEST_TEMPLATE index 823a017e..4b7383c2 100644 --- a/.github/PULL_REQUEST_TEMPLATE +++ b/.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. diff --git a/.github/workflows/publish-docs.yml b/.github/workflows/publish-docs.yml index 0a5876c0..c59e039d 100644 --- a/.github/workflows/publish-docs.yml +++ b/.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 diff --git a/README.md b/README.md index 7407686e..862ac73d 100644 --- a/README.md +++ b/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). diff --git a/docs/project-contributions.md b/docs/project-contributions.md index 45613332..26941bfb 100644 --- a/docs/project-contributions.md +++ b/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.