Skip to content

docs: the release procedure never mentioned the Homebrew tap it publishes - #148

Merged
skyoo2003 merged 1 commit into
mainfrom
docs/release-md-at-root
Sep 6, 2026
Merged

skyoo2003 merged 1 commit into
mainfrom
docs/release-md-at-root

Conversation

@skyoo2003

Copy link
Copy Markdown
Owner

Summary

The release process lived at docs/release.md and covered the tag pipeline end to end except for what it hands to a second repository. This moves it to RELEASE.md at 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) and Documentation-20260906-100200.yaml (#144).

Changes

Documented what was missing — each row was read out of the config, not recalled:

Gap Source of truth What the doc said before
Homebrew tap publishing .goreleaser.yaml:67-82, release.yml:252-260 nothing at all
Four *-alpine tags per release .goreleaser.yaml:93-97 "versioned *-alpine container images"
make changelog VERSION= Makefile:31-36 the two changie commands, by hand
Notes heading must name this tag release.yml:198-209 "verify the file exists"
dry_run defaults to true release.yml:17 unstated
Example version v1.1.0 changes/v1.0.0.md shipped v0.3.0, three releases stale

The 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.md to the archive files list in .goreleaser.yaml. The docs/ tree ships whole but root files are enumerated one by one, so moving the file out of docs/ without this leaves docs/README.md pointing at nothing inside the tarball — the same dangling-link failure the comment above that list already records.

Files Changed

File Change
docs/release.md → RELEASE.md Renamed + content refresh (89 lines)
.goreleaser.yaml Modified — RELEASE.md added to archives[0].files
CONTRIBUTING.md Modified — link
docs/README.md Modified — link
docs/compatibility-policy.md Modified — link
.github/pull_request_template.md Modified — link
changes/unreleased/Documentation-20260906-220000.yaml Added

Docs and config only. No Go source, no tests, no generated code.

Test Plan

  • Every relative link in RELEASE.md resolves 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.
  • No stale docs/release.md reference survives in live docs — grep -rn 'docs/release\.md' over *.md/*.yml/*.yaml returns only .claude/plans/*.plan.md, historical planning records left as written.
  • Pre-commit passed — yaml check covers the new Changie fragment; the Go and ruff hooks had no files to act on.
  • Not run: the Go suite and the boto3 compatibility suite. Nothing in this diff reaches either.

The .goreleaser.yaml edit 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 confirm RELEASE.md lands in the archive.

Checklist

  • Self-reviewed the code
  • Added/updated tests — N/A, docs and config only
  • Lint/format passes (pre-commit hooks green; golangci-lint N/A, no Go changed)
  • Updated documentation (if applicable)
  • Added a Changie changelog fragment for user-facing changes (changie new, see RELEASE.md)

…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.
@github-actions github-actions Bot added the documentation Improvements or additions to documentation label Sep 6, 2026
@skyoo2003
skyoo2003 merged commit 94fa6c2 into main Sep 6, 2026
7 checks passed
@skyoo2003
skyoo2003 deleted the docs/release-md-at-root branch September 6, 2026 02:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant