new script to extract information for release notes from commit messages

[Galen Charlton]

Following discussion from the January 2024 development meeting, I've created a script to help prepare release notes by grabbing information from Git commits

[Galen Charlton (gmc)]

A patch is available in the branch working/collab/gmcharlt/lp2051874_release_notes_helper / https://git.evergreen-ils.org/?p=working/Evergreen.git;a=shortlog;h=refs/heads/collab/gmcharlt/lp2051874_release_notes_helper

Given this tool's nature as an aid to part of the release process that will still require manual checking, I propose that this be merged quickly once its basic functionality has been verified, as it should be easy to iterate.

[Galen Charlton (gmc)]

Some ideas for enhancement:

- Maintain a file of aliases so that contributor names as extracted from the commits can have corrections of various sorts applied (e.g., name changes, typo corrections, etc.)
- Integrate it into what create_release_notes.sh does (or vice versa) to create a one-stop command for initializing the notes for a release
- If we want to consider crediting documentation contributors separately, do some parsing of which files are changed by each path
- Add an option to identify the starting point for the stream of commits to look at by commit date (so that `git log --since` can be used); that might be better for major releases that fiddling to find the right commit reference to give to --prev-release-branch.

[Josh Stompro (u-launchpad-stompro-org)]

Thanks Galen,

I've added some examples to the wiki git getting started page of using the release-note: tag.
https://wiki.evergreen-ils.org/doku.php?id=dev:git

I'll take a look at the other various wiki pages to see where it makes sense to add info.

https://wiki.evergreen-ils.org/doku.php?id=contributing:release_notes
https://wiki.evergreen-ils.org/doku.php?id=dev:release_notes_checklist
https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:release_notes_process
https://wiki.evergreen-ils.org/doku.php?id=dev:release_process:evergreen:how_to_build#prepare_release_notes_for_major_version_bumps_only
https://wiki.evergreen-ils.org/doku.php?id=evergreen-docs:release_notes_process

[Galen Charlton (gmc)]

Noting that "Co-authored-by" has been used in a few commit messages. If we add support for this, should note that there's at least one example that doesn't have an email address (Co-authored-by: New Developers Working Group).

[Terran McCanna (tmccanna)]

Re comment 4: For something like that, would it be appropriate to use the group's list address? (<email address hidden>)

[Galen Charlton (gmc)]

I don't think the email address is needed - for one thing, they'd never end up in the release notes. That comment was more a note to myself to ensure that the parsing will pick up contributors even if the email address is not found in the relevant tags.

[Terran McCanna (tmccanna)]

Questions - is case sensitivity an issue? (Release-note: vs Release-Note:)

Also, would it be useful to add the LP number in the release note line so that it appears in the final documents? I noticed Michele doing this so I've been doing that, for example:

Release-note: Fixed typo in blah (lp12345)

Or will the number be extracted automatically?

[Galen Charlton (gmc)]

It ignores case differences, and broadly speaking, the parsing can be made as forgiving as it needs to be without getting too many false hits into the output.

The script already grabs the bug number from the first line of the commit, so it's not necessary to include it in the Release-note entry.

[Andrea Neiman (aneiman)]

This is not really feedback on the branch itself, but a nitpicky question about note style.

"Removes" vs "Remove"?
"Fixes" vs "Fix"?
"Updates" vs "Update"?

and so forth.

We should probably pick one and stick with it, for consistency's sake.

[Jason Stephenson (jstephenson)]

I noticed something while looking at this branch. It seems a bit too greedy when looking for the release notes tag. The script generates the following from its own commit message:

* https://bugs.launchpad.net/evergreen/+bug/2051874[Bug 2051874]: .
* https://bugs.launchpad.net/evergreen/+bug/2051874[Bug 2051874]: New development tool to help prepare release notes using information from Git commits.

The first, empty entry is coming from this line at the end of a paragraph in the commit message: "release notes."

This could be avoided by making the regex a little tighter by requiring the '-' between "release" and "notes" rather allowing any character, or perhaps there could be a check for the length of the found text with some arbitrary minimum being required. (I'm not sure how short a useful release could be, but I imagine that anything less that 8-10 characters is too short to convey useful information.)

This looks good so far, and I wonder if it could be incorporated into the create_release_note.sh script to make things even easier/more automated.

Barring that, I think an example of using extract_release_notes_from_commits.pl to add to or to start a release notes file would be useful.

[Galen Charlton (gmc)]

I have pushed a patch to the collab branch with some improvements to the parsing of the commit messages, including taking up Jason's suggestion. Co-authored-by tags are now recognized.

I agree that integration with create_release_notes.sh (or perhaps, taking over its function) is in order. I'll work on that.

[Andrea Neiman (aneiman)]

Noting that in the 3/12/24 community dev meeting, we agreed on present tense for notes using this script.

"Fixes ..."
"Updates ..."
"Corrects ..."

etc.

[Andrea Neiman (aneiman)]

Does the thing! Thank you on behalf of she who writes many release notes :) :)

One suggested longer term followup - have authors/committers pick a 'category' for the release note (Circulation, Cataloging, etc.)

I have tested this code and consent to signing off on it with my name, Andrea Buntz Neiman, and my email address, <email address hidden>.

[Jane Sandberg (sandbergja)]

Thanks, Galen, Andrea, and Jason! Pushed to rel_3_11 and above.