Repository navigation
docs: make stamping the changelog a step, not a comment - #91
Merged
Merged
Conversation
The release instructions put "move [Unreleased] entries under a dated version heading" as a shell comment inside a bash block, with the tag commands runnable beneath it. Paste the block and the only thing that executes is the tag. That is not hypothetical: it happened today. v1.8.0 was tagged without a stamped changelog, and the new release workflow refused it -- which is the workflow working, but the instructions had set it up to fail. Stamping is now its own numbered step, described as a pull request, with an example of the heading it produces and a note on why it has to land before the tag: stamping afterwards leaves the tag pointing at a tree whose changelog is missing its own entry, and that is what `go get` serves. Also brings the section up to date with CI, which now checks the tag against the changelog and publishes the release from it, and keeps the proxy verification as the step CI genuinely cannot do -- the proxy is outside the repository, and a tag it refuses is a release that did not happen.
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.
What happened
v1.8.0was tagged today without a stamped changelog, and the new release workflow refused it. The workflow did its job. The instructions set it up to fail.CONTRIBUTING.mdhad this:The essential step is a comment inside a bash block — inert when pasted. The tag is the only thing that runs, and it's pre-filled with a version. Anyone copying that block does exactly one thing: tag without stamping.
I reproduced the same mistake in chat when I wrote out the release flow, which is how it surfaced.
The fix
Stamping is now its own numbered step, described as a pull request, with an example of the heading it produces — and a note on why it has to land before the tag: stamping afterwards leaves the tag pointing at a tree whose changelog is missing its own entry, and that's what
go getserves.Also brings the section up to date with CI: the tag is now checked against the changelog and the release is published from it. The proxy verification stays, framed as the step CI genuinely can't do — the proxy is outside the repository, and a tag it refuses is a release that didn't happen. Which is exactly how
v2.0.0went unnoticed for months.Not fixed, because it isn't broken
I claimed earlier the workflow printed a literal
$VERSIONin its error. It doesn't — that line was inside the##[group]Runblock, which is GitHub echoing the script source. The actual output resolved correctly to## [1.8.0]. I'd misread a command echo as output.