unofficial mirror of guix-devel@gnu.org 
 help / color / mirror / code / Atom feed
* Codifying/Documenting Guix commit message conventions?
@ 2024-06-27 23:04 Richard Sent
  2024-06-28  8:59 ` Andreas Enge
  2024-06-29  1:11 ` Maxim Cournoyer
  0 siblings, 2 replies; 10+ messages in thread
From: Richard Sent @ 2024-06-27 23:04 UTC (permalink / raw)
  To: guix-devel

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.


^ permalink raw reply	[flat|nested] 10+ messages in thread

end of thread, other threads:[~2024-07-02  2:21 UTC | newest]

Thread overview: 10+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2024-06-27 23:04 Codifying/Documenting Guix commit message conventions? Richard Sent
2024-06-28  8:59 ` Andreas Enge
2024-06-29  1:11 ` Maxim Cournoyer
2024-06-29  1:42   ` Richard Sent
2024-06-29  6:51   ` Liliana Marie Prikler
2024-06-30  1:11     ` Maxim Cournoyer
2024-06-30  6:25       ` Liliana Marie Prikler
2024-07-01 14:14         ` Maxim Cournoyer
2024-07-01 22:17           ` Richard Sent
2024-07-02  2:20             ` Maxim Cournoyer

Code repositories for project(s) associated with this public inbox

	https://git.savannah.gnu.org/cgit/guix.git

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).