Changelog style - #30
Merged
Merged
Conversation
heshaoqiong-tuya
marked this pull request as draft
August 27, 2026 07:19
heshaoqiong-tuya
marked this pull request as ready for review
August 27, 2026 09:32
The Unreleased section had drifted into commit bodies pasted under a heading: single entries running fifteen-plus lines through motivation, rejected alternatives and test counts. That is the right material, in the wrong file -- release notes are skimmed, and a reader who wants the reasoning goes to the commit. Convention 2 already said *when* an entry is needed; this says what it should look like. `## [0.3.0]` is named as the reference because it is the last section written that way: one line per change, sub-bullets only for specifics a reader acts on. Two things the section had also been losing: the PR number, which is the only link from a one-line summary back to the reasoning, and the Added / Changed / Fixed split, which release notes are generated from -- a fix landing under Added is published as a feature. No CHANGELOG entry for this commit, per convention 2: repo-internal, and this file is explicitly excluded. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
heshaoqiong-tuya
force-pushed
the
changelog_style
branch
from
August 27, 2026 09:39
5a426e3 to
49f336d
Compare
Applies convention 6 to the section that motivated it: 619 lines down to 139. The entries were commit bodies pasted under a heading — motivation, rejected alternatives, test counts and internal reasoning, several running past fifty lines for one change. All of that is still in the commits, which is where a reader who wants it looks. What is left here is what a reader acts on: the symbol, the behaviour change, the migration step. Most entries now carry a PR number. They could not be recovered from git history because these landed as squash or rebase merges, which leave no "Merge pull request #N" commit; the closed-PR list on GitHub has them, and each attribution was confirmed against that PR's own commit list rather than inferred from a branch name. Four entries carry none because they were pushed straight to master with no PR to cite. Two merged PRs turned out to have no entry at all, and are added: - #21, the APP-confirmed OTA (protocol 15) callback — a public callback on both config structs. - #23, the sizable ATOP response buffer — user-visible, since the sizes are set with -D. Three defects the rewrite surfaced, all from entries being appended rather than amended as the work continued: - Added and Fixed each appeared twice, and the second Fixed held Added-type material (the generic ATOP call). Merged into one of each, in the order Keep a Changelog defines, since release notes are generated from those headings. - The auto-connect default was documented both ways: Changed said it is now on by default, while the connect/disconnect entry still said "The default stays false". The later change never revisited the earlier entry. - The music-play demo was credited to #15, which is the region-wire-codes fix. It is #12. Two entries are dropped rather than shortened: the mqtt_abort_connect() extraction and a test-only over-read fix. Convention 2 scopes the CHANGELOG to what SDK users see, and neither is visible outside the repo. Rebased onto five commits that landed meanwhile, whose entries are folded in at the new length: the session-token-reason API (#29), the reset scope (#28), the POSIX binary renaming, and audio_chat_demo's header-shadowing and device-VAD fixes. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
heshaoqiong-tuya
force-pushed
the
changelog_style
branch
from
August 27, 2026 09:40
49f336d to
03dfad3
Compare
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.
The convention (AGENTS.md, rule 6)
- <module> — <what changed>(#<PR>)., with indented sub-bullets only forspecifics a reader acts on: a new symbol, a changed default, a migration step.
## [0.3.0]is named as the reference for length and shape — it is the lastsection written that way.
Added/Changed/Fixedheading, since releasenotes are generated from those.
body. The PR number is what links the one line back to all of it.
Unreleased: 619 lines → 139
The section had become commit bodies pasted under a heading — several single
entries ran past fifty lines through motivation, rejected alternatives and test
counts. That material is still in the commits; only what a reader acts on stays
here.
Defects this surfaced
All three come from entries being appended as work continued, rather than the
existing entry being amended:
AddedandFixedeach appeared twiceFixedheld Added-type material (the generic ATOP call). Merged into one of each.Changedsaid it is now on by default; the connect/disconnect entry still said "The default stays false".Two merged PRs had no entry at all
Not lost in the rewrite — they were never there:
both config structs.
set with
-D.PR numbers
Most entries now carry one. They are not recoverable from git history: these
landed as squash or rebase merges, which leave no
Merge pull request #Ncommit. The closed-PR list on GitHub has them, and each attribution was
confirmed against that PR's own commit list rather than inferred from a branch
name — which is how #26 was found to include the
link_deadfix, #20 to includethe TLS 1.3 ticket fix, and #19 the ATOP business-error change.
Four entries carry no number because they were pushed straight to master with no
PR to cite.
Dropped rather than shortened
The
mqtt_abort_connect()extraction and a test-only over-read fix. Convention 2scopes the CHANGELOG to what SDK users see; neither is visible outside the repo.
Note on the rebase
Five commits landed while this was open, and their entries are folded in at the
new length rather than left in the old one: the session-token-reason API (#29),
the reset scope (#28), the POSIX binary renaming, and
audio_chat_demo'sheader-shadowing and device-VAD fixes.
Only
## [Unreleased]is touched.## [0.3.0]and earlier are unchanged.