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

[Josh Stompro]

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/20240103/56ff8698/attachment.htm>