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

[Josh Stompro]

Would this also be a good time to include an official git commit template
file to add inline documentation for evergreen commit messages?

Example:
https://gist.github.com/lisawolderiksen/a7b99d94c92c6671181611be1641c733

And include setting up the commit.template in the Evergreen Git wiki page
as part of the quick start.
https://wiki.evergreen-ils.org/doku.php?id=dev:git

This would help me follow standard formatting, and would help with things
like prompting for testing plans, having a standard way of referencing the
lp ticket, and a prompt for setting the release-note: entry.

Josh


On Wed, Jan 3, 2024 at 3:02 PM Josh Stompro <stomproj at gsuite.larl.org>
wrote:

> Sounds like a good idea to me also.  +1
>
> I like the time saving aspect of it both for the reviewer and the author.
>
> Would it be helpful to also include the bug category?  Or is that already
> there via some other method?
>
> Something optional like:
> release-note: (client) Logging out on a page with a pcrud call floods
> browser with errors.
>
>
> On Wed, Jan 3, 2024 at 11:05 AM Blake Graham-Henderson via Evergreen-dev <
> evergreen-dev at list.evergreen-ils.org> wrote:
>
>> 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
>> phone: 877-OPEN-ILS (673-6457)
>> direct: 770-709-5581
>>
>> _______________________________________________
>> Evergreen-dev mailing listEvergreen-dev at list.evergreen-ils.orghttp://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev
>>
>>
>> _______________________________________________
>> 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/20240104/3099e14b/attachment-0001.htm>