The ## 3.0.0 (unreleased) section in cli/CHANGELOG.md is being written incrementally, one PR at a time, and it already reads badly: ~28 entries in merge order, several of them multi-hundred-word paragraphs, with related changes scattered (the lock model spans entries from two different PRs; three separate entries touch mops watch). Some entries also explain rationale at a depth that suited PR review but not a release note.
It needs an editing pass before v3 ships:
- Group by theme rather than merge order — lockfile model, dfx decoupling, defaults and UX, removals — so a reader can find what affects them.
- Lead each breaking entry with the migration, not the reasoning. Right now the "what do I type instead" sentence is often buried at the end of a long paragraph.
- Merge entries describing one user-visible change that arrived across multiple PRs.
- Cut the rationale to a sentence where the full explanation only mattered to reviewers; the PR link carries the detail.
- Consider a short "Migrating from 2.x" preamble listing only the things that require action, with the detailed entries below it.
Worth doing as one deliberate pass near the end rather than policing it per PR, since entries keep getting rewritten as later PRs supersede earlier ones (#681 already replaced #677's lock entry, for example).
The
## 3.0.0 (unreleased)section incli/CHANGELOG.mdis being written incrementally, one PR at a time, and it already reads badly: ~28 entries in merge order, several of them multi-hundred-word paragraphs, with related changes scattered (the lock model spans entries from two different PRs; three separate entries touchmops watch). Some entries also explain rationale at a depth that suited PR review but not a release note.It needs an editing pass before v3 ships:
Worth doing as one deliberate pass near the end rather than policing it per PR, since entries keep getting rewritten as later PRs supersede earlier ones (#681 already replaced #677's lock entry, for example).