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.md via tools/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#

JSON
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 summary and groups. Jargon goes in technical.
  • Unreleased work gets an entry with no date. The changelog shows "(unreleased)".
  • One version per shipped build. Use semantic versions: v0.x while unstable, a minor bump for features, a patch bump for fixes only.

Releasing#

  1. Set the date on the version's note. If the project ships files, add them to releases.json with bytes, sha256 and url. This follows xPartition's releases.json; generate the hashes with sha256sum.
  2. node tools/changelog.cjs --name "<Project>" --site https://<project>.knotvector.com/changelog
  3. Tag: git tag v0.3.0 && git push origin v0.3.0
  4. GitHub release: gh release create v0.3.0 <files> --title "v0.3.0 · <title>" --notes "<summary>"
  5. Website: commit the JSON to the site and deploy it (see project-site).

How you know it worked#

  • node tools/changelog.cjs --check passes.
  • The website changelog shows the new version at the top with its downloads.
  • The tag exists on GitHub.

Gotchas#

  • releases.json dates win over note dates, so keep them in sync or use only one.
  • Windows line endings make --check fail on files edited in some editors. The tool normalizes CRLF, but keep .gitattributes with *.md text eol=lf.