ci(release): index each tag on pkg.go.dev

[Behnam-RK]

What

publish gets one new final step, Index the tag on pkg.go.dev.

pkg.go.dev is not a publish target — it is a read-through cache over proxy.golang.org, and a version lands there only once somebody asks the proxy for it. Left alone, that is whenever the first person happens to fetch the module: a coincidence, not a release step. The new step asks, for the tag it just pushed:

curl -fsS "https://proxy.golang.org/github.com/behnam-rk/dezhban/@v/$TAG.info"
curl -fsS "https://pkg.go.dev/github.com/behnam-rk/dezhban@$TAG"

The first is what actually indexes the version; the second just makes pkg.go.dev build the page now rather than on its next index poll.

Design notes

• Warn-only, never fatal. By the time it runs, the tag is pushed and the release is created. A cache warm-up that timed out is not a failed release, and a red run would say it was. On exhaustion it emits ::warning and exits 0.
• Placed last on purpose. The tag push and gh release create are the steps that must not be disturbed, and the documented "re-run publish after a failure that left a tag" path has to keep working unchanged. Warming twice is harmless, so a re-run costs nothing.
• Module path from go list -m, not a hardcoded string. Go is already set up in that job for go run ./tools/relsign. Proxy URLs escape every uppercase letter as !<lower>; the module path is all-lowercase github.com/behnam-rk/dezhban while the repo is Behnam-RK/dezhban, so a rename that introduced a capital would 404 in silence. The step detects that and bails with a warning rather than guess.
• No KIND gate. rc tags are indexed too — pkg.go.dev files prereleases separately and never shows an rc as the latest version.

pkg.go.dev will show no documentation, and that is expected

It renders docs only for licenses on its allow-list, and ours — Hippocratic License 3.0 (Core) with the Dezhban named-entity restriction — is a deliberately modified, non-OSI license its detector will not match. The page still carries the import path, the version list and the install line, with a not-legally-redistributable note where the docs would be.

Nothing is lost in practice: every package here is under internal/, which pkg.go.dev never renders under any license, or is a main package. There is no importable library surface. This is recorded in releasing.md so it does not get chased as a bug later.

Docs

docs/contribute/releasing.md gets a ## pkg.go.dev section (the by-hand commands for a tag this step missed, the warn-only rationale, the license note), and the pipeline diagram's publish line is updated to stay true.

No CHANGELOG entry

Release tooling with no user-facing change. proxy.golang.org already serves all 14 existing tags (v0.1.0…v0.13.0); this only makes the timing deterministic for future ones. Flagging the omission rather than leaving it to be noticed.

Verification

• actionlint .github/workflows/release.yml — only the 2 pre-existing findings (:107 SC2086, :470 SC2035). Nothing from the new step.
• YAML parse confirms the step landed last in publish and no job boundary moved.
• Ran the step body standalone against all three paths: the uppercase guard warns and exits 0; v99.0.0 exhausts all 6 attempts and exits 0 without tripping set -e; v0.13.0 succeeds against both endpoints.
• go test ./internal/help passes — contribute/releasing.md is not a bundled help page, so the renderer's markdown subset does not apply.

Untested end-to-end, and there is no way to rehearse it: dry_run: true skips the whole publish job, so this step is first exercised by the next real release. Watch its output on that run.

🤖 Generated with Claude Code

---

Review loop

Two review rounds by a read-only reviewer, plus a self-read before round 1. Copilot could not be requested from the CLI on this repo (requestReviewsByLogin does not resolve the bot and suggestedActors has no reviewer filter) — worth requesting from the PR page for an independent hosted read.

Round	Findings	Headline	Introduced by
self-read	2	mod="$(go list -m)" unguarded under set -eu, in a step whose comment promises it never fails	the original step
1	7	a doc claim that pkg.go.dev "never renders internal packages under any license" — it does, on a direct URL	the original step
2	6	the retry loop could not fix the one cause its comment gave for it, and the warning handed over a command that would keep failing	3 of 6 were in text round 1 added
3	1	the doc promised the pkg.go.dev page carries an install line; it renders none	the original step
4	1	round 3's fix quoted the license-restriction line on the module page, which does not contain it	round 3

Stopped after round 4 on the second stop condition: its only finding was in round 3's own fix, so loop-introduced findings (1) outnumbered pre-existing ones (0). Rounds 3 and 4 both verified the diff against the live pkg.go.dev and proxy.golang.org responses rather than from memory.

Loop-introduced regressions, named rather than absorbed:

• Round 1 folded three module-path guards into one case and lost their distinct diagnostics with them. "No usable module path" is false of the uppercase branch, where the path is fine and this step is the limitation. Round 2 gave each rejection its own reason back.
• Round 1's new immutability paragraph asserted the stranded-tag recovery was safe because the step runs after the failure that strands a tag. That does not follow — the tag was public for as long as it took to notice. Round 2 made it a precondition with a command to check it.
• Round 1's same paragraph got the re-cut consequence wrong for most users: on the default GOPROXY they are served the cached original silently, which is worse than the checksum mismatch a direct fetcher sees.

Found by testing the fixes rather than by either reviewer: run outside a module, go list -m does not fail — it prints command-line-arguments, a single lowercase word that cleared every guard. A proxy path needs a host in its first element.

Verification of the final step, by extracting the run: block and stubbing go: go list failing, command-line-arguments, an uppercase path, a go.work-style multi-line path, three-attempt exhaustion, and the happy path — all exit 0, each with the right diagnostic, and the valid path emits no warning. shellcheck --shell=bash clean; actionlint reports only the two pre-existing findings at :107 and :470. task check green throughout.

Still unrehearsable: dry_run: true skips the whole publish job, so the step is first exercised by the next real release.