From 70ecc98507d6b23ab068893ce4abaf73beb26679 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Thu, 5 Nov 2026 22:55:22 -0400 Subject: [PATCH] pin_watch: the exit codes it documents are the five it returns MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `--pr-body` for a repo that did not move ends in `sys.exit("… did not move …")`, i.e. a string, so Python exits **1** — the header called it "a usage error (3)", and 3 is `--self-test` failing. The header's exit paragraph also folded "--check found nothing readable" into 1 where the tool returns 2 (`main()` ends with `return 2` when every pin lands in `notes`, and the self-test asserts it), while docs/model-pins.md said "There are three outcomes" and stopped at 2, leaving 3 and 4 — both of which CI and the workflow branch on — undocumented. Measured on main `1dfe2708` before the change, against the reviewer's own repro: $ printf '{"changes":[],"notes":[],"pins":1,"published_not_pinned":[]}' > sweep.json $ python3 tools/pin_watch.py --pr-body fake/moved --from sweep.json # -> 1 $ python3 tools/pin_watch.py # -> 2 The docs table was {0,1,2} against a header listing {0,1,2,3,4}, so the pair disagreed on the same five codes; now both list all five, with 0 widened to "or the requested output was printed", 1 to "or the requested --pr-body repo did not move", 2 to "usage or no pin could be read at all". The check that keeps them together: `--self-test` now compares the header's list with the table's rows (it fails on main's pair, verified against `git show origin/main:…`), and runs the tool in a subprocess so the did-not-move code is asserted at the **process** level (1), not through the test's own `SystemExit` mapping — which is why the old assertions could not have caught it. Self-test **56 -> 60**, `tests/workflow_shell_test.py` all checks passed. Reported by lane pi-docs in #1193's review thread; that PR merged with this loose end (it is #1181's line, on files #1193 last owned). Reported, not filed: no issue number. --- docs/model-pins.md | 12 +++++++----- tools/pin_watch.py | 33 ++++++++++++++++++++++++++++++--- 2 files changed, 37 insertions(+), 8 deletions(-) diff --git a/docs/model-pins.md b/docs/model-pins.md index 63d095ae8..c2d90d76e 100644 --- a/docs/model-pins.md +++ b/docs/model-pins.md @@ -66,13 +66,15 @@ therefore reconciled on every check: the commit for "did upstream move", and the current `main` and writes a Markdown report. It exits non-zero when anything moved, so the run is visible even if the PR is not opened. -There are three outcomes, and the exit code keeps them apart: +The exit code keeps them apart (`tools/pin_watch.py`'s header carries the same five): | exit | meaning | what the workflow does | |---|---|---| -| 0 | every pin was read and is at the revision we record | nothing | -| 1 | something moved, or a pinned repo is **gone upstream** (`404` — a delete, a rename and a privatisation look the same) | opens one bump PR per moved repo; a gone repo is reported and refused for bumping, a human decides | -| 2 | **no pin could be read at all** — a Hub outage or rate-limit is not a quiet day | the job fails | +| 0 | every pin was read and is at the revision we record — or the requested output (`--pr-body`, `--pin`, `--bump`) was printed | nothing | +| 1 | something moved, a pinned repo is **gone upstream** (`404` — a delete, a rename and a privatisation look the same), or `--pr-body` was asked for a repo that did not move | opens one bump PR per moved repo; a gone repo is reported and refused for bumping, a human decides | +| 2 | a usage error, or **no pin could be read at all** — a Hub outage or rate-limit is not a quiet day | the job fails | +| 3 | `--self-test` failed | nothing: this is CI's code, not the daily run's | +| 4 | `--bump` needs a human: the repo or a tracked file is gone upstream | skips that repo and says so | The report's first line counts what was read (`N of M checked, K not checked`), and the all-clear sentence only appears when nothing was left unread: a watcher whose "clean" and "could not check" are the same @@ -108,7 +110,7 @@ with it, so "nobody could check this" never looks like "nothing moved". ## Commands ```bash -tools/pin_watch.py --check # the daily comparison; writes pin-report.md, exit 0/1/2 (above) +tools/pin_watch.py --check # the daily comparison; writes pin-report.md, exit 0/1/2/3/4 (above) tools/pin_watch.py --check --orgs A,B # ...and census our own orgs for a repo nobody pinned tools/pin_watch.py --check --no-template # same, without the template range reads tools/pin_watch.py --check --json sweep.json # ...and the same sweep as JSON diff --git a/tools/pin_watch.py b/tools/pin_watch.py index 653ffd182..9812ba565 100644 --- a/tools/pin_watch.py +++ b/tools/pin_watch.py @@ -32,7 +32,7 @@ known. --no-template skips that read (the report then says it was not checked). --pr-body R print the bump PR's body for repo R and exit 0. With --from, it comes from the sweep a --check wrote (`--json`); without it the sweep is repeated, one full Hub read per - repo. A repo that did not move is a usage error (3), not a body. + repo. A repo that did not move exits 1 with that message: no body exists for it. --pin R... print the pin entry for each repo at its current main (adding a pin, or re-deriving one). --bump R rewrite repo R's entry in --pins to the current main, for the tracked files only; a tracked file that vanished upstream is refused rather than dropped silently. @@ -46,8 +46,9 @@ --from FILE with --pr-body: read the sweep from that JSON instead of re-checking every pin. --self-test run against fixtures, no network. -Exit codes: 0 nothing moved, 1 a pin moved (or --check found nothing readable), 2 usage, -3 --self-test failed, 4 --bump needs a human (the repo or a tracked file is gone upstream). +Exit codes: 0 nothing moved (or the requested output was printed), 1 a pin moved or the requested +--pr-body repo did not move, 2 usage or --check could read no pin at all, 3 --self-test failed, +4 --bump needs a human (the repo or a tracked file is gone upstream). The workflow reads 4 as "skip this repo and say so", and any other non-zero as an unread upstream: a bump that did not happen because the Hub was down is not a clean day either. @@ -59,6 +60,7 @@ import hashlib import json import os +import re import struct import sys import time @@ -710,6 +712,23 @@ def body_of(repo): expect("a census row is refused as a bump, in those words", (rc_unpinned != 0 and "published but not pinned" in msg_unpinned), True) expect("a pin that moved still prints its body", body_of("fake/moved"), (0, "")) + + # the header's exit codes are the ones the tool returns at the process level, not only in + # main(): a repo that did not move is 1 (the `sys.exit("…")` string branch), not the 3 this + # line used to claim, and a bare run is usage (2) + import subprocess + nomove = os.path.join(d, "sweep-nomove.json") + with open(nomove, "w", encoding="utf-8") as f: + json.dump({"date": "2026-11-05", "pins": 1, "changes": [], "notes": [], + "published_not_pinned": []}, f) + ran = subprocess.run([sys.executable, os.path.join(ROOT, "tools", "pin_watch.py"), + "--pr-body", "fake/still", "--from", nomove], + capture_output=True, text=True) + expect("a --pr-body repo that did not move exits 1", ran.returncode, 1) + expect("...and says no body exists for it", "did not move" in ran.stderr, True) + with contextlib.redirect_stdout(_io.StringIO()): + usage_rc = main([]) + expect("a bare invocation is usage, exit 2", usage_rc, 2) head, tree = fake_head_new, fake_tree # a container/LoRA repo has no `.gguf`: pinning it must still be possible, or the published @@ -775,6 +794,14 @@ def fake_head_flaky(repo): unread_md = open(report_path, encoding="utf-8").read() expect("the count is in the first line", "0 of 2 checked, 2 not checked" in unread_md.splitlines()[0], True) expect("and still no all-clear", "Every pinned upstream repo is at" in unread_md, False) + # the exit-code list in this file's header and the table in docs/model-pins.md are read by the same + # people in two places, and they disagreed once: the header called a repo that did not move a usage + # error (3) where the tool exits 1, and the table stopped at 2. Compared, not proofread. + header = " ".join((__doc__ or "").split("Exit codes:", 1)[1].split("\n\n", 1)[0].split()) + listed = re.findall(r"(?