Skip to content

ci: backport API compatibility guard to stable/9 - #468

Merged
emilyoram merged 8 commits into
stable/9from
ci/api-compat-backport-9-py-api-guard-stable9-Mj5ODM
Nov 18, 2026
Merged

emilyoram merged 8 commits into
stable/9from
ci/api-compat-backport-9-py-api-guard-stable9-Mj5ODM

Conversation

@emilyoram

@emilyoram emilyoram commented Nov 17, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Linear backport of #466 (adb8d60) to stable/9, 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 9.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/9's runtime, versions, generator, committed spec, Pyright, and existing workflows; do not import ty or newer main tooling.
  • This branch lacks generate-only: the API workflow calls its existing generator and formatter components directly against the committed bundle.
  • 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 without changing the Python 3.10 runtime floor or runtime test matrix. The initial unbounded range selected unsupported Python 3.15 on the sibling port; two workflow regression cases proved the fix red/green here too.
  • Put the source API-guard guidance in the existing .github/copilot-instructions.md instead of importing main's absent AGENTS.md. Keep contributor docs on Pyright.
  • Use the existing typed metadata fixture for strict Pyright and 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 the existing generator/ruff components with the committed bundle, avoiding make generate's worktree-incompatible hook setup and live spec fetch.
  • Full lint and Pyright, examples typecheck, README snippet and configuration-reference checks pass. The pinned Pyright prints an upgrade-available notice; no version change or warning suppression was made.
  • Acceptance: 352 passed, including 93 API-compat tests (checker, gate exits, approvals, retry re-gating, and workflow Python selection).
  • Real checker: --baseline-major 9 selected PyPI 9.0.6 and reported compatible against this worktree's regenerated SDK.
  • New API workflow passes actionlint. Publish workflow retains exactly the same 23 shellcheck diagnostics as untouched origin/stable/9; the full workflow lint is not green. No diagnostics suppressed.
  • Local artifacts left unstaged: generated/bundled_spec.yaml has required-list ordering drift; uv.lock updates the existing package version 9.0.5 to 9.0.6 and lock revision 5 to 3 during sync. AGENTS.md remains untracked locally after deletion attempts; it was explicitly removed from the committed tree. No generated SDK/stub changes. None of these artifacts is in this PR.
  • The main user checkout and pre-existing worktrees are untouched. CI watch completed successfully at 84edc2d, including API compatibility and Python 3.10-3.14. No merge or auto-merge requested.

Copilot review

One round fetched. All three 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.

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.
@emilyoram
emilyoram requested a review from a team as a code owner November 17, 2026 02:00
Copilot AI balanced review requested due to automatic review settings November 17, 2026 02:00
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.
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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

Unresolved compatibility-checking gaps allow breaking parameter transitions involving *args and type changes between annotated attributes and unannotated class values to pass undetected.

3 open issues
What changed in this PR

Backports the public API compatibility guard to stable/9, comparing the generated Python SDK with the latest published 9.x release to prevent unintended breaking changes.

Changes:

  • Adds API comparison logic, a local Make target, and acceptance tests.
  • Gates stable-branch PRs and releases, supports explicit approvals, and repeats the release check after retries.
  • Documents compatibility requirements and approval procedures.
File Description
tests/​acceptance/​test_api_compat.py Tests API changes, exit codes, approvals, and retry checks.
scripts/​semantic-release-with-retry.sh Retries release races with version and API checks.
scripts/​api-compat-gate.sh Enforces release compatibility and approved overrides.
scripts/​api_compat.py Resolves the PyPI baseline and compares public APIs.
Makefile Adds the api-compat command.
CONTRIBUTING.md Documents compatibility checks and approvals.
AGENTS.md Adds contributor and agent guidance, including compatibility requirements.
.github/​workflows/​publish.yml Integrates the release gate and retry script.
.github/​workflows/​api-compat.yml Adds compatibility checks for stable-branch PRs.
.github/​copilot-instructions.md Adds API compatibility guidance.

Review effort: Balanced

Comment thread scripts/api_compat.py Resolved
Comment thread scripts/api_compat.py Resolved
Comment thread scripts/api_compat.py Resolved
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.
emilyoram added a commit that referenced this pull request Nov 18, 2026
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.
@emilyoram
emilyoram requested a balanced review from Copilot November 18, 2026 00:16
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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The compatibility check conflates async generators with coroutines, missing a breaking change that causes existing async-for callers to raise TypeError.

1 open issue
3 resolved since last review

Review effort: Balanced

Comment thread scripts/api_compat.py Resolved

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

The compatibility checker misses breaking changes involving removed instance __call__ methods, changed NewType underlying types, and newly added variadic parameters in protocols.

No open issues 🎉

3 previously missed issues

In code that hasn't changed since last review

Medium severity Snapshot filter misses instance __call__ methods

scripts/​api_compat.py:198

hasattr(object, "__call__") finds the metaclass's type.__call__, so this filter omits public instance __call__ methods from the snapshot. Removing one therefore reports no break even though existing instance(...) calls raise TypeError. Check vars(object) instead, and add a regression case for removing __call__.

Medium severity Matching NewType names hide underlying type changes

scripts/​api_compat.py:891

Matching NewType names bypass comparison of their recorded underlying types. For example, changing UserId = NewType("UserId", str) to use int while retaining a public get_id() -> UserId signature is accepted, although callers can no longer treat the result as a string. Compare the underlying types in the same assignability direction before accepting matching identities, and add a regression case for this change.

Medium severity New variadic parameters are missed in protocol checks

scripts/​api_compat.py:1147

New variadic parameters are skipped even when checking a protocol's implementations. For example, changing AuthProvider.get_headers(self) to get_headers(self, **kwargs: str) reports no breaks, although existing providers with a no-argument method no longer satisfy the protocol and raise TypeError when passed those newly permitted arguments. Report new *args/**kwargs channels when implemented=True unless the baseline already supports the corresponding channel, and add regression cases for both.

1 resolved since last review

Review effort: Balanced

emilyoram added a commit that referenced this pull request Nov 18, 2026
* 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
emilyoram added a commit that referenced this pull request Nov 18, 2026
* ci: backport API compatibility guard to stable/10

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.

* chore: pin API guard jobs to supported Python 3.12

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.

* 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
@emilyoram
emilyoram merged commit a0d9951 into stable/9 Nov 18, 2026
17 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants