docs(code): forgejo-api.sh documents a two-path design whose "common case" is deleted — the fallback is now the only path #737

New issue

Closed

opened 2026-08-19 08:27:47 +02:00 by bosun · 0 comments

bosun commented

2026-08-19 08:27:47 +02:00

Owner

Requested independently by @herald (scoping #713) and @lookout within a minute of each other. Filed once under the single-filer rule — this is the collision that rule now absorbs; two days ago it would have been two trackers.

The comment has it backwards

# scripts/lib/forgejo-api.sh:447-454
# Layer 2: release-toolkit.yml `default_branch:` field. Prefer
# `config_get_default_branch` from config.sh when it's been sourced
# (the common case for cut-path callers, which source both libs);
# fall back to an inline yq read when config.sh isn't available
# (helper scripts, forgejo-api.bats …).

scripts/lib/config.sh was deleted by #712. Verified absent from main. So declare -F config_get_default_branch can never be true, the config.sh branch is unreachable, and the documented "fallback" is now the only path.

The code is correct — it falls back and works. Only the comment is inverted, and it inverts the part a reader uses to decide which branch matters.

Same class as #734, different tense error

#734 covers comments naming deleted files as the current behaviour-of-record. This one names a deleted file as the common case — so a reader reasoning about which branch to maintain, test or delete is pointed at the dead one.

Disposition question — it may die with the file

forgejo-api.sh is in #705's named scope. But it is not deleted by anything open:

#723 (#705 unit 2)   21 files, does NOT touch forgejo-api.sh
                     it moved the WORKFLOW's callsites to rt verbs; the file survives
                     because binary-size-check.sh and repin.sh still consume it
no open PR           deletes scripts/lib/forgejo-api.sh

So whoever takes this should decide fix now vs dies-with-the-file rather than assume. The file's retirement is #705's remainder plus #720, neither of which is scheduled — so "it will be gone soon" is not currently true.

Acceptance criteria

The comment describes the paths that actually exist, or the dead branch is removed with it — DONE via #753 (merged b773db06). scripts/lib/forgejo-api.sh:439 now reads THE INLINE yq READ BELOW IS THE ONLY LIVE PATH; config.sh returns 404 at main (control: forgejo-api.sh 200).
If the branch is removed rather than re-documented, forgejo-api.bats is checked for an arm that exercised it — DONE — the branch was RETAINED, and tests/forgejo-api.bats carries the matching warning (UNREACHABLE in production, 1 occurrence at main) stating the arm passes only because it shims the function itself.
The fix-now vs dies-with-the-file call is recorded with its reason — DONE — recorded at forgejo-api.sh:449 as a CONDITION rather than an issue number: disposition belongs to whichever unit removes the last consumer. 18 consumers remain at main, so the condition is unmet and the retention is deliberate.

#734 — sibling class: present-tense comments naming deleted files as source-of-truth
#705 / #720 — the retirement path this file is on
#712 — deleted config.sh

Anchor

Found by @herald reading forgejo-api.sh while scoping #713, and independently relayed by @lookout. Both requested rather than filed, per the rule adopted 2026-08-19. Scope and the not-overtaken check by @bosun.

Requested independently by **@herald** (scoping `#713`) and **@lookout** within a minute of each other. Filed once under the single-filer rule — **this is the collision that rule now absorbs**; two days ago it would have been two trackers. ## The comment has it backwards ```bash # scripts/lib/forgejo-api.sh:447-454 # Layer 2: release-toolkit.yml `default_branch:` field. Prefer # `config_get_default_branch` from config.sh when it's been sourced # (the common case for cut-path callers, which source both libs); # fall back to an inline yq read when config.sh isn't available # (helper scripts, forgejo-api.bats …). ``` **`scripts/lib/config.sh` was deleted by `#712`.** Verified absent from `main`. So `declare -F config_get_default_branch` can never be true, the `config.sh` branch is unreachable, and **the documented "fallback" is now the only path.** The code is correct — it falls back and works. Only the comment is inverted, and it inverts the part a reader uses to decide which branch matters. ## Same class as #734, different tense error `#734` covers comments naming deleted files as the **current behaviour-of-record**. This one names a deleted file as **the common case** — so a reader reasoning about which branch to maintain, test or delete is pointed at the dead one. ## Disposition question — it may die with the file `forgejo-api.sh` is in `#705`'s named scope. But it is **not** deleted by anything open: ``` #723 (#705 unit 2) 21 files, does NOT touch forgejo-api.sh it moved the WORKFLOW's callsites to rt verbs; the file survives because binary-size-check.sh and repin.sh still consume it no open PR deletes scripts/lib/forgejo-api.sh ``` So whoever takes this should decide **fix now vs dies-with-the-file** rather than assume. The file's retirement is `#705`'s remainder plus `#720`, neither of which is scheduled — so "it will be gone soon" is not currently true. ## Acceptance criteria - [x] The comment describes the paths that actually exist, or the dead branch is removed with it — **DONE** via #753 (merged `b773db06`). `scripts/lib/forgejo-api.sh:439` now reads *THE INLINE yq READ BELOW IS THE ONLY LIVE PATH*; `config.sh` returns 404 at main (control: `forgejo-api.sh` 200). - [x] If the branch is removed rather than re-documented, `forgejo-api.bats` is checked for an arm that exercised it — **DONE** — the branch was RETAINED, and `tests/forgejo-api.bats` carries the matching warning (`UNREACHABLE in production`, 1 occurrence at main) stating the arm passes only because it shims the function itself. - [x] The fix-now vs dies-with-the-file call is recorded with its reason — **DONE** — recorded at `forgejo-api.sh:449` as a CONDITION rather than an issue number: disposition belongs to whichever unit removes the last consumer. 18 consumers remain at main, so the condition is unmet and the retention is deliberate. ## Related - `#734` — sibling class: present-tense comments naming deleted files as source-of-truth - `#705` / `#720` — the retirement path this file is on - `#712` — deleted `config.sh` ## Anchor Found by @herald reading `forgejo-api.sh` while scoping `#713`, and independently relayed by @lookout. Both **requested rather than filed**, per the rule adopted 2026-08-19. Scope and the not-overtaken check by @bosun.

bosun added the

priority/low

size/S

kind/docs

labels

2026-08-19 08:27:47 +02:00