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

[Jani Nikula <jani.nikula@linux.intel.com>]

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.

The above would also match current usage in e.g. the drm subsystem.

> +
>  .. _the_canonical_patch_format:
>  
> -14) The canonical patch format
> +15) The canonical patch format

Would it be about time we dropped the numbers?


BR,
Jani.

>  ------------------------------
>  
>  This section describes how the patch itself should be formatted.  Note
> @@ -768,7 +781,7 @@ references.
>  
>  .. _explicit_in_reply_to:
>  
> -15) Explicit In-Reply-To headers
> +16) Explicit In-Reply-To headers
>  --------------------------------
>  
>  It can be helpful to manually add In-Reply-To: headers to a patch
> @@ -782,7 +795,7 @@ helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
>  the cover email text) to link to an earlier version of the patch series.
>  
>  
> -16) Providing base tree information
> +17) Providing base tree information
>  -----------------------------------
>  
>  When other developers receive your patches and start the review process,
> @@ -833,7 +846,7 @@ either below the ``---`` line or at the very bottom of all other
>  content, right before your email signature.
>  
>  
> -17) Sending ``git pull`` requests
> +18) Sending ``git pull`` requests
>  ---------------------------------
>  
>  If you have a series of patches, it may be most convenient to have the

-- 
Jani Nikula, Intel Open Source Graphics Center