docs: add a curated changelog and document the release process - #28
Open
refsz wants to merge 1 commit into
Open
Conversation
The changelog records what matters when upgrading - new capabilities, changed behaviour, fixes with user-visible effect - and points at the generated GitHub release notes for the complete pull-request list. Contributing gains the two rules that keep it honest: conventional PR titles (the squash commit on main) and a changelog entry in the same PR that changes behaviour.
refsz
force-pushed
the
docs/changelog-and-release-process
branch
from
August 19, 2026 16:01
5446929 to
e3173b2
Compare
refsz
changed the title
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.
Reworked after the discussion about automatic generation. The answer is a hybrid, and the split is now explicit:
The automatic layer already exists.
release.ymlrunsgenerate_release_notes: true, so every GitHub release carries the complete list of merged PRs — never stale, zero effort. Full automation beyond that (release-please, git-cliff) would need a commit convention onmain; with squash merges, that means conventional PR titles, which #29 establishes going forward — so the door stays open.The curated layer is only what automation cannot produce: what changes for a user who upgrades.
CHANGELOG.mdkeeps Added/Changed/Fixed with upgrade impact — the two constructor signature changes, theshell()semantics, the null-as-absent rule, the container-cache fix, and the--contextre-render fix that the first draft of this PR was missing (written before that bug was found; the staleness proved the point about hand-written logs). A header note points at the release notes for the complete PR list, and the former "Internal" section is gone — that is exactly what the generated notes cover.Drift prevention is a process rule, not a release-time recall exercise:
CONTRIBUTING.mdnow requires that a behaviour-changing PR updates theUnreleasedsection in the same PR, plus a conventional PR title since the squash title is the commit onmain. TheReleasingsection documents the tag flow, including that the version comes from the tag via Box and thatsputnik --versionmust never print@package_version@.No code changes.
🤖 Generated with Claude Code
https://claude.ai/code/session_018CTvnzcNYmFgm2HQcm821A