Re: [PATCH 2/2] Documentation: best practices for using Link trailers

[Thorsten Leemhuis <linux@leemhuis.info>]

On 18.06.24 18:42, Konstantin Ryabitsev wrote:
> Based on multiple conversations, most recently on the ksummit mailing
> list [1], add some best practices for using the Link trailer, such as:
> 
> - how to use markdown-like bracketed numbers in the commit message to
> indicate the corresponding link
> - when to use lore.kernel.org vs patch.msgid.link domains

[...]

> +   When using the ``Link:`` trailer to indicate the provenance of the
> +   patch, you should use the dedicated ``patch.msgid.link`` domain. This
> +   makes it possible for automated tooling to establish which link leads
> +   to the original patch submission. For example::
> +
> +     Link: https://patch.msgid.link/patch-source-msgid@here

I wonder how long it will take until someone starts using
patch.msgid.link/ for things that are not the submission of the change,
for example by misunderstanding what "provenance of the patch" is meant
to mean here.

How about something this:

"""
In case you want to record the public review submission of a patch while
committing it, use a ``Link:`` trailer with the dedicated
``patch.msgid.link`` domain::

   Link: https://patch.msgid.link/patch-source-msgid@here

This makes it possible to reliably look the submission up, hence don't
use that domain for any other patches you might want to link to.
"""

But I suspect some people will never see this and start assuming that
this domain should be meant for all patches -- and not all of these
cases will be found during review (or by checkpatch, in case we add a
check and people actually run it). Writing that made me think a
dedicated tag like "Lore-Submission" or "Public-Review-Link" could avoid
this while keeping some of the aspects that Linus likes about "Link" --
but I doubt that will convince him.

Ciao, Thorsten