docs: changelog entries told the whole story where one sentence would do - #152
Merged
Conversation
RELEASE.md asked for "a one-line body" and nothing enforced it, so entries grew into paragraphs: root cause, mechanism, evidence and rejected alternatives, all of which the linked issue already holds. The v1.1.0 notes ran 38 entries over 19KB, and a reader deciding whether the release affects them had to read a design document to find out. The fragment section now states the rule outright — one sentence, two only for a caveat a reader must not miss, never a third — with a too-long and a right-length body shown side by side, and the pre-flight checklist gained a line for it. Every entry in v1.1.0, v1.0.0 and the unreleased #151 fragment is rewritten to that limit; v0.2.0 and v0.1.0 already met it. CHANGELOG.md is regenerated with `changie merge`. The v1.1.0 and v1.0.0 GitHub Release bodies were republished from their `changes/<tag>.md` files, so the published notes and the repo still agree.
github-actions
Bot
added
the
documentation
5 tasks
skyoo2003
added a commit
that referenced
this pull request
Sep 6, 2026
…153) #152 stated the rule in RELEASE.md and added a pre-flight checklist line, but the only enforcement was a manual checkbox read once per release — and the rule was invisible where a contributor actually lands: CONTRIBUTING.md and the PR checklist both linked RELEASE.md without saying what the rule is. `.changie.yaml` now sets `body.maxLength: 400`, which `changie new` refuses to exceed (401 characters rejected, 398 accepted). It is a ceiling for the two-sentence case rather than a target, and it does not see a hand-written fragment — both stated in RELEASE.md beside the rule. CONTRIBUTING.md and the PR checklist state the rule and link the section directly. The unreleased #151 fragment ran 482 characters, over the new cap; it is shortened to 397 with nothing dropped. The #152 fragment covers the cap and the two added surfaces.
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.
Summary
RELEASE.mdasked for "a one-line body" and nothing enforced it, so changelog entries grew into paragraphs carrying root cause, mechanism, evidence and rejected alternatives — all of which the linked issue already holds. This states the limit (one sentence, two at most), rewrites every existing entry to it, and republishes the affected GitHub Release bodies.Related Issue
Fixes #
Changes
Guidance
RELEASE.md: new### One sentence. Two at most.section under During development — one sentence for what changed and what it means, a second only for a caveat a reader must not miss, never a third (a third means two changes, or a story that belongs in the issue). Shows a too-long and a right-lengthbody:side by side, using the fix: S3 Control requests were served by S3, silently #142 S3 Control entry.RELEASE.md: pre-flight checklist gains Every fragment body is one sentence, two at most.Rewrite
changes/v1.1.0.md— all 38 entries condensed to 1–2 sentences.changes/v1.0.0.md— the 6 entries that ran to three sentences (fix: released binaries could not start — swap SQLite driver to pure Go #128, docs: publish the v1.0 compatibility policy, and lock the surfaces it promises #129 ×3, fix: released binaries registered no services #131, Documentation docs: publish the v1.0 compatibility policy, and lock the surfaces it promises #129).changes/unreleased/Documentation-20260906-234500.yaml— docs: the docs restated the same numbers in five different values #151 fragment, 6 sentences to 2.CHANGELOG.md— regenerated withchangie merge.v0.2.0andv0.1.0already met the limit and are untouched.Published notes
gh release edit v1.1.0 / v1.0.0 --notes-file changes/<tag>.md. This does not break the "no manual GitHub Release editing" rule inRELEASE.md— the bodies were republished verbatim from the fragment-owned files, not hand-typed. Prior bodies backed up locally before the edit.Files Changed
RELEASE.mdchanges/v1.1.0.mdchanges/v1.0.0.mdchanges/unreleased/Documentation-20260906-234500.yamlCHANGELOG.mdTest Plan
changes/v*.mdandchanges/unreleased/*.yaml: 0 entries over the limit.release.ymlnotes validation againstchanges/v1.1.0.mdlocally: exactly 1 version heading naming the tag, 0 lines that are notchangieoutput, all 38 entries ending in a valid issue link.changie mergerun clean;CHANGELOG.mddiff is confined to the rewritten entries.changes/<tag>.mdafter the edit — byte-identical apart from the trailing newline GitHub appends.No code changed, so the Go and boto3 suites are unaffected.
Checklist
golangci-lintN/A, no Go files touched)changes/unreleased/Documentation-20260906-185423.yaml, Issue 152)