feat(ci): diff every published API against its last release on release PRs

.github/workflows/api-diff.yml

@@ -0,0 +1,54 @@
+name: API diff
+
+# Diffs every published API against its last release on PRs into `release`.
+# A backport fails on any break, since it must keep the published API. The cut
+# (a PR from `main`) only reports, for the migration audit: release-plz bumps
+# the versions after it lands, so its breaks are expected.
+permissions:
+  contents: read
+
+on:
+  workflow_call:
+
+concurrency:
+  group: api-diff-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  diff:
+    name: Public API
+    runs-on: ubuntu-24.04-arm
+    # cargo-semver-checks documents every published crate twice, baseline and current.
+    timeout-minutes: 120
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          persist-credentials: false
+      - uses: ./.github/actions/nix
+      - uses: ./.github/actions/rust-cache
+        with:
+          access-key-id: ${{ secrets.MBX_R2_ACCESS_KEY_ID }}
+          secret-access-key: ${{ secrets.MBX_R2_SECRET_ACCESS_KEY }}
+      # The JS baseline is the API reports committed on `release`.
+      - name: Fetch release
+        run: git fetch --no-tags --depth=1 origin +refs/heads/release:refs/remotes/origin/release
+      - name: Diff against the last release
+        id: diff
+        run: |
+          mode=(--deny)
+          # Only this repository's own `main` is the cut; a fork's `main` is a backport.
+          [[ "$HEAD_REF" != main || "$HEAD_REPO" != "$GITHUB_REPOSITORY" ]] || mode=()
+          nix develop --command just api-diff "${mode[@]}"
+        env:
+          HEAD_REF: ${{ github.head_ref }}
+          HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }}
+          # Lists and downloads the moq-c and moq-ffi release assets.
+          GH_TOKEN: ${{ github.token }}
+      - name: Keep the report
+        if: ${{ !cancelled() && steps.diff.outcome != 'skipped' }}
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7
+        with:
+          name: api-diff
+          path: target/api-diff/
+          retention-days: 30
+          if-no-files-found: error

.github/workflows/release-gate.yml

@@ -30,6 +30,7 @@ jobs:
     timeout-minutes: 10
     outputs:
       android: ${{ steps.filter.outputs.android }}
+      api-diff: ${{ steps.filter.outputs.api-diff }}
       audio-quality: ${{ steps.filter.outputs.audio-quality }}
       cpp: ${{ steps.filter.outputs.cpp }}
       interop: ${{ steps.filter.outputs.interop }}
@@ -82,6 +83,20 @@ jobs:
               - "Cargo.lock"
               - "rust-toolchain.toml"
               - ".github/workflows/android.yml"
+            # Anything a published API is built from, including the lockfiles,
+            # since a bumped dependency can change a re-exported type.
+            api-diff:
+              - "rs/**"
+              - "js/**"
+              - "Cargo.toml"
+              - "Cargo.lock"
+              - "package.json"
+              - "bun.lock"
+              - "cpp/moq/uniffi.toml"
+              - "sh/api-diff/**"
+              - "justfile"
+              - ".github/workflows/api-diff.yml"
+              - ".github/workflows/release-gate.yml"
             audio-quality:
               - "js/watch/**"
               # The container consumer decides what a replay delivers, waits for, and skips, on the
@@ -318,6 +333,13 @@ jobs:
     if: needs.scope.outputs.android == 'true'
     uses: ./.github/workflows/android.yml
 
+  api-diff:
+    name: API diff
+    needs: scope
+    if: needs.scope.outputs.api-diff == 'true'
+    uses: ./.github/workflows/api-diff.yml
+    secrets: inherit
+
   audio-quality:
     name: Audio quality
     needs: scope
@@ -469,6 +491,7 @@ jobs:
       - platform
       - features
       - android
+      - api-diff
       - audio-quality
       - cpp
       - interop

.remarkignore

@@ -9,6 +9,9 @@ pkg/
 result
 **/CHANGELOG.md
 
+# API Extractor reports, generated and checked by each package's build.
+js/*/api/*.api.md
+
 # IETF drafts are kramdown-rfc markdown, not CommonMark; linted by `just
 # drafts check` (kramdown-rfc) instead. doc/draft/ is generated from them by
 # doc/.vitepress/drafts.ts.

CONTRIBUTING.md

@@ -95,7 +95,7 @@ For an advisory against Quinn, follow the advisory triage in [`rs/moq-quic/READM
 
 - A release is cut by hand: a PR merging `main` into `release`, with a merge commit.
 - A breaking cut first writes, on `main`, each changed package's version-transition section in its `MIGRATE.md` (`## 0.3 -> 0.4`) from the migration audit: the `!` subjects since the `release` merge base, each of those PRs' Impact section, and the API diff.
-- Suggest a `release` backport for any serious bug fix (crash, security, data loss, broken interop), whether found on `main` or reported against a release. Land it on `main` first, then port it onto `release` as a separate PR that keeps the published API, so it ships as a patch.
+- Suggest a `release` backport for any serious bug fix (crash, security, data loss, broken interop), whether found on `main` or reported against a release. Land it on `main` first, then port it onto `release` as a separate PR that keeps the published API, so it ships as a patch. The Release gate's API diff (`just api-diff --deny`) fails a backport that changes one; on the cut PR, whose head is `main`, it only reports.
 - After any release publishes, patch or breaking, run `just test wire-compat --remeasure` on `main` and land the rewritten `test/interop/compat/planned-breaks.json` with refreshed reasons. Otherwise the nightly wire-compat check fails on the stale pins.
 - Nothing merges `release` into `main` automatically. Before cutting a minor or breaking release, the maintainer merges `release` into `main` once, so trunk carries the published versions, CHANGELOGs, and any `release`-only commits. It lands as a merge commit with `--admin`, never squashed, so the cut starts from an advanced merge base.