Codifying/Documenting Guix commit message conventions?

[Richard Sent]

Hi Guix,

I noticed that there seems to be discrepencies between the GNU Changelog
format and Guix's commit message convention. For example, see these
lines from [1].

>    Our convention for indicating conditional changes is to use _square
> brackets around the name of the condition_.
> 
>    Conditional changes can happen in numerous scenarios and with many
> variations, so here are some examples to help clarify. This first
> example describes changes in C, Perl, and Python files which are
> conditional but do not have an associated function or entity name:
> 
>      * xterm.c [SOLARIS2]: Include <string.h>.

Meanwhile in Guix commit messages, [foo] seems to be used to refer to a
subset of a larger part [2]:

> * doc/guix.texi (Base Services)[extra-special-file]: Add warning regarding
> files in /etc.

>From what I'm seeing, the GNU Changelog convention is to indicate
subsets using <> [3].

> * progmodes/sh-script.el (sh-while-getopts) <sh>: Handle case that
> user-specified option string is empty.

Guix states that commit messages should follow the ChangeLog format
and—as far as I can tell—leaves it at that with no mention of
discrepencies or quirks [4].

>    Please write commit logs in the ChangeLog format (*note
> (standards)Change Logs::); you can check the commit history for
> examples.

My questions to the group are thus:

1. Is this in fact a discrepency between the GNU ChangeLog format and
Guix convention or am I missing something?

2. Are there other discrepencies out there that people know of?

3. How should we go about documenting Guix-specific conventions?

I suspect another discrepency not mentioned is Guix's tendency to prefix
header lines with e.g. "doc:" or "gnu:". I haven't found a better way to
identify what to put for those besides viewing commits touching X file.
And if a commit evenly spans multiple categories it can sometimes be
blurry determining what fits best.

Another one seems to be the [security fixes], [fixes CVE-...], and
[fixes TROVE-...] blocks added to certain header lines. What other tags
exist? There seems to be inconsistency here when referring to multiple
CVEs. For example, when a fixes tag references multiple CVEs you can
find.

[fixes CVE-2020-10700, CVE-2020-10704]  [5]
[fixes CVE-2020-3898 & CVE-2019-8842]   [6]
[fixes CVE-2023-{28755, 28756}]         [7]

I'm happy to write up documentation on best practices, but I figure a
general post on guix-devel is a good idea to make sure nothing's missed.
I'm not advocating for a new French revolution to overthrow the
ChangeLog aristocracy.

[8] seems like a very interesting commit to analyze in terms of Guix
conventions since it deals with a dense, nontrivial package change and
refers to "sub-sub elements", which don't seem to be a thing in GNU
ChangeLog land.

[1]: (standards) Conditional Changes
[2]: Guix commit 398393187cc48f449215b14cf18b13fefb228558
[3]: (standards) Indicating the Part Changed
[4]: (guix) Submitting Patches
[5]: 62881ad61c
[6]: a9ca7998f7
[7]: cd0a8950e4
[8]: 77d949c812

-- 
Take it easy,
Richard Sent
Making my computer weirder one commit at a time.