Re: [PATCH] docs: Document the Link: tag formally

[Russell King - ARM Linux admin <linux@armlinux.org.uk>]

On Mon, Dec 16, 2019 at 03:14:56PM +0200, Jani Nikula wrote:
> On Mon, 16 Dec 2019, Linus Walleij <linus.walleij@linaro.org> wrote:
> > We have a lot of Link: tags in commits these days and they are
> > not formally defined in the kernel documentation. Let's put
> > a separate paragraph about it in submitting-patches.rst where
> > most other tags are defined.
> >
> > Cc: Jonathan Corbet <corbet@lwn.net>
> > Cc: Russell King <linux@armlinux.org.uk>
> > Reported-by: Russell King <linux@armlinux.org.uk>
> > Signed-off-by: Linus Walleij <linus.walleij@linaro.org>
> > ---
> >  Documentation/process/submitting-patches.rst | 21 ++++++++++++++++----
> >  1 file changed, 17 insertions(+), 4 deletions(-)
> >
> > diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> > index ba5e944c7a63..20ef984aa743 100644
> > --- a/Documentation/process/submitting-patches.rst
> > +++ b/Documentation/process/submitting-patches.rst
> > @@ -643,9 +643,22 @@ which stable kernel versions should receive your fix. This is the preferred
> >  method for indicating a bug fixed by the patch. See :ref:`describe_changes`
> >  for more details.
> >  
> > +14) Link: tags
> > +--------------
> > +
> > +A Link: attribute can be used to provide a link back to a protocol of a
> > +discussion pertaining to the patch. A typical link looks like this:
> > +
> > +    Link: https://lore.kernel.org/r/<message-id>
> > +
> > +Any HTTP[S] links can be referenced. It is customary for maintainers to add
> > +Link: tags to reference discussions on mailing lists, and this can be done
> > +automatically with the git tool when applying patches in mailbox format, see
> > +:ref:`Documentation/maintainer/configure-git.rst <configure git>`.
> 
> I'd like to emphasize even more strongly that it is applied by the
> maintainer or committer, and should reference the patch that got
> applied. And that the patch submitters shouldn't try to add it
> themselves. (Which makes you wonder about the placement in
> submitting-patches.rst.) IMO other references should use References:
> that is already widely used.

I'm the maintainer of phylink.  During discussions, I may propose a
patch for someone to try.  When successful, I'll send a new email
submitting the patch officially to davem as the networking maintainer
as an entirely separate thread.

Using Link: to the patch that was submitted officially is obviously
impossible, but you would want to link to the discussion that resulted
in the patch, rather than the official submission - which would
generally be the submission plus an "applied" reply.

Looking at the history between v5.4 and current, it seems that it's
only DRM that uses References, and there's variations in its
formatting.  Some references to commits contain the word "commit"
and others do not.  Some references, from what I can tell, are
useless - for example "HSDES#1405586840" which I guess is some kind
of internal system somewhere.

There are some broken Link:s:

https://patchwork.freedesktop.org/patch/msgid/
<CACAvsv56Am90okV334eXgxDuK228sb9UJxMiOYjNAMShvvv4cg@mail.gmail.com

That has a space in there with a "<" - which suggests a broken script
is in use that mis-parses the email.

The References: thing is also completely undocumented...

-- 
RMK's Patch system: https://www.armlinux.org.uk/developer/patches/
FTTC broadband for 0.8mile line in suburbia: sync at 12.1Mbps down 622kbps up
According to speedtest.net: 11.9Mbps down 500kbps up