Problem
The project makes a strong public promise — v2.0 shipped without breaking
changes, and the standalone breaker surface stays untouched by the pipeline
layer — but nothing mechanically verifies it. Today the only protection against
an accidental signature change, a removed keyword argument, a renamed attribute
or a dropped re-export from interlock/__init__.py is review attention.
Type checkers do not help here: mypy and pyright verify the code is internally
consistent, not that its public surface is compatible with the previous release.
tests/typing_surface.py pins some intended shapes, but only the ones somebody
remembered to write down.
Proposal
Add a CI check based on griffe check, which diffs the public API of the
working tree against a git reference and reports breaking changes
(removed/renamed objects, changed parameter kinds, order and defaults, narrowed
return types):
uvx griffe check interlock -a v2.1.3 --search .
Run it on pull requests against the latest release tag. A breaking change is
not automatically wrong — it is something that must be deliberate, labelled and
reflected in the changelog — so the check should be failable but overridable via
a label or an explicit allowlist entry.
Acceptance criteria
- A PR job resolves the latest
v* tag and runs griffe check against it.
- The job fails on a detected breaking change to
interlock (including the
re-exported pipeline surface) and prints the griffe report.
- A documented escape hatch for intentional breakage (label or config), so a
future major release is not blocked by its own tooling.
interlock/integrations/* is included — those are public too, even though
they are not re-exported from __init__.
- A documented local command in
CONTRIBUTING.md.
- griffe stays a dev/CI-only tool; the core remains dependency-free.
Non-goals
- Generating API documentation with griffe/mkdocstrings; docs stay on Zensical.
- Semantic-versioning automation or release-note generation.
- Checking behavioural compatibility — this is a signature-level guard only.
Problem
The project makes a strong public promise — v2.0 shipped without breaking
changes, and the standalone breaker surface stays untouched by the pipeline
layer — but nothing mechanically verifies it. Today the only protection against
an accidental signature change, a removed keyword argument, a renamed attribute
or a dropped re-export from
interlock/__init__.pyis review attention.Type checkers do not help here: mypy and pyright verify the code is internally
consistent, not that its public surface is compatible with the previous release.
tests/typing_surface.pypins some intended shapes, but only the ones somebodyremembered to write down.
Proposal
Add a CI check based on
griffe check, which diffs the public API of theworking tree against a git reference and reports breaking changes
(removed/renamed objects, changed parameter kinds, order and defaults, narrowed
return types):
uvx griffe check interlock -a v2.1.3 --search .Run it on pull requests against the latest release tag. A breaking change is
not automatically wrong — it is something that must be deliberate, labelled and
reflected in the changelog — so the check should be failable but overridable via
a label or an explicit allowlist entry.
Acceptance criteria
v*tag and runsgriffe checkagainst it.interlock(including there-exported pipeline surface) and prints the griffe report.
future major release is not blocked by its own tooling.
interlock/integrations/*is included — those are public too, even thoughthey are not re-exported from
__init__.CONTRIBUTING.md.Non-goals