Skip to content

Commit

Permalink
first cut at API checking
Browse files Browse the repository at this point in the history
Cabal-syntax and Cabal only; I assume cabal-install-solver is not
a public API.
  • Loading branch information
geekosaur committed Aug 16, 2024
1 parent 969343a commit ad55b8c
Show file tree
Hide file tree
Showing 4 changed files with 19,141 additions and 0 deletions.
81 changes: 81 additions & 0 deletions .github/workflows/check-api.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,81 @@
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: |
echo "Cabal-syntax API changes:"
diff Cabal-syntax/Cabal-syntax-${{ matrix.ghc }}-${{ matrix.sys.os }}.api Cabal-syntax-${{ matrix.ghc }}-${{ matrix.sys.os }}.api
echo
echo "Cabal API changes:"
diff Cabal/Cabal-${{ matrix.ghc }}-${{ matrix.sys.os }}.api Cabal-${{ matrix.ghc }}-${{ matrix.sys.os }}.api
13 changes: 13 additions & 0 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,6 +193,19 @@ 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 job report page) 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
-----------------

Expand Down
Loading

0 comments on commit ad55b8c

Please sign in to comment.