Skip to content

Add non-blocking CI check to detect API breaking changes #1145

@LalatenduMohanty

Description

@LalatenduMohanty

Problem

PR #1129 renamed the WorkContext.__init__ parameter constraints_file to constraints_files and changed it from a required positional argument to a keyword-only argument with a default. This was an API-incompatible change that broke downstream consumers (specifically the AIPCC wheels builder).

The commit message documented the breaking change in the body, but it was easy to miss during review — there was no automated signal to flag it.

Proposal

Add a non-blocking CI job that automatically detects public API signature changes on pull requests using griffe. This would cover:

  • Renamed or removed function/method parameters
  • Changed parameter types or defaults
  • Removed functions, classes, or modules
  • Changed class __init__ signatures

The check would:

  • Run only on pull requests
  • Compare the PR branch's API against origin/main
  • Use continue-on-error: true so it does not block merging — it serves as a warning system
  • Not be added to Mergify merge conditions

This gives PR authors and reviewers visibility into breaking changes without adding friction to the development process.

Implementation sketch

  1. Add a scripts/check_api_changes.py script using griffe to diff the API
  2. Add an api-check hatch environment with griffe as a dependency
  3. Add a non-blocking job to .github/workflows/check.yaml

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions