[PATCH] CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields

[PATCH] CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields

[Alejandro Colomar]

Signed-off-by: Alejandro Colomar <alx@kernel.org>
---

Hi!

I hadn't yet documented how to produce the Fixes: trailer fields in the
Linux man-pages project.  We require the commit-date to disambiguate
possible hash (and subject) collisions.  This documents how to produce
them easily.

I hope this will be useful to other projects.  I've been using this
format for some time, and it has some nice properties: it shows at first
glance the date of a commit (which itself gives an idea of how many
stable versions would need to be fixed).  It can also be parsed by a
machine, by having a consistent and simple (unambiguous) format.


Have a lovely night!
Alex

 CONTRIBUTING.d/git                 | 16 ++++++++++++++++
 CONTRIBUTING.d/patches/description | 11 +++++++++++
 2 files changed, 27 insertions(+)

diff --git a/CONTRIBUTING.d/git b/CONTRIBUTING.d/git
index 4b7a95472..3f944a23c 100644
--- a/CONTRIBUTING.d/git
+++ b/CONTRIBUTING.d/git
@@ -43,6 +43,22 @@ Description
 		$ git config --global \
 			sendemail.sendmailcmd 'mutt -H - && true';
 
+    Commit references
+	'Fixes:' trailer fields should have the following format.
+
+		Fixes: 12-char-hash ([author-date,] commit-date; "subject")
+
+	where the author date is optional, and only included if it's
+	somehow important.  The commit date is often more important, as
+	it's sorted, and thus can be used to find (with a binary search)
+	a commit whose hash and subject may have collisions.  To produce
+	such fields, the following git aliases are useful.
+
+		$ git config --global alias.ref \
+			"show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'"
+		$ git config --global alias.ref2 \
+			"show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%ad, %cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'"
+
 See also
 	git-config(1)
 	git-diff(1)
diff --git a/CONTRIBUTING.d/patches/description b/CONTRIBUTING.d/patches/description
index 73b603bf3..09ee35ec8 100644
--- a/CONTRIBUTING.d/patches/description
+++ b/CONTRIBUTING.d/patches/description
@@ -55,3 +55,14 @@ Description
 	"Co-developed-by:".  Example:
 
 		Signed-off-by: Alejandro Colomar <alx@kernel.org>
+
+	Add 'Fixes:' tags as necessary.  See <CONTRIBUTING.d/git> for
+	how to configure the alias.ref and alias.ref2 git aliases.  The
+	commit references can be produced with them.
+
+		$ git ref bb509e6fc
+		bb509e6fcbae (2020-10-16; "kernel_lockdown.7: New page documenting the Kernel Lockdown feature")
+
+	which then can be used as
+
+		Fixes: bb509e6fcbae (2020-10-16; "kernel_lockdown.7: New page documenting the Kernel Lockdown feature")

Range-diff:
-:  --------- > 1:  3a656e903 CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields

base-commit: be29e611a386b754fd5ce9f9d1ef421d15319ec1
-- 
2.51.0

Re: [PATCH] CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields

[Collin Funk]

Alejandro Colomar <alx@kernel.org> writes:

> Signed-off-by: Alejandro Colomar <alx@kernel.org>
> ---
>
> Hi!
>
> I hadn't yet documented how to produce the Fixes: trailer fields in the
> Linux man-pages project.  We require the commit-date to disambiguate
> possible hash (and subject) collisions.  This documents how to produce
> them easily.
>
> I hope this will be useful to other projects.  I've been using this
> format for some time, and it has some nice properties: it shows at first
> glance the date of a commit (which itself gives an idea of how many
> stable versions would need to be fixed).  It can also be parsed by a
> machine, by having a consistent and simple (unambiguous) format.
>
>
> Have a lovely night!
> Alex
>
>  CONTRIBUTING.d/git                 | 16 ++++++++++++++++
>  CONTRIBUTING.d/patches/description | 11 +++++++++++
>  2 files changed, 27 insertions(+)
>
> diff --git a/CONTRIBUTING.d/git b/CONTRIBUTING.d/git
> index 4b7a95472..3f944a23c 100644
> --- a/CONTRIBUTING.d/git
> +++ b/CONTRIBUTING.d/git
> @@ -43,6 +43,22 @@ Description
>  		$ git config --global \
>  			sendemail.sendmailcmd 'mutt -H - && true';
>  
> +    Commit references
> +	'Fixes:' trailer fields should have the following format.
> +
> +		Fixes: 12-char-hash ([author-date,] commit-date; "subject")
> +
> +	where the author date is optional, and only included if it's
> +	somehow important.  The commit date is often more important, as
> +	it's sorted, and thus can be used to find (with a binary search)
> +	a commit whose hash and subject may have collisions.  To produce
> +	such fields, the following git aliases are useful.
> +
> +		$ git config --global alias.ref \
> +			"show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'"
> +		$ git config --global alias.ref2 \
> +			"show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%ad, %cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'"
> +

I would recommend taking a look at the one mentioned in git's
SubmittingPatches. It looks fairly similar to yours:

    $ git ref HEAD
    d9fb823121b1 (2026-02-02; "maintainer-makefile: propagate MAKEINFO to gendocs")
    $ git show -s --pretty=reference HEAD
    d9fb82312 (maintainer-makefile: propagate MAKEINFO to gendocs, 2026-02-02)

Collin

Re: [PATCH] CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields

[Alejandro Colomar]

[-- Attachment #1: Type: text/plain, Size: 4212 bytes --]

[CC += git@]

Hi Collin,

On 2026-02-03T16:01:52-0800, Collin Funk wrote:
> Alejandro Colomar <alx@kernel.org> writes:
> 
> > Signed-off-by: Alejandro Colomar <alx@kernel.org>
> > ---
> >
> > Hi!
> >
> > I hadn't yet documented how to produce the Fixes: trailer fields in the
> > Linux man-pages project.  We require the commit-date to disambiguate
> > possible hash (and subject) collisions.  This documents how to produce
> > them easily.
> >
> > I hope this will be useful to other projects.  I've been using this
> > format for some time, and it has some nice properties: it shows at first
> > glance the date of a commit (which itself gives an idea of how many
> > stable versions would need to be fixed).  It can also be parsed by a
> > machine, by having a consistent and simple (unambiguous) format.
> >
> >
> > Have a lovely night!
> > Alex
> >
> >  CONTRIBUTING.d/git                 | 16 ++++++++++++++++
> >  CONTRIBUTING.d/patches/description | 11 +++++++++++
> >  2 files changed, 27 insertions(+)
> >
> > diff --git a/CONTRIBUTING.d/git b/CONTRIBUTING.d/git
> > index 4b7a95472..3f944a23c 100644
> > --- a/CONTRIBUTING.d/git
> > +++ b/CONTRIBUTING.d/git
> > @@ -43,6 +43,22 @@ Description
> >  		$ git config --global \
> >  			sendemail.sendmailcmd 'mutt -H - && true';
> >  
> > +    Commit references
> > +	'Fixes:' trailer fields should have the following format.
> > +
> > +		Fixes: 12-char-hash ([author-date,] commit-date; "subject")
> > +
> > +	where the author date is optional, and only included if it's
> > +	somehow important.  The commit date is often more important, as
> > +	it's sorted, and thus can be used to find (with a binary search)
> > +	a commit whose hash and subject may have collisions.  To produce
> > +	such fields, the following git aliases are useful.
> > +
> > +		$ git config --global alias.ref \
> > +			"show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'"
> > +		$ git config --global alias.ref2 \
> > +			"show --no-patch --abbrev=12 --date=short --format=tformat:'%C(auto)%h%C(reset) %C(dim white)(%ad, %cd%x3B \"%C(reset)%C(auto)%s%C(reset)%C(dim white)\")%C(reset)'"
> > +
> 
> I would recommend taking a look at the one mentioned in git's
> SubmittingPatches. It looks fairly similar to yours:
> 
>     $ git ref HEAD
>     d9fb823121b1 (2026-02-02; "maintainer-makefile: propagate MAKEINFO to gendocs")
>     $ git show -s --pretty=reference HEAD
>     d9fb82312 (maintainer-makefile: propagate MAKEINFO to gendocs, 2026-02-02)

I've seen that format before (while investigating all the --pretty=
options).  I didn't know that was used in git(1)'s SubmittingPatches,
though.

I considered it, and concluded that it was suboptimal for several
reasons:

-  It is unclear whether ', 2026-02-02' is part of the commit message.
   Since it's common practice to quote the subject in other projects
   --such as the kernel--, a format that quotes the subject is
   preferrable.

-  The date is a short and fixed-width field.  Readability is better if
   such fields go early, as they would be aligned.  Compare:

	8df2abb81a90 (man/man3/stpncpy.3: wfix, 2026-01-06)
	a17ed1cefd7f (man/man3type/intN_t.3type: STANDARDS: These conform to C23, 2026-01-06)

	8df2abb81a90 (2026-01-06; "man/man3/stpncpy.3: wfix")
	a17ed1cefd7f (2026-01-06; "man/man3type/intN_t.3type: STANDARDS: These conform to C23")

-  I use a semicolon, which is a stronger separator than a comma, as
   that allows me to use a comma for adding another sub-field to the
   date field.  In some cases, the author date is useful:

	$ git ref2 8df2abb81a90
	8df2abb81a90 (2026-01-06, 2026-01-06; "man/man3/stpncpy.3: wfix")

   This also allows further future extension, for example for including
   the author and/or committer names, as other fields.

I wondered a few months ago whether I should let git know about this
to improve --pretty=reference.  I guess this is the time.  I've thus
added them to CC.


Have a lovely day!
Alex

> Collin

-- 
<https://www.alejandro-colomar.es>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]