release-and-changelog
Write release notes once, as data, and publish them everywhere (CHANGELOG.md, the project website's changelog page, GitHub releases) the way xPartition does. Use when cutting a version, adding a user-visible change, or setting up a changelog for a new project.
One file, release-notes.json, holds every release note. Everything else is generated from it:
CHANGELOG.mdviatools/changelog.cjs,- the website's changelog page, which reads the JSON at runtime,
- GitHub release text.
Pattern proven on xPartition (site/release-notes.json + site/releases.json + tools/sync-changelog.cjs).
Writing a note#
1{2 "version": "v0.3.0",3 "title": "Two to four words",4 "date": "2026-11-20",5 "summary": "One or two sentences a user cares about. What can they do now?",6 "groups": {7 "Added": ["Feature, in the user's words, with where to find it."],8 "Changed": ["What behaves differently now."],9 "Fixed": ["What was broken, from the user's point of view, and that it now works."],10 "Security":["Only real security-relevant changes."]11 },12 "technical": ["Implementation notes for developers: files, formats, trade-offs."]13}Rules:
- Newest first.
- Plain language in
summaryandgroups. Jargon goes intechnical. - Unreleased work gets an entry with no
date. The changelog shows "(unreleased)". - One version per shipped build. Use semantic versions:
v0.xwhile unstable, a minor bump for features, a patch bump for fixes only.
Releasing#
- Set the date on the version's note. If the project ships files, add them to
releases.jsonwithbytes,sha256andurl. This follows xPartition'sreleases.json; generate the hashes withsha256sum. node tools/changelog.cjs --name "<Project>" --site https://<project>.knotvector.com/changelog- Tag:
git tag v0.3.0 && git push origin v0.3.0 - GitHub release:
gh release create v0.3.0 <files> --title "v0.3.0 · <title>" --notes "<summary>" - Website: commit the JSON to the site and deploy it (see
project-site).
How you know it worked#
node tools/changelog.cjs --checkpasses.- The website changelog shows the new version at the top with its downloads.
- The tag exists on GitHub.
Gotchas#
releases.jsondates win over note dates, so keep them in sync or use only one.- Windows line endings make
--checkfail on files edited in some editors. The tool normalizes CRLF, but keep.gitattributeswith*.md text eol=lf.