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

[Alejandro Colomar <alx@kernel.org>]

[-- 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 --]