docs: the release procedure never mentioned the Homebrew tap it publishes - #148
Merged
Merged
Conversation
…shes The release process lived at docs/release.md and described the tag pipeline end to end except for what it hands to a second repository: .goreleaser.yaml's brews section publishes Formula/devcloud.rb to skyoo2003/homebrew-tap using a token minted from a GitHub App installed only there. A maintainer reading the doc to debug a failed release had nothing to check. Two smaller drifts alongside it. The doc said a tag produces "versioned *-alpine container images" where the config pushes four tags per release (vX.Y.Z, vX.Y, vX, latest), and it walked through changie batch and changie merge by hand while the Makefile has had `make changelog VERSION=` for both. The running example was v0.3.0, three releases behind v1.0.0. Moved to RELEASE.md at the repo root, next to the other governance files, and added to the archives files list in .goreleaser.yaml: docs/README.md links it, and a root file left off that list is absent from the tarball even though the docs tree that points at it ships.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The release process lived at
docs/release.mdand covered the tag pipeline end to end except for what it hands to a second repository. This moves it toRELEASE.mdat the repo root and closes three gaps against the files that actually define the pipeline.Related Issue
N/A — no tracking issue. The Changie fragment references this PR number, following the convention in
Documentation-20260906-210200.yaml(#147) andDocumentation-20260906-100200.yaml(#144).Changes
Documented what was missing — each row was read out of the config, not recalled:
.goreleaser.yaml:67-82,release.yml:252-260*-alpinetags per release.goreleaser.yaml:93-97*-alpinecontainer images"make changelog VERSION=Makefile:31-36release.yml:198-209dry_rundefaults totruerelease.yml:17v1.1.0changes/v1.0.0.mdshippedv0.3.0, three releases staleThe Homebrew gap is the one with teeth: a maintainer debugging a failed release had nothing telling them the formula step needs a GitHub App still installed on the tap, with unexpired
TAP_APP_ID/TAP_APP_PRIVATE_KEY.Moved the file and repointed everything at it —
docs/release.md→RELEASE.md, beside the other governance files. Four inbound links updated (CONTRIBUTING.md,docs/README.md,docs/compatibility-policy.md,.github/pull_request_template.md), and the file's own seven relative links rewritten for the root.Added
RELEASE.mdto the archive files list in.goreleaser.yaml. Thedocs/tree ships whole but root files are enumerated one by one, so moving the file out ofdocs/without this leavesdocs/README.mdpointing at nothing inside the tarball — the same dangling-link failure the comment above that list already records.Files Changed
docs/release.md→RELEASE.md.goreleaser.yamlRELEASE.mdadded toarchives[0].filesCONTRIBUTING.mddocs/README.mddocs/compatibility-policy.md.github/pull_request_template.mdchanges/unreleased/Documentation-20260906-220000.yamlDocs and config only. No Go source, no tests, no generated code.
Test Plan
RELEASE.mdresolves from the repo root — extracted all seven targets and stat'd each:.changie.yaml,.goreleaser.yaml,.github/workflows/release.yml,.github/workflows/cd.yml,CHANGELOG.md,docs/compatibility-policy.md,internal/config/config.go. All present.docs/release.mdreference survives in live docs —grep -rn 'docs/release\.md'over*.md/*.yml/*.yamlreturns only.claude/plans/*.plan.md, historical planning records left as written.The
.goreleaser.yamledit is the one change with a runtime effect, and it is only verifiable at release time — a dry run (Release → Run workflow,dry_run: true) would confirmRELEASE.mdlands in the archive.Checklist
golangci-lintN/A, no Go changed)changie new, see RELEASE.md)