{"thread":{"id":"64915","subject":"Re: [PATCH] CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields","startedAt":"2026-02-04T13:34:01Z","lastAt":"2026-02-04T13:34:01Z","messageCount":1,"participants":["Alejandro Colomar"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"535148","messageId":"aYNITpLKCEYFOOsw@devuan","threadId":"64915","inReplyTo":"87zf5p8jgv.fsf@gmail.com","subject":"Re: [PATCH] CONTRIBUTING.d/: Document format of 'Fixes:' trailer fields","fromName":"Alejandro Colomar","fromEmail":"alx@kernel.org","sentAt":"2026-02-04T13:33:57Z","receivedAt":"2026-02-04T13:34:01Z","isPatch":true,"sender":{"key":"alx@kernel.org","avatar":null},"body":"[CC += git@]\n\nHi Collin,\n\nOn 2026-02-03T16:01:52-0800, Collin Funk wrote:\n> Alejandro Colomar <alx@kernel.org> writes:\n> \n> > Signed-off-by: Alejandro Colomar <alx@kernel.org>\n> > ---\n> >\n> > Hi!\n> >\n> > I hadn't yet documented how to produce the Fixes: trailer fields in the\n> > Linux man-pages project.  We require the commit-date to disambiguate\n> > possible hash (and subject) collisions.  This documents how to produce\n> > them easily.\n> >\n> > I hope this will be useful to other projects.  I've been using this\n> > format for some time, and it has some nice properties: it shows at first\n> > glance the date of a commit (which itself gives an idea of how many\n> > stable versions would need to be fixed).  It can also be parsed by a\n> > machine, by having a consistent and simple (unambiguous) format.\n> >\n> >\n> > Have a lovely night!\n> > Alex\n> >\n> >  CONTRIBUTING.d/git                 | 16 ++++++++++++++++\n> >  CONTRIBUTING.d/patches/description | 11 +++++++++++\n> >  2 files changed, 27 insertions(+)\n> >\n> > diff --git a/CONTRIBUTING.d/git b/CONTRIBUTING.d/git\n> > index 4b7a95472..3f944a23c 100644\n> > --- a/CONTRIBUTING.d/git\n> > +++ b/CONTRIBUTING.d/git\n> > @@ -43,6 +43,22 @@ Description\n> >  \t\t$ git config --global \\\n> >  \t\t\tsendemail.sendmailcmd 'mutt -H - && true';\n> >  \n> > +    Commit references\n> > +\t'Fixes:' trailer fields should have the following format.\n> > +\n> > +\t\tFixes: 12-char-hash ([author-date,] commit-date; \"subject\")\n> > +\n> > +\twhere the author date is optional, and only included if it's\n> > +\tsomehow important.  The commit date is often more important, as\n> > +\tit's sorted, and thus can be used to find (with a binary search)\n> > +\ta commit whose hash and subject may have collisions.  To produce\n> > +\tsuch fields, the following git aliases are useful.\n> > +\n> > +\t\t$ git config --global alias.ref \\\n> > +\t\t\t\"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)'\"\n> > +\t\t$ git config --global alias.ref2 \\\n> > +\t\t\t\"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)'\"\n> > +\n> \n> I would recommend taking a look at the one mentioned in git's\n> SubmittingPatches. It looks fairly similar to yours:\n> \n>     $ git ref HEAD\n>     d9fb823121b1 (2026-02-02; \"maintainer-makefile: propagate MAKEINFO to gendocs\")\n>     $ git show -s --pretty=reference HEAD\n>     d9fb82312 (maintainer-makefile: propagate MAKEINFO to gendocs, 2026-02-02)\n\nI've seen that format before (while investigating all the --pretty=\noptions).  I didn't know that was used in git(1)'s SubmittingPatches,\nthough.\n\nI considered it, and concluded that it was suboptimal for several\nreasons:\n\n-  It is unclear whether ', 2026-02-02' is part of the commit message.\n   Since it's common practice to quote the subject in other projects\n   --such as the kernel--, a format that quotes the subject is\n   preferrable.\n\n-  The date is a short and fixed-width field.  Readability is better if\n   such fields go early, as they would be aligned.  Compare:\n\n\t8df2abb81a90 (man/man3/stpncpy.3: wfix, 2026-01-06)\n\ta17ed1cefd7f (man/man3type/intN_t.3type: STANDARDS: These conform to C23, 2026-01-06)\n\n\t8df2abb81a90 (2026-01-06; \"man/man3/stpncpy.3: wfix\")\n\ta17ed1cefd7f (2026-01-06; \"man/man3type/intN_t.3type: STANDARDS: These conform to C23\")\n\n-  I use a semicolon, which is a stronger separator than a comma, as\n   that allows me to use a comma for adding another sub-field to the\n   date field.  In some cases, the author date is useful:\n\n\t$ git ref2 8df2abb81a90\n\t8df2abb81a90 (2026-01-06, 2026-01-06; \"man/man3/stpncpy.3: wfix\")\n\n   This also allows further future extension, for example for including\n   the author and/or committer names, as other fields.\n\nI wondered a few months ago whether I should let git know about this\nto improve --pretty=reference.  I guess this is the time.  I've thus\nadded them to CC.\n\n\nHave a lovely day!\nAlex\n\n> Collin\n\n-- \n<https://www.alejandro-colomar.es>\n"}]}