[crandmck]

Overview

Automatically promote stable @contentauth/c2pa-web releases in the versioned API documentation.

Changes

• Consume Changesets publishedPackages explicitly inside the existing publish-docs job. Changesets uses GITHUB_TOKEN to create releases, so another release-published workflow cannot be relied upon. Separately published stable web release events are also supported without triggering package publishing.
• Verify the exact package release tag and npm version with bounded retries. Prepend/promote the exact npm version, remove duplicate occurrences of that version, and preserve older entries and unrelated metadata. Prereleases, drafts, node and other package tags cannot change the web index.
• Commit only api-docs/web-versions.json directly to main when changed, then build and deploy the existing complete site from that same checkout. Push/verification failures stop deployment; reruns avoid empty commits. No tags are modified.
• Reuse the package mapping and exact-version validator in the existing docs generator. Add a package-neutral helper for the node follow-up, targeted tests, and contributor documentation.
• Preserve existing main package publication, Changesets prerelease docs rebuilds, manual docs-only rebuilds, native-binary rebuilds, and existing URLs.

Activation caveat: repository rules/branch protection must allow the GITHUB_TOKEN bot to make this direct index update. Current main protection requires one review and code-owner review; no bypass permission was changed or assumed. Without a suitable bot exception, the push fails visibly before deployment. Only this implementation feature branch was pushed; no production release automation was run.

Testing

• pnpm test:docs: 32 tests passed, including exact prepend/promote/deduplicate, metadata preservation, byte-identical no-op, prerelease/draft/package exclusion and expression-level release/manual/Changesets routing.
• The persistence test executes the actual workflow shell against a temporary Git repository and bare remote with mocked GitHub/npm responses, verifies only the web index is committed, verifies no empty commits on reruns, and checks rejected pushes/missing publication fail nonzero.
• pnpm ci:docs:releases: both configured node/web versioned sites built successfully against public npm.
• Built a temporary web site with the real published 0.16.0 release promoted; checked the default page, all retained release pages and their exact selector metadata. Checked-in indexes were not changed by validation.
• Targeted ESLint, YAML parsing, Prettier and git diff --check passed. Hosted Actions deployment and real protected-branch bot writes were not executed.

Cross-package drift check

If this PR touches Settings/Context, Reader/Builder input validation, or signer/HTTP logic in one package:

• Checked whether c2pa-utilities already owns this logic, and changed it there instead of adding a package-local copy.
• If this package's behavior must differ from its sibling, explained why in a comment.
• If a duplicate was unavoidable for now, add comments explaining why and how it should be reconciled in the future.

N/A: documentation/release automation only; shared package-neutral tooling is reused.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 4575c70

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[ale-adobe]

Release events run with a tag GITHUB_REF, but this repository’s github-pages environment currently permits only the main branch (in the GitHub configuration). I think this means the job would be rejected before version promotion or deployment.

Could we permit the intended web release tags in the environment policy, or dispatch the docs workflow on main instead? I think I have a slight preference for dispatching on main, just to keep everything strongly tied to it.