Can't we just put them in docs/RELEASE_NOTES_NEXT/miscellaneous.adoc?
That's what I've been doing.
Yes, it leads to conflicts when cherry-picking but they're very simple
to resolve, just remove the conflict markers and include all of the lines.
On 1/3/24 11:27, 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
[email protected] <mailto:[email protected]>
https://www.equinoxOLI.org <https://www.equinoxOLI.org>
phone: 877-OPEN-ILS (673-6457)
direct: 770-709-5581
_______________________________________________
Evergreen-dev mailing list
[email protected]
http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev
_______________________________________________
Evergreen-dev mailing list
[email protected]
http://list.evergreen-ils.org/cgi-bin/mailman/listinfo/evergreen-dev
