feat(release): changes/ fragment system + generator, .public-surface snapshot + CI migration gate, deprecation-warning + anchor harnesses, Trusted Publishing, relicense CHANGELOG entry

1 files changed, 35 insertions, 0 deletions

diff --git a/.github/workflows/github-actions.yml b/.github/workflows/github-actions.yml
index f9f49d6..0fcb6bf 100644
--- a/.github/workflows/github-actions.yml
+++ b/.github/workflows/github-actions.yml
@@ -21,6 +21,10 @@ jobs:
             python: '3.11'
             command: 'uv run pyright edify'
             os: 'ubuntu-latest'
+          - name: 'public-surface'
+            python: '3.11'
+            command: 'uv run python tools/surface.py --check'
+            os: 'ubuntu-latest'
           - name: 'docs'
             python: '3.11'
             command: 'uv run --group docs sphinx-build -b html docs dist/docs && uv run --group docs sphinx-build -b linkcheck docs dist/docs'
@@ -59,6 +63,37 @@ jobs:
       - name: ${{ matrix.name }}
         run: ${{ matrix.command }}
 
+  surface-migration-gate:
+    name: 'public-surface migration gate'
+    runs-on: ubuntu-latest
+    if: github.event_name == 'pull_request'
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0
+        with:
+          fetch-depth: 0
+      - name: require a changes/ fragment when the public surface moves
+        env:
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+          PR_TITLE: ${{ github.event.pull_request.title }}
+        run: |
+          if echo "$PR_TITLE" | grep -q '\[no-migration\]'; then
+              echo "PR marked [no-migration]; skipping the fragment requirement."
+              exit 0
+          fi
+          if git diff --quiet "$BASE_SHA" "$HEAD_SHA" -- .public-surface; then
+              echo "Public surface unchanged; no fragment required."
+              exit 0
+          fi
+          added_fragments=$(git diff --name-only --diff-filter=A "$BASE_SHA" "$HEAD_SHA" -- 'changes/*.rst' | grep -v 'changes/README.rst' || true)
+          if [ -z "$added_fragments" ]; then
+              echo "::error::.public-surface changed but no changes/ fragment was added. Add a fragment describing the migration, or mark the PR title with [no-migration]."
+              exit 1
+          fi
+          echo "Public surface changed and a changes/ fragment accompanies it:"
+          echo "$added_fragments"
+
   install-without-regex-extra:
     name: 'install: edify (no [regex] extra)'
     runs-on: ubuntu-latest