Skip to content

Detect public-API breakage with griffe check in CI #104

Description

@bagowix

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.

Metadata

Metadata

Assignees

Labels

enhancementNew feature or request

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions