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>
---
 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::
-- 
2.51.0

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

On Mon, Sep 8, 2025 at 9:32 PM Jonathan Corbet <corbet@lwn.net> 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>

Fair enough,
Reviewed-by: Linus Walleij <linus.walleij@linaro.org>

Yours,
Linus Walleij