[Evergreen-dev] Proposal: add release note one-liners to commit messages

[Jason Stephenson]

Can't we just put them in docs/RELEASE_NOTES_NEXT/miscellaneous.adoc? 
That's what I've been doing.

Yes, it leads to conflicts when cherry-picking but they're very simple 
to resolve, just remove the conflict markers and include all of the lines.

On 1/3/24 11:27, Galen Charlton via Evergreen-dev wrote:
> Hi,
> 
> Inspired by recent discussion about improving the ease of writing 
> release notes - as well as some friction I'm already running into 
> dealing with merge conflicts on miscellaneous.adoc when doing patch 
> review - I'd like to propose a convention for adding brief release notes 
> entry to the commit messages.
> 
> Specifically, I propose adding a new "Release-note:" tag to the commit 
> message that might look something like this:
> 
> -- BEGIN COMMIT MESSAGE --
> LP#12356873: Quux the frobinator in the most techie fashion possible
> 
> Commit message and test plan
> 
> Release-note: Fix patrons occasionally getting overcharged by a penny 
> when paying fines online
> 
> Signed-off-by: ...
> -- END COMMIT MESSAGE --
> 
> The idea is that when rolling a release, one stage of preparing the 
> release notes would be running a script that looks at the commit 
> messages on the release branch since the previous release in that 
> series, grabs the bug number and the commit message, then generates a 
> list in AsciiDoc format suitable for plopping into the Miscellaneous 
> section of a set of release notes.
> 
> Such a script should probably be forgiving about how it parses the tag, 
> including accepting the likes of "Release-noTeS:". When there's no tag 
> in the commit message, falling back to the first line of the commit 
> message after the bug number might be a not-too-terrible fallback.
> 
> Some reasons to consider doing it this way:
> 
> - It avoids merge conflicts on miscellaenous.adoc during patch review 
> and committing
> - Patch authors would not have to fiddle with formatting the LP bug URL 
> for misceallaneous.adoc
> - It avoids some problems that might arise by an alternative convention 
> to include the release note entry somewhere in LP, including LP's poor 
> API and the fact that bug reports tend to be, well, statements of 
> problems, whereas release notes usually should be statements of fixes or 
> changes.
> - When a committer (or actually, anybody in the review chain for a given 
> patch) needs to supply a release note that wasn't supplied by the patch 
> author, a "git commit --amend" is quicker than fiddling with 
> miceallaneous.adoc.
> - The existence of such a tag can help clarify the purpose of the patch 
> for anybody reading the commit, as my example above implies
> 
> When to use this convention:
> 
> - For bug fixes and very minor enhancements that can be adequately 
> described in a single line
> 
> When not to use to this convention:
> 
> - For anything that cannot be described in a single line due to scope, 
> complexity, or because the patch or series adds new permissions or 
> library settings. In such cases, the existing RELEASE_NOTES_NEXT 
> convention should be followed.
> 
> Thoughts? If there is general agreement that this is worth trying, I 
> will put an example script together.
> 
> Regards,
> 
> Galen
> -- 
> Galen Charlton
> Implementation and IT Manager
> Equinox Open Library Initiative
> gmc at equinoxOLI.org <mailto:gmc at equinoxOLI.org>
> https://www.equinoxOLI.org <https://www.equinoxOLI.org>
> phone: 877-OPEN-ILS (673-6457)
> direct: 770-709-5581
> 
> _______________________________________________
> Evergreen-dev mailing list
> Evergreen-dev at list.evergreen-ils.org
> http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev