Re: [PATCH] docs: update the guidance for Link: tags

[Randy Dunlap <rdunlap@infradead.org>]

On 9/8/25 12:32 PM, Jonathan Corbet wrote:
> As stated definitively by Linus, the use of Link: tags should be limited to
> situations where there is additional useful information to be found at the
> far end of the link.  Update our documentation to reflect that policy, and
> to remove the suggestion for a Git hook to add those tags automatically.
> 
> Link: https://lore.kernel.org/all/CAHk-=wh5AyuvEhNY9a57v-vwyr7EkPVRUKMPwj92yF_K0dJHVg@mail.gmail.com/
> Cc: Linus Walleij <linus.walleij@linaro.org>
> Signed-off-by: Jonathan Corbet <corbet@lwn.net>

Reviewed-by: Randy Dunlap <rdunlap@infradead.org>

Thanks.

> ---
>  Documentation/maintainer/configure-git.rst | 28 ----------------------
>  Documentation/process/5.Posting.rst        |  7 +++---
>  2 files changed, 3 insertions(+), 32 deletions(-)
> 
> diff --git a/Documentation/maintainer/configure-git.rst b/Documentation/maintainer/configure-git.rst
> index 0a36831814ea..0c21f203cf7a 100644
> --- a/Documentation/maintainer/configure-git.rst
> +++ b/Documentation/maintainer/configure-git.rst
> @@ -28,31 +28,3 @@ You may also like to tell ``gpg`` which ``tty`` to use (add to your shell
>  rc file)::
>  
>  	export GPG_TTY=$(tty)
> -
> -
> -Creating commit links to lore.kernel.org
> -----------------------------------------
> -
> -The web site https://lore.kernel.org is meant as a grand archive of all mail
> -list traffic concerning or influencing the kernel development. Storing archives
> -of patches here is a recommended practice, and when a maintainer applies a
> -patch to a subsystem tree, it is a good idea to provide a Link: tag with a
> -reference back to the lore archive so that people that browse the commit
> -history can find related discussions and rationale behind a certain change.
> -The link tag will look like this::
> -
> -    Link: https://lore.kernel.org/r/<message-id>
> -
> -This can be configured to happen automatically any time you issue ``git am``
> -by adding the following hook into your git::
> -
> -	$ git config am.messageid true
> -	$ cat >.git/hooks/applypatch-msg <<'EOF'
> -	#!/bin/sh
> -	. git-sh-setup
> -	perl -pi -e 's|^Message-I[dD]:\s*<?([^>]+)>?$|Link: https://lore.kernel.org/r/$1|g;' "$1"
> -	test -x "$GIT_DIR/hooks/commit-msg" &&
> -		exec "$GIT_DIR/hooks/commit-msg" ${1+"$@"}
> -	:
> -	EOF
> -	$ chmod a+x .git/hooks/applypatch-msg
> diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.Posting.rst
> index 22fa925353cf..9999bcbdccc9 100644
> --- a/Documentation/process/5.Posting.rst
> +++ b/Documentation/process/5.Posting.rst
> @@ -207,10 +207,9 @@ document with a specification implemented by the patch::
>  
>  	Link: https://example.com/somewhere.html  optional-other-stuff
>  
> -Many maintainers when applying a patch also add this tag to link to the
> -latest public review posting of the patch; often this is automatically done
> -by tools like b4 or a git hook like the one described in
> -'Documentation/maintainer/configure-git.rst'.
> +As per guidance from the Chief Penguin, a Link: tag should only be added to
> +a commit if it leads to useful information that is not found in the commit
> +itself.
>  
>  If the URL points to a public bug report being fixed by the patch, use the
>  "Closes:" tag instead::

-- 
~Randy