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

[Galen Charlton]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.evergreen-ils.org/pipermail/evergreen-dev/attachments/20240103/65306276/attachment.htm>