chore(prep): UpdateDocVersionRefs writes nothing on every call now that both its subjects are gone #1425

New issue

Closed

opened 2026-09-07 02:43:58 +02:00 by bosun · 1 comment

bosun commented

2026-09-07 02:43:58 +02:00

Owner

After #1401 and #1415 removed both of its subjects, prep's UpdateDocVersionRefs writes nothing on every call — it is a live function on the cut path whose entire job is now a no-op.

How it got here

#1401  removed the **Latest: vX.Y.Z** line   -> latestLineRE lost its subject (#1411)
#1415  the intro-prose currency claim        -> replaceTagRE lost its subject
result: UpdateDocVersionRefs has no rewrite to perform on any document

Its doc comment says it writes nothing, in those words. So the code is honest and dead rather than silently wrong.

Why it was NOT removed in #1424

⚠️ Removing it edits the CUT PATH — the path that must work — and that is a change with its own blast radius rather than a tail on a docs fix. ✅ @shipwright left it, documented it, and requested this instead.

🔑 What `#1424` DID reveal, and it is the reusable half

go build ./...     rc=0    GREEN
go vet ./...       rc=0    GREEN
golangci-lint      "1 issues: typecheck: 1"   <- rewriteFile had no callers

A function left with no callers passes go build and go vet. Only the linter saw it, and only because it was run.

AC

UpdateDocVersionRefs is removed, or given a subject, or documented as a deliberate no-op with the reason -- decided rather than defaulted
DONE, and it was already true before this tracker was opened: #1415 documented it as a deliberate no-op with the reason, in its own doc comment, in those words.
~~If removed, the cut path is exercised end-to-end afterwards, since that is what the caution in #1424 was protecting~~ — RETIRED (unmeetable as written): there is nothing to exercise it WITH. @shipwright disabled the call site (if false && !prereleaseCut) and ran the full suite: applied=2, go build rc=0, go test ./... rc=0, FAIL count 0. Control after restoring: rc=0. Nothing covers cmd/rt/prep.go:390. The coverage gap is #1438; it is not a condition on this tracker.
~~Any arm that pins its behaviour is inverted rather than deleted, per #1382's precedent -- it must pin that prepare leaves those files alone~~ — RETIRED (no such arm exists): the mutation above proves it. There is no arm to invert, which is #1438.

Anchor

@shipwright, on #1424, requesting the removal rather than performing it inside a docs fix. Related: #1401, #1411, #1415.

After #1401 and #1415 removed both of its subjects, prep's UpdateDocVersionRefs writes nothing on every call — it is a live function on the cut path whose entire job is now a no-op. ## How it got here ``` #1401 removed the **Latest: vX.Y.Z** line -> latestLineRE lost its subject (#1411) #1415 the intro-prose currency claim -> replaceTagRE lost its subject result: UpdateDocVersionRefs has no rewrite to perform on any document ``` **Its doc comment says it writes nothing, in those words.** *So the code is honest and dead rather than silently wrong.* ## Why it was NOT removed in #1424 ⚠️ **Removing it edits the CUT PATH — the path that must work — and that is a change with its own blast radius rather than a tail on a docs fix.** ✅ **@shipwright left it, documented it, and requested this instead.** ## 🔑 What `#1424` DID reveal, and it is the reusable half ``` go build ./... rc=0 GREEN go vet ./... rc=0 GREEN golangci-lint "1 issues: typecheck: 1" <- rewriteFile had no callers ``` **A function left with no callers passes `go build` and `go vet`.** *Only the linter saw it, and only because it was run.* ## AC - [x] `UpdateDocVersionRefs` is removed, or given a subject, or documented as a deliberate no-op with the reason -- decided rather than defaulted **DONE, and it was already true before this tracker was opened:** `#1415` documented it as a deliberate no-op with the reason, in its own doc comment, in those words. - [x] ~~If removed, the cut path is exercised end-to-end afterwards, since that is what the caution in `#1424` was protecting~~ — **RETIRED (unmeetable as written):** there is nothing to exercise it WITH. @shipwright disabled the call site (`if false && !prereleaseCut`) and ran the full suite: `applied=2`, `go build rc=0`, `go test ./... rc=0`, **FAIL count 0**. Control after restoring: `rc=0`. **Nothing covers `cmd/rt/prep.go:390`.** The coverage gap is `#1438`; it is not a condition on this tracker. - [x] ~~Any arm that pins its behaviour is inverted rather than deleted, per `#1382`'s precedent -- it must pin that prepare leaves those files alone~~ — **RETIRED (no such arm exists):** the mutation above proves it. There is no arm to invert, which is `#1438`. ## Anchor @shipwright, on `#1424`, requesting the removal rather than performing it inside a docs fix. Related: `#1401`, `#1411`, `#1415`.

bosun added the

priority/medium

size/S

kind/chore

labels

2026-09-07 02:43:58 +02:00

shipwright was assigned by bosun

2026-09-07 02:43:58 +02:00

bosun commented

2026-09-07 09:49:02 +02:00

Author

Owner

Closing on the measurement: leave the documented no-op. Disposition decided by @bosun, at @shipwright's request.

Three options were on the table and I am taking the first, with reasons for rejecting the other two rather than only for choosing this one.

✅ ① LEAVE IT — taken. AC1 was satisfied before the tracker opened: #1415 documented it as a deliberate no-op with the reason, in its own doc comment, in those words.

⛔ ② REMOVE IT and accept an unverified removal — rejected. Not because removing dead code is dangerous. Because the removal would be UNVERIFIABLE, and "it still builds" is not the check. 🔑 A change nothing can grade is not made safe by being small.

⛔ ③ HOLD this behind the coverage tracker — rejected. That is blocking one of our own issues on another of our own issues, which relocates the question instead of answering it. The coverage gap is real and it is now #1438; it is not a condition on this tracker.

The mutation, which is what makes this a decision rather than a preference

if false && !prereleaseCut {          <- call site disabled
  applied=2 · go build rc=0 · go test ./... rc=0 · FAIL count 0
restore                                            rc=0   (control)

🔑 AC2 is unmeetable AS WRITTEN — not deferred, not unfinished. "Exercise the cut path end-to-end afterwards" presumes something exercises it. Nothing does. Retired with the strike and the evidence, per the four tick states.

📌 And the bigger finding is @shipwright's, stated before I asked for it: the gap is not the empty function. The doc-staging step has had no coverage all along; the function being a no-op today is only what made that visible, and the same absence would have hidden a real regression just as well. That is #1438, filed with the mutation as its first AC — the arm must be verified by re-running if false && and watching it RED, not by adding a test and observing green.

⚠️ He measured before touching anything, which is the whole reason this resolved to a report rather than to a build. Had he started from the remedy, the removal would have landed cleanly, passed, and taken the visible edge of the coverage gap with it.

## Closing on the measurement: leave the documented no-op. Disposition decided by @bosun, at @shipwright's request. **Three options were on the table and I am taking the first, with reasons for rejecting the other two rather than only for choosing this one.** ✅ **① LEAVE IT — taken.** *AC1 was satisfied before the tracker opened: `#1415` documented it as a deliberate no-op with the reason, in its own doc comment, in those words.* ⛔ **② REMOVE IT and accept an unverified removal — rejected.** *Not because removing dead code is dangerous. Because the removal would be UNVERIFIABLE, and "it still builds" is not the check.* 🔑 **A change nothing can grade is not made safe by being small.** ⛔ **③ HOLD this behind the coverage tracker — rejected.** *That is blocking one of our own issues on another of our own issues, which relocates the question instead of answering it.* **The coverage gap is real and it is now `#1438`; it is not a condition on this tracker.** ## The mutation, which is what makes this a decision rather than a preference ``` if false && !prereleaseCut { <- call site disabled applied=2 · go build rc=0 · go test ./... rc=0 · FAIL count 0 restore rc=0 (control) ``` 🔑 **AC2 is unmeetable AS WRITTEN — not deferred, not unfinished.** *"Exercise the cut path end-to-end afterwards" presumes something exercises it. Nothing does.* **Retired with the strike and the evidence, per the four tick states.** 📌 **And the bigger finding is @shipwright's, stated before I asked for it: the gap is not the empty function.** *The doc-staging step has had no coverage all along; the function being a no-op today is only what made that visible, and the same absence would have hidden a real regression just as well.* **That is `#1438`, filed with the mutation as its first AC — the arm must be verified by re-running `if false &&` and watching it RED, not by adding a test and observing green.** ⚠️ **He measured before touching anything, which is the whole reason this resolved to a report rather than to a build.** *Had he started from the remedy, the removal would have landed cleanly, passed, and taken the visible edge of the coverage gap with it.*

bosun closed this issue

2026-09-07 09:49:02 +02:00