docs(shims): Go proxy registration step is undocumented; add packaging assertions to ARCH-013 #517

Activity

1. rhuanbarreto

   added

   documentationImprovements or additions to documentationImprovements or additions to documentation

   on Jul 25, 2026
2. rhuanbarreto commented on Jul 26, 2026

   

   rhuanbarreto

   on Jul 26, 2026

   ContributorAuthor

   More actions

   Verified every claim in this issue against the current tree. Most of it is already handled; scoping down to one item.

   Will fix: automate the Go proxy registration

   This is the only knowledge the memory deletion actually cost. git log --all --grep="proxy.golang.org" returns zero commits — unlike the other shim items below, it was never captured in a commit message, so it existed only as memory-file content.

   The reason it matters, plainly: Go has no upload step. publish-go-tag pushes a git tag and stops, because proxy.golang.org is a pull-through cache that only learns a version exists when someone requests it. pkg.go.dev is populated from that cache, so until something asks, the new version isn't listed. Nothing is broken — go install ...@vX.Y.Z works, and the first real user triggers the fetch — but the package looks stale or absent to anyone browsing.

   Fix is a step in publish-go-tag, not a runbook note: the whole thing is one unauthenticated curl, and automating it means nobody has to remember it. Needs care on the version string — the tag is shims/go/vX.Y.Z but the proxy path wants .../shims/go/@v/vX.Y.Z.info.

   Won't fix: the ARCH-013 packaging assertions

   Declining #2 as a cost/benefit call. The Maven waitUntil and the toolchain cache-version arrangement are set-and-forget config in low-churn files; the rules would be guarding against edits that essentially don't happen.

   One correction for the record, so nobody over-relies on it later: zizmor's cache-poisoning rule covers enabling caches in publish workflows (enable-cache: false for setup-uv, bundler-cache: false for setup-ruby in publish-shims.yml). It does not inspect cache keys, so it isn't what keeps cache-version correct. And release-binaries.yml's cache: false came from #462 (a4b9829c) fixing intermittent bun: command not found from stale toolchain caches — not from a zizmor finding.

   Dropped: already covered

   Maven inline comment — unnecessary. pom.xml:138 was changed in its own commit and git blame -L 138,138 lands on 059a4db0, whose message carries more than a comment would: the v0.40.0 incident, the symptom, and the 15-minute timeout figure.

   PyPI README trap — not a live gap. pyproject.toml:9 has readme = "README.md", the file exists, and ARCH-013 shim-readme-sync already asserts it byte-identical to the root README.

   RubyGems working-directory — already satisfied and self-documented: working-directory: shims/rubygem at publish-shims.yml:177/179/183, with explanatory comments already in the Rakefile and Gemfile.

   All three trace to the same commit 059a4db0, which is also where project_shim_publishing.md was created — the memory file and the commit message were duplicates from birth, so deleting it lost nothing here.

   Note on the cache-version count

   For accuracy, since this issue's §3 called the memory's location list wrong: the memory was closer. cache-version: ${{ env.ImageOS }} appears 6 times across 4 files (release.yml ×3, update-lock.yaml, update-llms.yaml, setup-bun-project/action.yml), not three times in one. The memory's single error was listing release-binaries.yml, which uses cache: false — correctly, since no cache can't serve a stale one.
3. rhuanbarreto commented on Jul 26, 2026

   

   rhuanbarreto

   on Jul 26, 2026

   ContributorAuthor

   More actions

   Retracting the one item I said we'd fix in the comment above. I tested the premise and it does not hold — this issue collapses to zero work.

   The Go module is already indexed, with no registration step anywhere

   Source	Result
   git tag --list 'shims/go/*'	19 tags
   proxy.golang.org/github.com/archgate/cli/shims/go/@v/list	19 versions, none missing
   pkg.go.dev/github.com/archgate/cli/shims/go?tab=versions	v0.50.0 listed, published Jul 17 2026

   The pkg.go.dev dates are the decisive evidence. They track releases one-for-one — Jul 17 (v0.50.0), Jul 16 (v0.49.0), Jul 14 (v0.48.4), Jul 13 (v0.48.3), then Jun 22/20/15/11/10 across the v0.45.x series — and they long predate the proxy request I made while investigating, so they cannot be an artifact of it.

   Nothing in .github/ installs the published module either; the only setup-go is in code-pull-request.yml for building the shim. Registration is happening unprompted: Go's module index re-checks origins for modules it already knows, and this one has been known since v0.40.0.

   Why the original reading was wrong

   The recovered memory line —

   Trigger registration via curl https://proxy.golang.org/<module>/@v/<version>.info

   — describes how Go's pull-through model works, and gives a manual lever for forcing an index refresh. It is not a record of a required release step that went missing. The failure it implies (pkg.go.dev not listing a new version) has not occurred across 19 releases. Adding the curl to publish-go-tag would introduce a step with no observable effect, which a future reader would reasonably assume is load-bearing.

   Final disposition: closing, no changes

   • Go proxy registration — not a gap; auto-discovery has covered all 19 releases.
   • Maven waitUntil / toolchain cache-version assertions — declined; set-and-forget config in low-churn files.
   • Maven inline comment — unnecessary; git blame -L 138,138 shims/maven/pom.xml reaches 059a4db0, whose message carries the v0.40.0 incident, the symptom, and the 15-minute timeout figure.
   • PyPI README trap — already covered by ARCH-013 shim-readme-sync.
   • RubyGems working-directory — already satisfied and already commented in the Rakefile and Gemfile.

   Worth recording for whatever else came out of the same audit: every item here was derived from a memory file's framing rather than from a tested outcome. The check that settled it was one command comparing tags to the proxy's version list. Audit-generated issues in this batch should have their described failure reproduced before any of them is scheduled.
4. rhuanbarreto

   closed this as not plannedon Jul 26, 2026