From 1bc926c338bff7e6691bde5edbe0d88d53d83bbc Mon Sep 17 00:00:00 2001 From: Anthony Minessale II Date: Thu, 13 Aug 2026 17:43:45 -0500 Subject: [PATCH] =?UTF-8?q?ci:=20DRIFT=20is=20advisory=20here=20=E2=80=94?= =?UTF-8?q?=20python=20is=20the=20reference,=20not=20a=20port?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit For the nine ports DRIFT is a hard gate, and rightly so: it asks whether the port still matches the reference, and a port can be wrong about that. This repo IS the reference. python_signatures.json is DERIVED from this tree, so python cannot drift from itself. A difference after regeneration means only that the snapshot in porting-sdk has not caught up yet — which is bookkeeping downstream of this repo, not a defect in it. Failing python's CI on that inverted the dependency. Adding public API here — an ordinary thing to do in the reference implementation — required a lockstep change in another repo before python could go green, so the source of truth was blocked on its own derivative. That is why a release sat unpublishable while a coordinated pass was in flight. The gate now reports the delta and returns 0. The delta is worth printing: it is exactly the new surface, and exactly what gets regenerated downstream after this merges. Nothing is weakened for the ports. They still check against the reference with a hard DRIFT gate. This tree is still enumerated on every run by SIGNATURES, which still fails loudly if it cannot be enumerated, and which SEMVER-DIFF still depends on — so a version bump that does not match the surface change is caught here, as before. Verified both paths: clean snapshot reports "matches this tree"; with new public API present it prints the shortstat and passes. Full run-ci otherwise unchanged. --- scripts/run-ci.sh | 36 ++++++++++++++++++++++++++++++++++-- 1 file changed, 34 insertions(+), 2 deletions(-) diff --git a/scripts/run-ci.sh b/scripts/run-ci.sh index 007c3fcb..280fb9fa 100755 --- a/scripts/run-ci.sh +++ b/scripts/run-ci.sh @@ -94,6 +94,38 @@ python3 -m pip freeze 2>/dev/null \ | grep -iE '^(fastapi|starlette|pydantic|pydantic-core|anyio|uvicorn|httpx|requests)==' \ | sed 's/^/ /' || true +# DRIFT — ADVISORY here, and only here. +# +# For the nine PORTS, DRIFT is a hard gate: it asks whether the port still matches +# the reference. That question has a right answer and a port can be wrong. +# +# This repo IS the reference. python_signatures.json is DERIVED from this tree, so +# python cannot drift from itself — a difference after regeneration means only that +# porting-sdk's committed snapshot has not caught up yet. Failing python's CI for +# that made adding public API here require a lockstep change in another repo, which +# inverted the dependency: the source of truth was blocked on its own derivative. +# +# So it reports and does not fail. The delta is printed because it is genuinely +# useful — it is exactly the new surface, and it is what a maintainer regenerates +# downstream after this merges. Nothing is weakened for the ports: they still check +# against the reference with a hard gate, and the reference is still enumerated on +# every run by the SIGNATURES gate above (which SEMVER-DIFF depends on, and which +# still fails loudly if this tree cannot be enumerated at all). +drift_gate() { + if (cd "$PORTING_SDK_DIR" && git diff --quiet -- python_signatures.json 2>/dev/null); then + echo " oracle snapshot matches this tree." + return 0 + fi + local stat + stat="$(cd "$PORTING_SDK_DIR" && git diff --shortstat -- python_signatures.json 2>/dev/null)" + echo " ADVISORY: this tree's public surface differs from porting-sdk's committed" + echo " oracle (${stat# }). That is expected when you add or change public API." + echo " Not a failure: python is the reference, the oracle is derived from it." + echo " Say so in your PR ('changes public surface') and a maintainer regenerates" + echo " it downstream — see .github/CONTRIBUTING.md." + return 0 +} + # FMT — ruff format. LOCAL applies; CI --check. fmt_gate() { if [ -n "${CI:-}" ]; then @@ -207,8 +239,8 @@ sched_gate SIGNATURES desc="regenerate python_signatures.json (reference oracle) --signalwire-python "$PORT_ROOT/signalwire" \ --out "$PORTING_SDK_DIR/python_signatures.json" -sched_gate DRIFT deps=SIGNATURES desc="python_signatures.json unchanged after regen" \ - -- bash -c "cd '$PORTING_SDK_DIR' && git diff --quiet -- python_signatures.json" +sched_gate DRIFT deps=SIGNATURES desc="oracle snapshot vs this tree (ADVISORY — python is the reference)" \ + --fn drift_gate sched_gate SEMVER-DIFF deps=SIGNATURES desc="version bump matches surface change vs python_signatures.baseline.json (the reference is not exempt)" \ -- python3 "$PORTING_SDK_DIR/scripts/semver_diff.py" --port python --repo "$PORT_ROOT"