I’ve set up a directory
Documentation/release/dev which is intended to contain snippets of release notes to add to topics for contribution. The goal of this is to help maintain release notes throughout the development cycle rather than doing it all with a mass email right before release. There’s a
0-sample-topic.md file in there with some instructions and a basic layout to use. Essentially, add a file named
Documentation/release/dev with a header and snippet about what is different. Images may be added and linked if they’re useful (but please keep them relevant and as small as possible).
This is the essentially the same process in use by ParaView, SMTK, CMB, and CMake (with slight differences between them, mostly the directory they’re expected to live in). Updating an existing release note (e.g., clarification, consolidation, or typo fixes) or removing one in case of backing out a change are also considered “updating the release notes” for the purposes of this process.
The robot will mention if the MR topic as a whole does not have a release note, but it will not block merging (because not every topic is actually worth one). Contributors, please consider adding release notes for things like new features, classes, critical bug fixes, and (especially) API changes. Things like typo fixes, doc updates, or other “chore”-like tasks don’t really need them mentioned. Reviewers, please ask for release note additions if they’re relevant.
We expect to prepare release notes at the release time based on these files and send out a draft of the release notes ahead of time instead of the mass email.