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

[Collin Funk]

Alejandro Colomar <alx@xxxxxxxxxx> writes:

> Signed-off-by: Alejandro Colomar <alx@xxxxxxxxxx>
> ---
>
> 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