Skip to content

Add CHANGELOG and document the update process#2899

Closed
cconstable wants to merge 2 commits into
masterfrom
add-changelog
Closed

Add CHANGELOG and document the update process#2899
cconstable wants to merge 2 commits into
masterfrom
add-changelog

Conversation

@cconstable
Copy link
Copy Markdown

What

Adds a CHANGELOG.md and a lightweight process for keeping it current.

  • CHANGELOG.md at the repo root with an ## [Unreleased] section, loosely
    following the Keep a Changelog format.
    Entries are grouped under free-form headings (Added, Changed, Deprecated,
    Breaking Changes, Fixed, Security), created as needed.
  • .gitattributes marks CHANGELOG.md as merge=union so entries added by
    concurrent PRs append instead of conflicting.
  • CONTRIBUTING.md documents when to add an entry (any user-facing change)
    and how.

Why

Today release drivers reconstruct notes by hand at release time. Capturing
high-level notes incrementally in each PR makes releases faster and more
reliable: the GitHub release notes become the [Unreleased] section plus the
commit log.

Notes

  • Docs and config only; no code or behavior changes. The changelog starts fresh;
    historical release notes remain available through GitHub Releases.
  • We can backfill the changelog if necessary.

Add a CHANGELOG.md with an Unreleased section, set CHANGELOG.md to merge=union via .gitattributes, and document in CONTRIBUTING.md when and how to add entries.
@cconstable cconstable requested a review from a team as a code owner June 4, 2026 18:04
@cconstable
Copy link
Copy Markdown
Author

@maciejdudko What do we want to do with the previous releases? From our chat earlier, it sounded like having every repo move towards a consistent changelog was the plan. I could write a little script to backfill the changelog with the contents of the old release notes and then remove them so there isn't confusion about which to use. We could also "archive" them somehow so they are still visible in the repo. Or we could revisit this conversation for Java.

@maciejdudko
Copy link
Copy Markdown
Contributor

There are some special considerations for Java given our semi-automated release flow due to which Java changelog file should probably be handled differently from other SDKs. Let's flesh out the plan more and get back to it another time.

@maciejdudko maciejdudko closed this Jun 4, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants