docs: record 0.1.0 in the changelog on main - #27
Merged
Conversation
main has carried the released notes under [Unreleased] since the release: 0.1.0 was stabilized on its own branch and the commit that renamed the heading lives only there, so nothing carried it home. The heading is not all that was wrong. The section had `### Changed` with a **Migration** note and `### Fixed` with two entries — on a *first* release. Changed relative to what? There was no prior published version. The migration note tells an operator to migrate from nothing, and "the SDK no longer silently reconciles them" describes behaviour that, publicly, never existed. Those entries were deltas against internal pre-release states, which is history a reader of this repository cannot see. python-sdk, ts-sdk and go-sdk all get this right: their 0.1.0 section is a heading, a blank line, and `- Initial release.` — no subsections at all. This now matches, byte for byte in shape. Nothing of value is lost. A changelog records deltas, and a first release has none; what the SDK *does* belongs in the README and the user guides, which carry it. The entries removed here described the behaviour 0.1.0 shipped with, not a change to it. ## Deliberately not byte-exact with the tag The convention is that main's `## [X.Y.Z]` section is a byte-exact copy of the tagged one, so published notes are never quietly rewritten. This departs from it, knowingly: - the tag keeps pointing at a77db11, the commit the published jar was built from, and its CHANGELOG is left alone as the record of what was cut; - the published artifact does not carry the changelog at all — checked the jar on Central, it contains no `.md` — so nothing immutable disagrees with this; - the GitHub Release body is corrected the same way, which is where the convention already sends corrections. So the two surfaces a reader actually looks at agree with each other and with the rest of the family, and the tag remains the historical record. Re-establishing byte-exactness would mean moving the tag off the commit the artifact was built from, which is a worse trade. The finalize step that renames `[Unreleased]` is what let this through: it renames a heading and asks nothing about whether the subsections mean anything for a first release. cs-sdk shipped its whole Keep-a-Changelog skeleton the same way. Worth a check in that step.
RobertoIskandarani
force-pushed
the
docs/record-0.1.0-on-main
branch
from
September 8, 2026 18:02
505a29f to
f4bfe7b
Compare
muralx
approved these changes
Sep 8, 2026
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
2 participants
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.
mainhas carried the released notes under[Unreleased]since the release, so the changelog on the default branch does not describe the version that shipped today.Why it happened
0.1.0 was stabilized on its own branch, and the commit that renamed
[Unreleased]to## [0.1.0] - 2026-09-07lives only there.release.ymldeletes the release branch after tagging, so nothing carries the rename home. The bodies stayed identical, which is what makes the omission invisible — the notes look right until you go looking for the version heading.This is structural, not a slip:
cut-releaseopens a back-port PR to the default branch that bumps POM versions only, andrelease.ymlreads the section on the release branch and never writes to the default branch. It will recur on every release until that is fixed.What changes
Two added lines: the
## [0.1.0] - 2026-09-07heading, and the now-empty[Unreleased]left above it. No note is edited, moved or reworded.Verified rather than assumed: both sections were extracted and diffed, and the resulting
## [0.1.0]body is byte-identical to the one at thev0.1.0tag (34 lines).Keeping main's section an exact copy of the tagged one is what makes a correction to published notes go in the GitHub Release body instead of being silently rewritten here.
Verification
mvn verifygreen across all four modules against the pinned conformance catalog.