interlock/.github/workflows/api-compatibility.yml at main · bagowix/interlock · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
name: API compatibility

# griffe check diffs the public API of the working tree against the latest
# release tag: interlock/__init__.py's re-exports plus interlock/integrations/*,
# which is public without being re-exported from __init__ (#104). A detected
# breakage is not automatically wrong — it must be deliberate, so the job is
# failable but overridable: label the pull request `breaking-change` to
# acknowledge it.
on:
  pull_request:

concurrency:
  group: api-compatibility-${{ github.ref }}
  cancel-in-progress: true

permissions:
  contents: read

jobs:
  griffe:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0 # tags must be present locally; griffe resolves the latest one itself
          persist-credentials: false

      - name: Install uv
        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
        with:
          enable-cache: true

      - name: Install dependencies
        run: uv sync --frozen

      - name: Check public API against the latest release
        id: griffe
        continue-on-error: true
        run: |
          # The `-f github` run is what annotates the diff; the gate reads the
          # `oneline` run so one benign finding can be filtered out of it. Every
          # release bumps `interlock.VERSION`, and griffe reports the new value
          # as an attribute change — that is the release mechanism working, not
          # a public-API breakage, and without this every release PR would need
          # the `breaking-change` label. The filter is deliberately narrow (that
          # attribute, in that file, that one check); if griffe ever rewords the
          # message it stops matching and this job fails, which is the safe
          # direction to fail in.
          uv run griffe check interlock --search . -f github || true
          uv run griffe check interlock --search . -f oneline \
            > "${RUNNER_TEMP}/griffe.txt" 2>&1 || true
          grep -vE '^interlock/version\.py:[0-9]+: VERSION: Attribute value was changed:' \
            "${RUNNER_TEMP}/griffe.txt" > "${RUNNER_TEMP}/breakages.txt" || true
          if [ -s "${RUNNER_TEMP}/breakages.txt" ]; then
            cat "${RUNNER_TEMP}/breakages.txt"
            exit 1
          fi

      - name: Acknowledge intentional breakage
        if: steps.griffe.outcome == 'failure' && contains(github.event.pull_request.labels.*.name, 'breaking-change')
        run: echo '::warning::griffe reported a public-API breakage, acknowledged via the "breaking-change" label.'

      - name: Fail on unacknowledged breakage
        if: steps.griffe.outcome == 'failure' && !contains(github.event.pull_request.labels.*.name, 'breaking-change')
        run: |
          echo '::error::griffe detected a public-API breakage. If intentional, label the pull request "breaking-change" and record it in CHANGELOG.md.'
          exit 1