docs: CHANGELOG style convention and make build version trap - #61
Merged
Conversation
Record the convention in CLAUDE.md (one line per entry, what changed and its user-visible effect; rationale and measurements belong in the PR description) and tighten the existing [Unreleased] entries to match. Released sections are left as published history.
A plain `make build` stamps cmd.version=dev, and runUpdate refuses ""/"dev", so `grant update` can never succeed on a default local build. Record the trap and the `make build VERSION=0.7.0` workaround in CLAUDE.md's Build section and the README development block.
Three numbers had drifted from the tree or contradicted themselves: - The dependency bullet claimed a full module graph of 95; `go list -m all` reports 109. The other two figures (33 build-graph modules, 39 go.mod requires) were correct but are brittle. The load-bearing content is the named exception and its justification, so the counts are dropped and the direction of the change kept. - `go-isatty` was pinned at v0.0.20 in prose; go.mod is on v0.0.24. Point at go.mod instead of restating a version that will drift again. - "20 linters enabled" contradicted its own list, which enumerates 19. Dropped the count and noted the list is exhaustive under disable-all.
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
1 participant
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.
Docs-only. Three commits.
1. CHANGELOG style convention — records in CLAUDE.md that entries are one short line saying what changed and its user-visible effect; rationale, evidence and measurements belong in the PR description. Applies to
[Unreleased]and everything from now on; released sections are published history and are left alone. The existing[Unreleased]entries are tightened to match, the duplicate### Fixedheading left by #59 and #60 landing separately is consolidated, and the revoke JSONoutcomefield is moved toAddedwhere it belongs. The exit-code behaviour change stays explicit so nobody skimming before an upgrade misses it.2.
make buildversion trap —Makefile:2setsVERSION ?= devand injects it via-X ...cmd.version=$(VERSION)(Makefile:5-8), whilerunUpdaterefuses""/"dev"(cmd/update.go:38-39). So a plainmake buildproduces a binary on whichgrant updatecan never work. Documented in CLAUDE.md's Build section and one line in the README development block, including the workaround:make build VERSION=0.7.0— a version older than the latest release, so an update is actually found.3. Stale version and count claims — a sweep of CLAUDE.md and README.md for numbers written before the recent churn. Three had drifted:
110 -> 95go list -m allreports 109go-isattyv0.0.20disable-allThe other two dependency figures (33 build-graph modules, 39
go.modrequires) were accurate but brittle, so they went with the rest — consistent with the convention commit 1 establishes. Everything else checked out and was left alone: the SDK is correctly cited as v0.8.1 throughout,minio/selfupdatev0.6.0 matches go.mod,rhysd/go-github-selfupdateappears only in its correct historical context as the dependency that was removed, and thegrant revokeexit-code and keyring sections in both files are already post-#59/#60.No CHANGELOG entry: docs-only.
Verification:
make lintandmake buildclean. No code change;cmd/update_test.goalready covers the dev-build guard for both""and"dev"("dev build returns error" and "explicit dev version returns error"), so no test was added.