Skip to content

docs: add CHANGELOG.md with breaking change tracking#423

Draft
jkmassel wants to merge 1 commit intotrunkfrom
jkmassel/add-changelog
Draft

docs: add CHANGELOG.md with breaking change tracking#423
jkmassel wants to merge 1 commit intotrunkfrom
jkmassel/add-changelog

Conversation

@jkmassel
Copy link
Copy Markdown
Contributor

@jkmassel jkmassel commented Apr 3, 2026

Summary

  • Add a CHANGELOG.md following the release-toolkit format with historical entries back to v0.3.0, categorized into Breaking Changes, New Features, Bug Fixes, and Internal Changes
  • Update bin/release.sh to automatically manage the Trunk section during releases (renames Trunk to the version number and creates a fresh empty Trunk section)
  • Update docs/releases.md and docs/code/developer-workflows.md to document the changelog workflow

The key motivation is surfacing breaking changes prominently so consumers of the library can plan upgrades. Retroactive breaking changes have been identified for v0.6.0, v0.8.0, v0.10.0, v0.12.0, and v0.15.0.

Test plan

  • Verify CHANGELOG.md renders correctly on GitHub
  • Verify the release script changelog update works: make release VERSION_TYPE=patch DRY_RUN=true (dry run skips the sed, but confirms the function is wired in)
  • Manually test the sed transformation: copy CHANGELOG.md, run the two sed commands from update_changelog, and confirm the Trunk section is correctly replaced and recreated

Add a CHANGELOG.md following the release-toolkit format with historical
entries back to v0.3.0. Each version is categorized into Breaking Changes,
New Features, Bug Fixes, and Internal Changes.

The release script now automatically manages the Trunk section during
releases, and the developer workflow docs mention updating the changelog
when merging user-facing changes.
@github-actions github-actions bot added the [Type] Developer Documentation Documentation for developers label Apr 3, 2026
@dcalhoun
Copy link
Copy Markdown
Member

dcalhoun commented Apr 6, 2026

With #392, I attempted to automate change groups and avoid the need to manually type change log entries, including breaking changes. If a PR is labeled appropriately, its title is included in the GitHub Release notes in the corresponding group. If a PR title follows Conventional Commits spec, a GitHub Action automatically labels the PR appropriately. I.e., the PR title becomes the release note.

Curious your thoughts: Is there value in a CHANGELOG.md over GitHub Releases? PR titles are required for the GitHub flow, is there value in also having separate release note entries? If both are worth keeping, we might consider ensuring manual notes are never forgotten via scripts like Jetpack's. Lasly, should we align the CHANGELOG.md organization with the existing GitHub Release organization or remove the latter?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

[Type] Developer Documentation Documentation for developers

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants