You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
ci: backport API compatibility guard to stable/10 - #467
The PR and release gates compare the generated public API with the latest non-prerelease 10.x release on PyPI. Only exit code 1 can be waived by api-break-approved or the manual release input; setup errors still fail. The release gate runs again after a retry resets to a newer branch tip.
Branch adaptations
Retain stable/10's runtime, versions, generator, committed spec, and existing workflows.
This branch lacks the source retry script and its version-check helper. Carry the retry script touched by ci: block public API breaks on stable branches #466, wire it into publishing, and inline the target's existing major-version check instead of importing the unrelated helper fix.
Pin setup-python and UV_PYTHON to 3.12 for the API and release jobs, overriding local Python pins without changing the Python 3.10 runtime floor or runtime test matrix. The initial unbounded range selected 3.15 in CI, which the pinned pydantic-core cannot build on; two workflow regression cases proved the fix red/green.
Carry only the source API-guard contributor guidance; omit unrelated main instructions. Add nine hermetic approval/exit-code cases to the source tests.
No generated output, live spec refresh, dependency/toolchain upgrade, labels, release dispatch, or ruleset changes.
Validation
Generation: uv sync on Python 3.12, then make generate-only with the committed bundle. This runs the generation components without make generate's worktree-incompatible hook setup or live spec fetch.
Full lint and ty typecheck, examples typecheck, README snippet and configuration-reference checks pass.
Acceptance: 953 passed, including 93 API-compat tests (checker, gate exits, approvals, retry re-gating, and workflow Python selection).
Real checker: --baseline-major 10 selected PyPI 10.1.5 and reported compatible against this worktree's regenerated SDK.
New API workflow passes actionlint. Publish workflow retains exactly the same 22 shellcheck diagnostics as untouched origin/stable/10; the full workflow lint is not green. No diagnostics suppressed.
No generated or lockfile drift. The main user checkout and pre-existing worktrees are untouched.
CI watch completed successfully at 052dcd1, including API compatibility and Python 3.10-3.14. No merge or auto-merge requested.
Copilot review
One round fetched. Both findings concern unchanged checker logic from merged #466, not the target adaptations, and remain unresolved under the linear-port scope:
Backport #466 (adb8d60)
following the design in camunda/orchestration-cluster-api-csharp#545.
Stable regeneration must not silently release public API breaks.
Keep the checker and approval semantics, including re-gating after a
release retry resets to a new tip. Retain the target major-version
check inline because its helper is absent. Select Python >=3.11 for
tool jobs while retaining the Python 3.10 runtime floor.
Relates to #465.
The unconstrained workflow selected Python 3.15, but stable branch
pydantic-core supports only through 3.14. Use the already-tested
3.12 interpreter for API and release jobs without changing the SDK
runtime floor or its version matrix.
A regression test for both jobs failed before the fix and now passes.
Relates to #465.
The reason will be displayed to describe this comment to others. Learn more.
🟡 Changes recommended
The compatibility gate can miss breaking API changes because subclass attribute reassignments retain inherited types and public SDK re-exports without __all__ are ignored.
Backports the public API compatibility guard to stable/10, checking the generated SDK against the latest published 10.x release to catch breaking changes, including upstream spec drift.
Changes:
Adds stable-branch PR and release checks with explicit approvals that waive breaking changes, but not setup errors.
Adds release retries that repeat version validation and API checks after moving to a newer branch tip.
Adds acceptance coverage, a local Make target, and contributor guidance while retaining Python 3.10 SDK support.
File
Description
tests/acceptance/test_api_compat.py
Tests API comparisons, exit codes, approvals, and retry checks.
scripts/semantic-release-with-retry.sh
Retries concurrent release conflicts and revalidates the new branch tip.
scripts/api-compat-gate.sh
Enforces release compatibility and handles approved breaks.
scripts/api_compat.py
Downloads the baseline wheel and compares public API signatures and types.
Makefile
Adds the api-compat target.
CONTRIBUTING.md
Documents compatibility rules, checks, and approvals.
AGENTS.md
Adds stable-branch API compatibility guidance.
.github/workflows/publish.yml
Integrates the release gate, manual approval, and retry script.
.github/workflows/api-compat.yml
Adds PR checks after regeneration from the committed spec.
Review of the stable/10 and stable/9 backports (#467, #468) found
breaks the checker reported as compatible. Each now has a regression
that fails on the previous commit:
- A package without __all__ re-exports what it imports from the SDK;
removing `from .client import Client` broke `from pkg import Client`
unnoticed. Packages now record their SDK imports; a plain module's
imports stay incidental.
- A subclass reassigning an inherited attribute in __init__ kept the
base class's inferred type, so `int` -> `int | None` went unseen.
The subclass's inference now replaces an inherited one, but never a
declared annotation.
- `f(*args, label="")` -> `f(label="", *args)` makes `f("x",
label="y")` bind label twice.
- An annotated attribute becoming a plain class value, and the
reverse, skipped the type comparison.
stable/10's generated SDK is still compatible with 10.1.5 under the new
checks, as it was before.
Ports the policy fixed in the Rust SDK (camunda/orchestration-cluster-
api-rust#170).
PR check: every PR to stable/N was compared with the last published
N.x release. Once an approved breaking PR merged, its breaks stayed in
that comparison and failed every later PR until the next release. A PR
is now compared with its base commit, both sides regenerated from
their own checked-in bundled spec, so it answers only for its own
changes. It still passes when the major has no release yet.
Release gate: a labelled PR merged anywhere, `main` included, approved
every break in the release, including any pushed after it. The search
(scripts/api-break-approvals.sh, shared with the Rust SDK) now counts
only PRs merged into the release branch since the baseline. An approval
covers the API as of that PR's merge: when the newest approved merge
is not HEAD, the gate regenerates that commit and blocks any break
added since. Tests run the gate against a real git repo with the
checker, generator and approval search stubbed; disabling the
post-approval comparison fails four of them.
Strict pyright on stable/9 (its pre-push hook) rejects untyped lambdas in
the parametrized approval-search test and an unannotated list. Plain
typed parameters keep the test identical across branches.
Review of the stable/10 and stable/9 backports (#467, #468) found
breaks the checker reported as compatible. Each now has a regression
that fails on the previous commit:
- A package without __all__ re-exports what it imports from the SDK;
removing `from .client import Client` broke `from pkg import Client`
unnoticed. Packages now record their SDK imports; a plain module's
imports stay incidental.
- A subclass reassigning an inherited attribute in __init__ kept the
base class's inferred type, so `int` -> `int | None` went unseen.
The subclass's inference now replaces an inherited one, but never a
declared annotation.
- `f(*args, label="")` -> `f(label="", *args)` makes `f("x",
label="y")` bind label twice.
- An annotated attribute becoming a plain class value, and the
reverse, skipped the type comparison.
stable/10's generated SDK is still compatible with 10.1.5 under the new
checks, as it was before.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
The compatibility checker misses breaking protocol-property return narrowing and incorrectly flags field or key removals from orphan models, leaving gaps in break detection and causing unnecessary gate failures.
No open issues 🎉
2 previously missed issues
In code that hasn't changed since last review
Skip field and key checks for orphan data models
scripts/api_compat.py:1194
Removing a field from a model that no API accepts or returns still reports attribute removed, despite the documented exemption for orphan schemas. Unused TypedDict keys have the same issue at scripts/api_compat.py:1306–1307, so these permitted changes unnecessarily block the gate. Skip compatibility checks for all orphan data-model kinds at the start of _check_class, while retaining symbol-existence checks, and add regression cases for field and key removal.
Detect narrowed return types on protocol properties
scripts/api_compat.py:1288
Protocol properties also constrain customer implementations, but this branch only checks widening. Changing a protocol property's return from str | None to str currently produces no breaks (verified with two synthetic packages), even though an existing implementation returning str | None no longer satisfies the protocol. Check narrowing for protocol properties as well, as the method-return and annotated-attribute paths already do, and add a regression case.
* chore: catch five more API breaks the compatibility checker missed
Review of the stable/10 and stable/9 backports (#467, #468) found
breaks the checker reported as compatible. Each now has a regression
that fails on the previous commit:
- A package without __all__ re-exports what it imports from the SDK;
removing `from .client import Client` broke `from pkg import Client`
unnoticed. Packages now record their SDK imports; a plain module's
imports stay incidental.
- A subclass reassigning an inherited attribute in __init__ kept the
base class's inferred type, so `int` -> `int | None` went unseen.
The subclass's inference now replaces an inherited one, but never a
declared annotation.
- `f(*args, label="")` -> `f(label="", *args)` makes `f("x",
label="y")` bind label twice.
- An annotated attribute becoming a plain class value, and the
reverse, skipped the type comparison.
stable/10's generated SDK is still compatible with 10.1.5 under the new
checks, as it was before.
* ci: scope api-compat approvals to the changes they cover
Ports the policy fixed in the Rust SDK (camunda/orchestration-cluster-
api-rust#170).
PR check: every PR to stable/N was compared with the last published
N.x release. Once an approved breaking PR merged, its breaks stayed in
that comparison and failed every later PR until the next release. A PR
is now compared with its base commit, both sides regenerated from
their own checked-in bundled spec, so it answers only for its own
changes. It still passes when the major has no release yet.
Release gate: a labelled PR merged anywhere, `main` included, approved
every break in the release, including any pushed after it. The search
(scripts/api-break-approvals.sh, shared with the Rust SDK) now counts
only PRs merged into the release branch since the baseline. An approval
covers the API as of that PR's merge: when the newest approved merge
is not HEAD, the gate regenerates that commit and blocks any break
added since. Tests run the gate against a real git repo with the
checker, generator and approval search stubbed; disabling the
post-approval comparison fails four of them.
* chore: type the approval-search test parameters
Strict pyright on stable/9 (its pre-push hook) rejects untyped lambdas in
the parametrized approval-search test and an unannotated list. Plain
typed parameters keep the test identical across branches.
* chore: preserve Python export and call semantics in API checks
* chore: check protocol variadics and exempt unused model fields
* ci: backport API compatibility guard to stable/9
Backport #466 (adb8d60)
following the design in camunda/orchestration-cluster-api-csharp#545.
Stable regeneration must not silently release public API breaks.
Keep the checker and approval semantics, including re-gating after a
release retry resets to a new tip. Retain the target version check,
Pyright and generation commands. Select Python >=3.11 for tool jobs
without changing the Python 3.10 runtime floor. Adapt the typed test
fixture and place guard guidance in the existing instructions.
Relates to #465.
* chore: retain only stable/9 contributor instructions
The cherry-pick carried the main-only AGENTS.md despite the target
having no such file. Remove it from the port; the source guard
guidance is already in the existing Copilot instructions.
Relates to #465; backports #466.
* chore: pin API guard jobs to supported Python 3.12
The unconstrained workflow can select Python 3.15, but stable branch
pydantic-core supports only through 3.14. Use the already-tested
3.12 interpreter for API and release jobs without changing the SDK
runtime floor or its version matrix.
A regression test for both jobs failed before the fix and now passes.
Relates to #465.
* chore: catch five more API breaks the compatibility checker missed
Review of the stable/10 and stable/9 backports (#467, #468) found
breaks the checker reported as compatible. Each now has a regression
that fails on the previous commit:
- A package without __all__ re-exports what it imports from the SDK;
removing `from .client import Client` broke `from pkg import Client`
unnoticed. Packages now record their SDK imports; a plain module's
imports stay incidental.
- A subclass reassigning an inherited attribute in __init__ kept the
base class's inferred type, so `int` -> `int | None` went unseen.
The subclass's inference now replaces an inherited one, but never a
declared annotation.
- `f(*args, label="")` -> `f(label="", *args)` makes `f("x",
label="y")` bind label twice.
- An annotated attribute becoming a plain class value, and the
reverse, skipped the type comparison.
stable/10's generated SDK is still compatible with 10.1.5 under the new
checks, as it was before.
* ci: scope api-compat approvals to the changes they cover
Ports the policy fixed in the Rust SDK (camunda/orchestration-cluster-
api-rust#170).
PR check: every PR to stable/N was compared with the last published
N.x release. Once an approved breaking PR merged, its breaks stayed in
that comparison and failed every later PR until the next release. A PR
is now compared with its base commit, both sides regenerated from
their own checked-in bundled spec, so it answers only for its own
changes. It still passes when the major has no release yet.
Release gate: a labelled PR merged anywhere, `main` included, approved
every break in the release, including any pushed after it. The search
(scripts/api-break-approvals.sh, shared with the Rust SDK) now counts
only PRs merged into the release branch since the baseline. An approval
covers the API as of that PR's merge: when the newest approved merge
is not HEAD, the gate regenerates that commit and blocks any break
added since. Tests run the gate against a real git repo with the
checker, generator and approval search stubbed; disabling the
post-approval comparison fails four of them.
* chore: type the approval-search test parameters
Strict pyright on stable/9 (its pre-push hook) rejects untyped lambdas in
the parametrized approval-search test and an unannotated list. Plain
typed parameters keep the test identical across branches.
* chore: preserve Python export and call semantics in API checks
* chore: check protocol variadics and exempt unused model fields
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Linear backport of #466 (adb8d60) to stable/10, following the API compatibility design in camunda/orchestration-cluster-api-csharp#545.
The PR and release gates compare the generated public API with the latest non-prerelease 10.x release on PyPI. Only exit code 1 can be waived by api-break-approved or the manual release input; setup errors still fail. The release gate runs again after a retry resets to a newer branch tip.
Branch adaptations
Validation
Copilot review
One round fetched. Both findings concern unchanged checker logic from merged #466, not the target adaptations, and remain unresolved under the linear-port scope:
No checker redesign or second review requested. These are known detection gaps, not waived API breaks.
Related issues
Relates to #465 (already closed). Backports #466.