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

[Terran McCanna]

+1!

Terran McCanna, PINES Program Manager
------------------------------

Georgia Public Library Service | University System of Georgia

2872 Woodcock Blvd, Suite 250 l Atlanta, GA 30341

(404) 235-7138 | tmccanna at georgialibraries.org

http://help.georgialibraries.org | help at georgialibraries.org

<https://www.facebook.com/georgialibraries>
<https://www.twitter.com/georgialibs>
<https://www.instagram.com/georgialibraries/>
<https://www.twitter.com/georgialibs>

Join our email list <http://georgialibraries.org> for stories of Georgia
libraries making an impact in our communities.



On Wed, Jan 3, 2024 at 12:05 PM 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/20240103/8475ac57/attachment-0001.htm>