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

[Blake Graham-Henderson]

Galen,

I think it's a fine idea. At the very least, it couldn't hurt. I'll 
start putting that line in my commit messages where appropriate.

I appreciate the time and consideration on the issue.

-Blake-
Conducting Magic
Will consume any data format
MOBIUS

On 1/3/2024 10:27 AM, 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
> 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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.evergreen-ils.org/pipermail/evergreen-dev/attachments/20240103/38fd57f3/attachment.htm>