first cut at API checking

Cabal-syntax and Cabal only; I assume cabal-install-solver is not
a public API.

.github/workflows/check-api.yml

@@ -0,0 +1,91 @@
+name: Check API
+
+on:
+  push:
+    paths-ignore:
+      - "doc/**"
+      - "**/README.md"
+      - "CONTRIBUTING.md"
+    branches:
+      - master
+  pull_request:
+    paths-ignore:
+      - "doc/**"
+      - "**/README.md"
+      - "CONTRIBUTING.md"
+  release:
+    types:
+      - created
+  workflow_call:
+
+jobs:
+  check-api:
+    name: Check API using ${{ matrix.sys.os }} ghc-${{ matrix.ghc }}
+    runs-on: ${{ matrix.sys.os }}
+    strategy:
+      matrix:
+        # we check API only on one platform and ghc release, since it shouldn't
+        # vary elsewhere and the API tracer is sensitive to both
+        sys:
+          - { os: ubuntu-latest }
+        ghc:
+          [
+            # print-api only supports a small subset of ghc versions
+            "9.10.1",
+          ]
+
+    steps:
+
+      - uses: actions/checkout@v4
+
+      - uses: haskell-actions/setup@v2
+        id: setup-haskell
+        with:
+          ghc-version: ${{ matrix.ghc }}
+          cabal-version: 3.12.1.0 # see https://github.com/haskell/cabal/pull/10251
+          ghcup-release-channel: https://raw.githubusercontent.com/haskell/ghcup-metadata/master/ghcup-prereleases-0.0.8.yaml
+
+      # I was going to use the canned action, but it only supports a single package and reinstalls the same binary each time
+      - name: Install print-api
+        run: |
+          wget -q https://github.com/Kleidukos/print-api/releases/download/v0.1.0.1/print-api-0.1.0.1-Linux-static-${{ matrix.ghc }}-x86_64.tar.gz
+          tar -xzvf print-api-0.1.0.1-Linux-static-${{ matrix.ghc }}-x86_64.tar.gz
+          chmod +x print-api
+
+      # print-api needs environment files. It also doesn't make a lot of sense to use the cached builds, sadly,
+      # since they're special in different ways (bootstrap and validate) and we want a vanilla build. And there
+      # isn't enough cache space to make a third cache, even though this is a very limited build.
+      - name: Build Cabal with environment files
+        run: cabal build Cabal-syntax Cabal --write-ghc-environment-files=always
+
+      - name: Generate Cabal-syntax and Cabal APIs
+        run: |
+          ./print-api --package-name Cabal-syntax > Cabal-syntax-${{ matrix.ghc }}-${{ matrix.sys.os }}.api
+          ./print-api --package-name Cabal > Cabal-${{ matrix.ghc }}-${{ matrix.sys.os }}.api
+
+      # for convenience, since large changes would be a pain to reconstruct from diffs and
+      # contributors aren't guaranteed to have ubuntu-latest handy
+      # run this _before_ checking the API, so hopefully they're available on failure
+      # because that's the point of making them artifacts!
+      - uses: actions/upload-artifact@v4
+        with:
+          name: Cabal-api
+          path: '*.api'
+
+      - name: Check Cabal-syntax and Cabal APIs
+        run: |
+          rc=0
+          if cmp Cabal-syntax/Cabal-syntax-${{ matrix.ghc }}-${{ matrix.sys.os }}.api Cabal-syntax-${{ matrix.ghc }}-${{ matrix.sys.os }}.api; then
+            :
+          else
+            echo "Cabal-syntax API changed"
+            rc=1
+          fi
+          if cmp Cabal/Cabal-${{ matrix.ghc }}-${{ matrix.sys.os }}.api Cabal-${{ matrix.ghc }}-${{ matrix.sys.os }}.api; then
+            echo "Cabal API changed"
+            rc=1
+          fi
+          if [ $rc -ne 0 ]; then
+            echo "The new APIs are in the artifact uploaded in the previous step."
+            exit $rc
+          fi

CONTRIBUTING.md

@@ -193,6 +193,20 @@ We use automated whitespace convention checking. Violations can be fixed by
 running [fix-whitespace](https://hackage.haskell.org/package/fix-whitespace). If
 you push a fix of a whitespace violation, please do so in a _separate commit_.
 
+API Changes
+-----------
+
+The `Check API` job tests the `Cabal` and `Cabal-syntax` packages for API changes.
+It's still something of a work in progress, but even in its current state it is
+useful to indicate when a changelog is needed and which PRs aren't appropriate
+for backports.
+
+If the `Check API` job fails, you will find in its build artifacts (at the bottom
+of the "upload artifacts" step, immediately before the actual API check) a ZIP file
+containing the new API records. You can download this and replace the existing API
+descriptions, which can be found in the package top level directories, with `.api`
+suffixes.
+
 Other Conventions
 -----------------