From e8acd8259acff220054bbcce637e3dd126395585 Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Thu, 12 Nov 2026 21:21:09 -0400 Subject: [PATCH 1/2] docs: a private pin is the one bump CI cannot check -- and only two of the four config files ARE one The pre-merge page covered the checks a lane runs on its own tree. It did not cover the case engine#2316 hit: a bump of a config/*.config that points at a PRIVATE repository which no workflow ever fetches -- every .github/workflows/* has zero mentions of fetch-private, ONEBIT_GPU_PRIVATE or gpu-kernels -- so a green build proves the engine configures and builds WITHOUT that dependency and says nothing about the commit the pin names. tools/check_pins.py does not help: it compares submodule gitlinks, not config shas. The first draft of this section said "these four files pin private repositories", which is wrong for two of them, and I checked rather than assumed: config/npu-runtime.config repo=1bit-MONSTER/1bit-MONSTER gh api .private -> true config/gpu-kernels.config repo=1bit-MONSTER/gpu-kernels gh api .private -> true config/llama-mirror-hold.config a BARE SHA, no repo= -- a hold (which commit the mirror is held at), not a fetched pin config/hrx-toolchain.config index=https://nightly.repo.amd.com/rocm/whl-next/ -- a PUBLIC index, fetched by scripts/fetch-rocm-sdk.sh So the page now names the two that are private pins, with the `private: true` verification, and says plainly what the other two are. Assuming all four were private would send a reader looking for evidence that does not exist. Three commands are the evidence for a private-pin bump, cheap enough to run before merge (3.4 MB, 1.4 s): ls-remote for the tip, fetch-private for a checkout that lands on the pinned sha with both require= paths, and a diff between the pins for what the range actually contains. Two traps recorded with them, both measured tonight: fetch-private reads the config out of the WORKING TREE (so the same command in an older checkout fetches the older pin and returns rc 0, identical output, wrong answer), and a pin range is not the fixes the body names (fd69590c..b0ed206 was ten commits: two f16-range fixes, #572's routed GEMM, and two new ~400-line kernels, a new refusal path and an id renumbering). --- docs/pre-pr-checks.md | 34 ++++++++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/pre-pr-checks.md b/docs/pre-pr-checks.md index b8c5126bf..fc2d68dc8 100644 --- a/docs/pre-pr-checks.md +++ b/docs/pre-pr-checks.md @@ -37,6 +37,40 @@ Two more, for the moments they are for: | `python3 tools/ci/conflict_triage.py . ` | before resolving a merge with many conflicted files: it classifies them by kind (content, add/add, mod/del, rename) from the index, which text tools cannot see in a file whose conflict has no markers | | `python3 tools/ci/hrx_f16_narrowing.py --check --root ` | when the change could touch f32→f16 narrowing; it lists every body that narrows | +## A private pin (`config/*.config`) is the one bump CI cannot check + +Two of these files pin a **private** repository; they are the ones whose bumps need evidence: + +| file | `repo=` | private? | +|---|---|---| +| `config/npu-runtime.config` | `1bit-MONSTER/1bit-MONSTER` | **yes** (`gh api repos/… --jq .private` → `true`) | +| `config/gpu-kernels.config` | `1bit-MONSTER/gpu-kernels` | **yes** | + +The other two are **not** private pins, and assuming otherwise sends a reader looking for evidence that does not exist: +`config/llama-mirror-hold.config` holds a **bare sha** — which commit the mirror is held at, a decision rather than a fetched +pin — and `config/hrx-toolchain.config` names a **public** index (`index=https://nightly.repo.amd.com/rocm/whl-next/`, fetched by +`scripts/fetch-rocm-sdk.sh`). +`ONEBIT_GPU_PRIVATE` or `gpu-kernels` — so a green `build` on a pin bump proves the engine configures and builds *without* that +dependency and says nothing about the commit the pin names. `tools/check_pins.py` does not help either: it compares **submodule +gitlinks**, not `config/*.config` shas. + +Three commands are the evidence, and they are cheap enough to run before merge (a fetched private pin was 3.4 MB and 1.4 s): + +```bash +git ls-remote https://github.com/1bit-MONSTER/.git refs/heads/main # the pinned sha IS the advertised tip +bash scripts/fetch-private.sh config/.config ~/.cache/scratch-/pin # rc 0, HEAD == the pinned sha, + # both require= paths present +git -C ~/.cache/scratch-/pin diff --stat ..HEAD # what the range actually contains +``` + +Run the first two **from the branch that changes the pin**: `fetch-private.sh` reads the config out of the *working tree*, so the +same command in a checkout of an older commit fetches the older pin and returns **rc 0** — indistinguishable output, wrong answer. + +That third command is the one a reviewer needs. A pin range is not "the fixes I named": measured on engine#2316, +`fd69590c..b0ed206` was **ten commits**, of which two were the f16-range fixes the PR closed, one was #572's routed GEMM, and the +rest were **two new ~400-line kernels, a new refusal path and an id renumbering**. A body that says "three fixes" asks a reviewer +to accept eight things they were not told about. + ## Why the merge-base one is not the same as "it merges" A PR's diff is computed against its **merge base**. If `main` moved under you, every row another lane landed shows in your From 1b038b274201ac4cc3eb49b0834bb6a09a0dafbb Mon Sep 17 00:00:00 2001 From: bong-water-water-bong Date: Thu, 12 Nov 2026 23:31:01 -0400 Subject: [PATCH 2/2] docs: the private-pin check is reachability, not equality -- a healthy pin is normally BEHIND the tip The review at e8acd82 is right and the fix is one command: the page said the pinned sha "IS the advertised tip", which flags almost every correct pin. A pin is normally behind -- main moves after the pin is taken -- so the test that matters is whether the pinned commit still exists on the branch, not whether it is the head of it. Measured on the gpu-kernels bump merged tonight: tip b0ed2060e413, and the previous healthy pin eb0f3839 is TWO commits behind, still an ancestor, and fetch-private.sh checks it out without complaint. By the old wording that pin reads as a failure, and a check that flags correct work is the one people stop running -- taking the two good commands down with it. git ls-remote .git refs/heads/main note the tip git fetch && git merge-base --is-ancestor rc 0: the pin is still on the branch Verified in both directions against the real repository: eb0f3839 IS an ancestor of b0ed2060e4 (healthy though behind), and the reverse test fails, so the direction of the ancestor check matters. Also recorded the opposite signal, which the review raised and the page did not say: a pin that EQUALS the tip is worth a second look for the opposite reason -- the branch moved after review. Everything else the review asked to keep is kept: the "two of the four config files" scoping, and "run the first two from the branch that changes the pin" (an older checkout fetches the older pin and returns rc 0, indistinguishable from success). --- docs/pre-pr-checks.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/pre-pr-checks.md b/docs/pre-pr-checks.md index fc2d68dc8..e4bf8067f 100644 --- a/docs/pre-pr-checks.md +++ b/docs/pre-pr-checks.md @@ -57,12 +57,20 @@ gitlinks**, not `config/*.config` shas. Three commands are the evidence, and they are cheap enough to run before merge (a fetched private pin was 3.4 MB and 1.4 s): ```bash -git ls-remote https://github.com/1bit-MONSTER/.git refs/heads/main # the pinned sha IS the advertised tip +git ls-remote https://github.com/1bit-MONSTER/.git refs/heads/main # note the tip +git fetch && git merge-base --is-ancestor # rc 0: the pin is still on the branch bash scripts/fetch-private.sh config/.config ~/.cache/scratch-/pin # rc 0, HEAD == the pinned sha, # both require= paths present git -C ~/.cache/scratch-/pin diff --stat ..HEAD # what the range actually contains ``` +**The first check is reachability, not equality, and the difference is the whole point.** A pin is *normally behind* the tip — +`main` moves after the pin is taken — so "the pinned sha IS the advertised tip" flags almost every correct pin. Measured on the +gpu-kernels bump merged on 2026-11-13: the tip was `b0ed206` and the *previous, healthy* pin was `eb0f3839`, two commits behind and +still an ancestor, which `fetch-private.sh` checks out without complaint. What the check is *for* is a pin that no longer exists — +a force-push — so the test is `merge-base --is-ancestor`, and a pin that equals the tip is worth a second look for the opposite +reason (the branch moved after review). + Run the first two **from the branch that changes the pin**: `fetch-private.sh` reads the config out of the *working tree*, so the same command in a checkout of an older commit fetches the older pin and returns **rc 0** — indistinguishable output, wrong answer.