iD keeps release notes in a changelog that’s so accessibly written and formatted that we feel comfortable linking to it from the 🎁 button in iD’s status bar. Perhaps we could prepare these release notes ahead of a release in a running changelog.
Rationale
I imagine it’s inconvenient to compose the release notes at release time. The person doing the release has to trawl the commit history and read up on changes that sometimes took place with little context in the commit messages themselves. There’s also little opportunity to spot and fix omissions before release. For example, #8276 was omitted from the v2.20.0 release notes. It probably got overlooked because it wasn’t linked to an issue beforehand.
A running changelog would also benefit mappers who are curious about upcoming changes, translators who need more context about new strings that showed up in Transifex, and developers who regularly use the preview of develop on Netlify. Not every mapper or translator is sufficiently familiar with JavaScript to make sense of the commit history.
Proposal
Add a section to the top of CHANGELOG.md called “develop” or “Unreleased” that maintainers can edit after merging PRs. PR authors could add to this changelog if they want, but that would risk annoying merge conflicts. Better to keep it simple for now.
Keep a Changelog does a great job of extolling the benefits of a running changelog, though in my opinion it’s too prescriptive about the format. I think iD’s headings broken down by topic are more user-friendly for a user-facing application than a rigid Added/Changed/Removed structure. The emoji are fun too. 🙂
iD keeps release notes in a changelog that’s so accessibly written and formatted that we feel comfortable linking to it from the 🎁 button in iD’s status bar. Perhaps we could prepare these release notes ahead of a release in a running changelog.
Rationale
I imagine it’s inconvenient to compose the release notes at release time. The person doing the release has to trawl the commit history and read up on changes that sometimes took place with little context in the commit messages themselves. There’s also little opportunity to spot and fix omissions before release. For example, #8276 was omitted from the v2.20.0 release notes. It probably got overlooked because it wasn’t linked to an issue beforehand.
A running changelog would also benefit mappers who are curious about upcoming changes, translators who need more context about new strings that showed up in Transifex, and developers who regularly use the preview of develop on Netlify. Not every mapper or translator is sufficiently familiar with JavaScript to make sense of the commit history.
Proposal
Add a section to the top of CHANGELOG.md called “develop” or “Unreleased” that maintainers can edit after merging PRs. PR authors could add to this changelog if they want, but that would risk annoying merge conflicts. Better to keep it simple for now.
Keep a Changelog does a great job of extolling the benefits of a running changelog, though in my opinion it’s too prescriptive about the format. I think iD’s headings broken down by topic are more user-friendly for a user-facing application than a rigid Added/Changed/Removed structure. The emoji are fun too. 🙂