templates_archive_urls' Forgejo comment is wrong — the archive/refs/{tags,heads} paths are served #123

New issue

Open

opened 2026-07-29 15:13:38 +00:00 by claude-bot-andresmgsl · 0 comments

claude-bot-andresmgsl commented

2026-07-29 15:13:38 +00:00

Member

commands/lib/templates.sh:58-66 documents the two forges' archive grammars and
states, of Forgejo:

Forgejo ONE form. /archive/<ref>.tar.gz resolves tags, branches and SHAs
alike, and the refs/{tags,heads}/ paths are not served at all — emitting
them would mean two guaranteed 404s ahead of every fetch and a failure message
listing URLs that never could have worked.

Measured against forgejo.heavyduty.builders, not inferred from the docs.

The claim is false against this instance today (8.0.3+gitea-1.22.0), measured
2026-07-29:

URL	result
`heavy-duty/rig/archive/refs/tags/0.3.0.tar.gz`	200
`heavy-duty/rig/archive/refs/heads/main.tar.gz`	200
`heavy-duty/rig/archive/refs/tags/main.tar.gz` (`main` is a branch)	404

They also disambiguate correctly. On a throwaway public repo carrying a branch
dupe and a tag dupe with different content: refs/tags/dupe served the tag,
refs/heads/dupe served the branch, and the bare /archive/dupe served the
tag.

So the two forges share one grammar, and "two guaranteed 404s" is exactly
backwards — the refs/ paths are the more precise of the two.

Why it is worth fixing rather than leaving

This is not a stale comment beside working code; it is the stated rationale for a
case arm, and it already cost something. !114 inherited the premise and shipped
a Forgejo arm emitting only the bare form, which meant the release channel could
not express "tag only" — the bare form serves branches — and a resolved release
tag whose archive was missing fell through to a same-named branch while
INSTALLED_FROM still recorded the tag. That was caught in review and fixed by
dropping the case arm from ref_candidate_urls entirely; templates_archive_urls
still carries both the arm and the wrong comment.

Whether the instance gained these paths since !110 measured or the earlier
measurement read something else, the file is wrong now.

Spec

Re-measure, then either correct the comment and keep the single-form arm as a
deliberate choice with an accurate reason, or drop the arm so both forges share
the two-URL list — which is what install.sh's ref_candidate_urls now does
after !114, making the two files disagree about the same forge.

Recommend dropping the arm: one grammar, less code, and the refs/ forms are
what let a caller demand a tag specifically.

Coupling that constrains the change: install.sh:135-145 carries a
byte-identical copy of templates_archive_urls, and test/cli.sh diffs the two.
Both move in one commit or the drift test reds.

Tasks

Re-measure all three archive forms against the instance and record the result
Correct the comment in commands/lib/templates.sh
Apply the identical change to install.sh's copy
Reconcile with ref_candidate_urls, which no longer has a case arm

Acceptance criteria

No comment in the tree claims Forgejo does not serve archive/refs/{tags,heads}/
templates_archive_urls' two copies stay byte-identical and test/cli.sh proves it
templates_resolve still fetches successfully from both forges
If the single-form arm is kept, its comment states an accurate reason

Test plan

Extend test/cli.sh's templates_archive_urls cases with whichever grammar is
chosen. Live: fetch a tag, a branch and a SHA from the instance through
templates_resolve and confirm each lands.

Dependencies

Split out of #111 / !114 — @andres was asked there whether this correction should
ride that PR or become its own issue and the question is still open. If it rides,
close this as duplicate.

Filed under @andres's explicit authorization on !114 to create process issues
directly. No queue label applied — ready does not exist yet.

`commands/lib/templates.sh:58-66` documents the two forges' archive grammars and states, of Forgejo: > `Forgejo` ONE form. `/archive/<ref>.tar.gz` resolves tags, branches and SHAs > alike, and the `refs/{tags,heads}/` paths **are not served at all** — emitting > them would mean two guaranteed 404s ahead of every fetch and a failure message > listing URLs that never could have worked. > > Measured against forgejo.heavyduty.builders, not inferred from the docs. The claim is false against this instance today (`8.0.3+gitea-1.22.0`), measured 2026-07-29: | URL | result | |---|---| | `heavy-duty/rig/archive/refs/tags/0.3.0.tar.gz` | **200** | | `heavy-duty/rig/archive/refs/heads/main.tar.gz` | **200** | | `heavy-duty/rig/archive/refs/tags/main.tar.gz` (`main` is a branch) | 404 | They also disambiguate correctly. On a throwaway public repo carrying a branch `dupe` and a tag `dupe` with different content: `refs/tags/dupe` served the tag, `refs/heads/dupe` served the branch, and the bare `/archive/dupe` served the **tag**. So the two forges share one grammar, and "two guaranteed 404s" is exactly backwards — the `refs/` paths are the *more* precise of the two. ## Why it is worth fixing rather than leaving This is not a stale comment beside working code; it is the stated rationale for a `case` arm, and it already cost something. !114 inherited the premise and shipped a Forgejo arm emitting only the bare form, which meant the release channel could not express "tag only" — the bare form serves branches — and a resolved release tag whose archive was missing fell through to a same-named branch while `INSTALLED_FROM` still recorded the tag. That was caught in review and fixed by dropping the case arm from `ref_candidate_urls` entirely; `templates_archive_urls` still carries both the arm and the wrong comment. Whether the instance gained these paths since !110 measured or the earlier measurement read something else, the file is wrong now. ## Spec Re-measure, then either correct the comment and keep the single-form arm as a deliberate choice with an accurate reason, or drop the arm so both forges share the two-URL list — which is what `install.sh`'s `ref_candidate_urls` now does after !114, making the two files disagree about the same forge. Recommend dropping the arm: one grammar, less code, and the `refs/` forms are what let a caller demand a tag specifically. **Coupling that constrains the change:** `install.sh:135-145` carries a byte-identical copy of `templates_archive_urls`, and `test/cli.sh` diffs the two. Both move in one commit or the drift test reds. ## Tasks - [ ] Re-measure all three archive forms against the instance and record the result - [ ] Correct the comment in `commands/lib/templates.sh` - [ ] Apply the identical change to `install.sh`'s copy - [ ] Reconcile with `ref_candidate_urls`, which no longer has a case arm ## Acceptance criteria - [ ] No comment in the tree claims Forgejo does not serve `archive/refs/{tags,heads}/` - [ ] `templates_archive_urls`' two copies stay byte-identical and `test/cli.sh` proves it - [ ] `templates_resolve` still fetches successfully from both forges - [ ] If the single-form arm is kept, its comment states an accurate reason ## Test plan Extend `test/cli.sh`'s `templates_archive_urls` cases with whichever grammar is chosen. Live: fetch a tag, a branch and a SHA from the instance through `templates_resolve` and confirm each lands. ## Dependencies Split out of #111 / !114 — @andres was asked there whether this correction should ride that PR or become its own issue and the question is still open. If it rides, close this as duplicate. *Filed under @andres's explicit authorization on !114 to create process issues directly. No queue label applied — `ready` does not exist yet.*