docs: document the changelog convention and the release process - #41
Merged
Merged
Conversation
Neither was written down. The release mechanism had to be reverse-engineered from tag objects and workflow config to answer "does merging bump a version?" (it does not), and the changelog convention was inconsistent across the only two releases that have one: v0.20.0 came in via a PR, v0.20.1 via a direct push to main, and in both cases the whole section was authored at release time rather than accumulated. Establishes the accumulating convention: every PR that changes observable behaviour adds its entry under `## [Unreleased]`, so releasing is renaming a heading rather than reconstructing history from the log. Calls out that `skills/` is go:embed-ed, so a reference-doc correction ships to users and warrants an entry — that is not obvious from the file layout. Also records the parts that are easy to get wrong: - Releases are manual and tag-driven; merging to main publishes nothing. - The version lives only in the git tag. GoReleaser injects it via ldflags and local builds report `dev`, so there is no version file to bump. - GoReleaser's `changelog:` block generates the GitHub release notes from commit subjects and never touches CHANGELOG.md. It also filters out `docs:`, `chore:`, `test:` and `ci:` — which is why the two existing CHANGELOG commits, both `docs:`, do not appear in any release notes. - `internal/version/update.go` polls the releases API, so tagging immediately advertises the upgrade to every installed CLI. Deploy dependent API changes before tagging, not after. Adds the changelog step to the Adding-a-New-Resource checklist. AGENTS.md is a symlink to this file, so agents pick it up too. Every claim verified against .goreleaser.yaml, .github/workflows/release.yml, cmd/dhq/main.go, internal/version/update.go, skills/embed.go and the annotated tag objects. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Hibw5xsRNGDkYzr1hXsDQz
WalkthroughChangesRelease Documentation
Estimated code review effort: 1 (Trivial) | ~2 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 4✅ Passed checks (4 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@CLAUDE.md`:
- Around line 125-127: Update the release-order guidance in CLAUDE.md to clarify
that internal/version/update.go detects only the latest published GitHub
release, after GoReleaser publication and on the next checker invocation.
Replace the claim that tagging immediately advertises the upgrade while
preserving the instruction to deploy the backend before publishing a dependent
release.
- Around line 106-111: Update the release instructions around Step 4 to push the
release commit to origin/main before pushing the vX.Y.Z tag. Add the explicit
main-branch push while preserving the existing tag creation and push commands.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
Contributor
Author
|
@codex review |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: acdf460132
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Review follow-up on #41. Two defects in the runbook, both of which matter because the whole point of the doc is that someone follows it literally. The release steps committed the changelog on main and then pushed only the tag. Pushing a tag sends the reachable objects but does not move refs/heads/main, so following the sequence verbatim would publish a release containing the changelog while origin/main still lacked it. Adds the explicit `git push origin main`, before the tag, with a note on why the order matters. The update-checker note claimed tagging "immediately advertises the upgrade to every installed CLI". internal/version/update.go:14 reads /releases/latest — the latest *published* release, not the tag — and Check() runs per CLI invocation. The real sequence is tag, GoReleaser builds, release published, then each CLI notices on its next run. The practical advice is unchanged (deploy dependent API changes before tagging) but the stated mechanism now matches the code. Caught by CodeRabbit and Codex on #41. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Hibw5xsRNGDkYzr1hXsDQz
MartaKar
approved these changes
Aug 6, 2026
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
3 participants
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
Writes down two things that weren't documented anywhere:
## [Unreleased], accumulating. Releasing then means renaming a heading, not reconstructing history from the commit log.mainpublishes nothing.CLAUDE.md only, +41 lines.
AGENTS.mdis a symlink to it, so agents get it too.Why
The mechanism had to be reverse-engineered from tag objects and workflow config to answer "does merging bump a version?" — it doesn't. And the changelog convention was inconsistent across the only two releases that have one:
mainIn both cases the whole section was authored at release time — between v0.20.0 and v0.20.1,
cfb35eeis the only commit touching the file; feature PRs #35 and #37 never did. The accumulating convention removes that release-time archaeology.Worth being clear about what this PR is: the convention is already in use on
main, adopted ad hoc — #38 and #39 both added entries under## [Unreleased]. This documents and ratifies that, rather than proposing something new. Which is also why it needs @facundofarias' sign-off: he has cut both prior releases the other way, and he is the one who will follow this runbook.What it records
release.ymlfires onpush: tags: ["v*"].-X main.version={{.Version}};cmd/dhq/main.godefaults todev. There is no version file to bump.changelog:block generates the GitHub release notes from commit subjects and never touchesCHANGELOG.md. It filtersdocs:,chore:,test:,ci:— which is why both existing CHANGELOG commits, bothdocs:, appear in no release notes at all.internal/version/update.goreads/releases/latest— the latest published release, not the tag. The sequence is tag → GoReleaser builds → release published → each CLI notices on its next invocation. Not instant, but not retractable either, so deploy dependent API changes before tagging.skills/isgo:embed-ed, so a reference-doc correction ships to users and warrants a changelog entry — not obvious from the file layout.Also adds the changelog step to the Adding-a-New-Resource checklist.
Review round
Both findings real, both fixed in
b3e7a27; all three threads resolved.main— following them literally publishes the tag whileorigin/mainlacks the changelog commitgit push origin main, explicitly before the tag, with a note on why the order mattersupdate.go:14reads/releases/latest, so it needs a published release and the CLI's next runBoth were defects in a runbook, which is the worst place for them: the doc exists to be followed literally. The push-
maingap was documentation-only —cfb35eeis onmainandv0.20.1points at it, so the step has always happened in practice, it just was never written down.Test plan
Documentation only — no code paths touched.
go build ./cmd/dhq/.github/workflows/release.yml.goreleaser.yaml:22devcmd/dhq/main.go:12docs:/chore:/test:/ci:.goreleaser.yamlchangelog blockinternal/version/update.go:14skills/embed.go:15git cat-file -t v0.20.1→tag🤖 Generated with Claude Code
https://claude.ai/code/session_01Hibw5xsRNGDkYzr1hXsDQz
Summary by CodeRabbit