[PATCH 0/2] Documentation: update information for mailing lists

[PATCH 0/2] Documentation: update information for mailing lists

[Konstantin Ryabitsev]

There have been some important changes to the mailing lists hosted at
kernel.org, most importantly that vger.kernel.org was migrated from
majordomo+zmailer to mlmmj and is now being served from the unified
mailing list platform called "subspace" [1].

This series updates many links pointing at obsolete locations, but also
makes the following changes:

- drops the recommendation to use /r/ subpaths in lore.kernel.org links
(it has been unnecessary for a number of years)
- adds some detail on how to reference specific Link trailers from
inside the commit message

Some of these changes are the result of discussions on the ksummit
mailing list [2].

Link: https://subspace.kernel.org # [1]
Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat/ # [2]
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
---
Konstantin Ryabitsev (2):
      Documentation: fix links to mailing list services
      Documentation: best practices for using Link trailers

 Documentation/process/2.Process.rst          |  8 ++++----
 Documentation/process/howto.rst              | 10 +++++-----
 Documentation/process/kernel-docs.rst        |  5 ++---
 Documentation/process/maintainer-netdev.rst  |  5 ++---
 Documentation/process/maintainer-tip.rst     | 24 ++++++++++++++++++------
 Documentation/process/submitting-patches.rst | 15 +++++----------
 6 files changed, 36 insertions(+), 31 deletions(-)
---
base-commit: 6ba59ff4227927d3a8530fc2973b80e94b54d58f
change-id: 20240618-docs-patch-msgid-link-6961045516e0

Best regards,
-- 
Konstantin Ryabitsev <konstantin@linuxfoundation.org>

[PATCH 1/2] Documentation: fix links to mailing list services

[Konstantin Ryabitsev]

There have been some changes to the way mailing lists are hosted at
kernel.org, so fix the links that are pointing at the outdated
resources.

Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
---
 Documentation/process/2.Process.rst          |  8 ++++----
 Documentation/process/howto.rst              | 10 +++++-----
 Documentation/process/kernel-docs.rst        |  5 ++---
 Documentation/process/maintainer-netdev.rst  |  5 ++---
 Documentation/process/submitting-patches.rst | 15 +++++----------
 5 files changed, 18 insertions(+), 25 deletions(-)

diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst
index 613a01da4717..ef3b116492df 100644
--- a/Documentation/process/2.Process.rst
+++ b/Documentation/process/2.Process.rst
@@ -392,13 +392,13 @@ represent a potential hazard to developers, who risk getting buried under a
 load of electronic mail, running afoul of the conventions used on the Linux
 lists, or both.
 
-Most kernel mailing lists are run on vger.kernel.org; the master list can
+Most kernel mailing lists are hosted at kernel.org; the master list can
 be found at:
 
-	http://vger.kernel.org/vger-lists.html
+	https://subspace.kernel.org
 
-There are lists hosted elsewhere, though; a number of them are at
-redhat.com/mailman/listinfo.
+There are lists hosted elsewhere; please check the MAINTAINERS file for
+the list relevant for any particular subsystem.
 
 The core mailing list for kernel development is, of course, linux-kernel.
 This list is an intimidating place to be; volume can reach 500 messages per
diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
index eebda4910a88..9438e03d6f50 100644
--- a/Documentation/process/howto.rst
+++ b/Documentation/process/howto.rst
@@ -331,7 +331,7 @@ they need to be integration-tested.  For this purpose, a special
 testing repository exists into which virtually all subsystem trees are
 pulled on an almost daily basis:
 
-	https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
+	https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
 
 This way, the linux-next gives a summary outlook onto what will be
 expected to go into the mainline kernel at the next merge period.
@@ -373,12 +373,12 @@ As some of the above documents describe, the majority of the core kernel
 developers participate on the Linux Kernel Mailing list.  Details on how
 to subscribe and unsubscribe from the list can be found at:
 
-	http://vger.kernel.org/vger-lists.html#linux-kernel
+	https://subspace.kernel.org/subscribing.html
 
 There are archives of the mailing list on the web in many different
 places.  Use a search engine to find these archives.  For example:
 
-	https://lore.kernel.org/lkml/
+	https://lore.kernel.org/linux-kernel/
 
 It is highly recommended that you search the archives about the topic
 you want to bring up, before you post it to the list. A lot of things
@@ -393,13 +393,13 @@ groups.
 Many of the lists are hosted on kernel.org. Information on them can be
 found at:
 
-	http://vger.kernel.org/vger-lists.html
+	https://subspace.kernel.org
 
 Please remember to follow good behavioral habits when using the lists.
 Though a bit cheesy, the following URL has some simple guidelines for
 interacting with the list (or any list):
 
-	http://www.albion.com/netiquette/
+	https://subspace.kernel.org/etiquette.html
 
 If multiple people respond to your mail, the CC: list of recipients may
 get pretty large. Don't remove anybody from the CC: list without a good
diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
index 8660493b91d0..3476fb854c7a 100644
--- a/Documentation/process/kernel-docs.rst
+++ b/Documentation/process/kernel-docs.rst
@@ -194,9 +194,8 @@ Miscellaneous
 
     * Name: **linux-kernel mailing list archives and search engines**
 
-      :URL: http://vger.kernel.org/vger-lists.html
-      :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html
-      :URL: http://groups.google.com/group/mlist.linux.kernel
+      :URL: https://subspace.kernel.org
+      :URL: https://lore.kernel.org
       :Keywords: linux-kernel, archives, search.
       :Description: Some of the linux-kernel mailing list archivers. If
         you have a better/another one, please let me know.
diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
index 5e1fcfad1c4c..fe8616397d63 100644
--- a/Documentation/process/maintainer-netdev.rst
+++ b/Documentation/process/maintainer-netdev.rst
@@ -25,9 +25,8 @@ drivers/net (i.e. hardware specific drivers) in the Linux source tree.
 Note that some subsystems (e.g. wireless drivers) which have a high
 volume of traffic have their own specific mailing lists and trees.
 
-The netdev list is managed (like many other Linux mailing lists) through
-VGER (http://vger.kernel.org/) with archives available at
-https://lore.kernel.org/netdev/
+Like many other Linux mailing lists, the netdev list is hosted at
+kernel.org with archives available at https://lore.kernel.org/netdev/.
 
 Aside from subsystems like those mentioned above, all network-related
 Linux development (i.e. RFC, review, comments, etc.) takes place on
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 66029999b587..f310f2f36666 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -119,10 +119,10 @@ web, point to it.
 
 When linking to mailing list archives, preferably use the lore.kernel.org
 message archiver service. To create the link URL, use the contents of the
-``Message-Id`` header of the message without the surrounding angle brackets.
+``Message-ID`` header of the message without the surrounding angle brackets.
 For example::
 
-    Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
+    Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI
 
 Please check the link to make sure that it is actually working and points
 to the relevant message.
@@ -243,11 +243,9 @@ linux-kernel@vger.kernel.org should be used by default for all patches, but the
 volume on that list has caused a number of developers to tune it out.  Please
 do not spam unrelated lists and unrelated people, though.
 
-Many kernel-related lists are hosted on vger.kernel.org; you can find a
-list of them at http://vger.kernel.org/vger-lists.html.  There are
-kernel-related lists hosted elsewhere as well, though.
-
-Do not send more than 15 patches at once to the vger mailing lists!!!
+Many kernel-related lists are hosted at kernel.org; you can find a list
+of them at https://subspace.kernel.org.  There are kernel-related lists
+hosted elsewhere as well, though.
 
 Linus Torvalds is the final arbiter of all changes accepted into the
 Linux kernel.  His e-mail address is <torvalds@linux-foundation.org>.
@@ -866,9 +864,6 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
 
   <http://www.kroah.com/log/linux/maintainer-06.html>
 
-NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
-  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
-
 Kernel Documentation/process/coding-style.rst
 
 Linus Torvalds's mail on the canonical patch format:

-- 
2.45.2

Re: [PATCH 1/2] Documentation: fix links to mailing list services

[Dan Williams]

Konstantin Ryabitsev wrote:
> There have been some changes to the way mailing lists are hosted at
> kernel.org, so fix the links that are pointing at the outdated
> resources.

The change to the documented policy about patch-bombs probably deserves
a mention here even though it has been effectively ignored for a while.

Otherwise,

Acked-by: Dan Williams <dan.j.williams@intel.com>

[..]
> diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
> index 5e1fcfad1c4c..fe8616397d63 100644
> --- a/Documentation/process/maintainer-netdev.rst
> +++ b/Documentation/process/maintainer-netdev.rst
[..]
> @@ -243,11 +243,9 @@ linux-kernel@vger.kernel.org should be used by default for all patches, but the
>  volume on that list has caused a number of developers to tune it out.  Please
>  do not spam unrelated lists and unrelated people, though.
>  
> -Many kernel-related lists are hosted on vger.kernel.org; you can find a
> -list of them at http://vger.kernel.org/vger-lists.html.  There are
> -kernel-related lists hosted elsewhere as well, though.
> -
> -Do not send more than 15 patches at once to the vger mailing lists!!!
> +Many kernel-related lists are hosted at kernel.org; you can find a list
> +of them at https://subspace.kernel.org.  There are kernel-related lists
> +hosted elsewhere as well, though.
>  
>  Linus Torvalds is the final arbiter of all changes accepted into the
>  Linux kernel.  His e-mail address is <torvalds@linux-foundation.org>.
> @@ -866,9 +864,6 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
>  
>    <http://www.kroah.com/log/linux/maintainer-06.html>
>  
> -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
> -  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
> -
>  Kernel Documentation/process/coding-style.rst
>  
>  Linus Torvalds's mail on the canonical patch format:
> 
> -- 
> 2.45.2
> 
> 

Re: [PATCH 1/2] Documentation: fix links to mailing list services

[Carlos Bilbao]

On 6/18/24 11:42, Konstantin Ryabitsev wrote:

> There have been some changes to the way mailing lists are hosted at
> kernel.org, so fix the links that are pointing at the outdated
> resources.
>
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> ---
>  Documentation/process/2.Process.rst          |  8 ++++----
>  Documentation/process/howto.rst              | 10 +++++-----
>  Documentation/process/kernel-docs.rst        |  5 ++---
>  Documentation/process/maintainer-netdev.rst  |  5 ++---
>  Documentation/process/submitting-patches.rst | 15 +++++----------
>  5 files changed, 18 insertions(+), 25 deletions(-)
>
> diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst
> index 613a01da4717..ef3b116492df 100644
> --- a/Documentation/process/2.Process.rst
> +++ b/Documentation/process/2.Process.rst
> @@ -392,13 +392,13 @@ represent a potential hazard to developers, who risk getting buried under a
>  load of electronic mail, running afoul of the conventions used on the Linux
>  lists, or both.
>  
> -Most kernel mailing lists are run on vger.kernel.org; the master list can
> +Most kernel mailing lists are hosted at kernel.org; the master list can
>  be found at:
>  
> -	http://vger.kernel.org/vger-lists.html
> +	https://subspace.kernel.org
>  
> -There are lists hosted elsewhere, though; a number of them are at
> -redhat.com/mailman/listinfo.
> +There are lists hosted elsewhere; please check the MAINTAINERS file for
> +the list relevant for any particular subsystem.
>  
>  The core mailing list for kernel development is, of course, linux-kernel.
>  This list is an intimidating place to be; volume can reach 500 messages per
> diff --git a/Documentation/process/howto.rst b/Documentation/process/howto.rst
> index eebda4910a88..9438e03d6f50 100644
> --- a/Documentation/process/howto.rst
> +++ b/Documentation/process/howto.rst
> @@ -331,7 +331,7 @@ they need to be integration-tested.  For this purpose, a special
>  testing repository exists into which virtually all subsystem trees are
>  pulled on an almost daily basis:
>  
> -	https://git.kernel.org/?p=linux/kernel/git/next/linux-next.git
> +	https://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git
>  
>  This way, the linux-next gives a summary outlook onto what will be
>  expected to go into the mainline kernel at the next merge period.
> @@ -373,12 +373,12 @@ As some of the above documents describe, the majority of the core kernel
>  developers participate on the Linux Kernel Mailing list.  Details on how
>  to subscribe and unsubscribe from the list can be found at:
>  
> -	http://vger.kernel.org/vger-lists.html#linux-kernel
> +	https://subspace.kernel.org/subscribing.html
>  
>  There are archives of the mailing list on the web in many different
>  places.  Use a search engine to find these archives.  For example:
>  
> -	https://lore.kernel.org/lkml/
> +	https://lore.kernel.org/linux-kernel/
>  
>  It is highly recommended that you search the archives about the topic
>  you want to bring up, before you post it to the list. A lot of things
> @@ -393,13 +393,13 @@ groups.
>  Many of the lists are hosted on kernel.org. Information on them can be
>  found at:
>  
> -	http://vger.kernel.org/vger-lists.html
> +	https://subspace.kernel.org
>  
>  Please remember to follow good behavioral habits when using the lists.
>  Though a bit cheesy, the following URL has some simple guidelines for
>  interacting with the list (or any list):
>  
> -	http://www.albion.com/netiquette/
> +	https://subspace.kernel.org/etiquette.html
>  
>  If multiple people respond to your mail, the CC: list of recipients may
>  get pretty large. Don't remove anybody from the CC: list without a good
> diff --git a/Documentation/process/kernel-docs.rst b/Documentation/process/kernel-docs.rst
> index 8660493b91d0..3476fb854c7a 100644
> --- a/Documentation/process/kernel-docs.rst
> +++ b/Documentation/process/kernel-docs.rst
> @@ -194,9 +194,8 @@ Miscellaneous
>  
>      * Name: **linux-kernel mailing list archives and search engines**
>  
> -      :URL: http://vger.kernel.org/vger-lists.html
> -      :URL: http://www.uwsg.indiana.edu/hypermail/linux/kernel/index.html
> -      :URL: http://groups.google.com/group/mlist.linux.kernel
> +      :URL: https://subspace.kernel.org
> +      :URL: https://lore.kernel.org


Nice!
Reviewed-by: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>


>        :Keywords: linux-kernel, archives, search.
>        :Description: Some of the linux-kernel mailing list archivers. If
>          you have a better/another one, please let me know.
> diff --git a/Documentation/process/maintainer-netdev.rst b/Documentation/process/maintainer-netdev.rst
> index 5e1fcfad1c4c..fe8616397d63 100644
> --- a/Documentation/process/maintainer-netdev.rst
> +++ b/Documentation/process/maintainer-netdev.rst
> @@ -25,9 +25,8 @@ drivers/net (i.e. hardware specific drivers) in the Linux source tree.
>  Note that some subsystems (e.g. wireless drivers) which have a high
>  volume of traffic have their own specific mailing lists and trees.
>  
> -The netdev list is managed (like many other Linux mailing lists) through
> -VGER (http://vger.kernel.org/) with archives available at
> -https://lore.kernel.org/netdev/
> +Like many other Linux mailing lists, the netdev list is hosted at
> +kernel.org with archives available at https://lore.kernel.org/netdev/.
>  
>  Aside from subsystems like those mentioned above, all network-related
>  Linux development (i.e. RFC, review, comments, etc.) takes place on
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index 66029999b587..f310f2f36666 100644
> --- a/Documentation/process/submitting-patches.rst
> +++ b/Documentation/process/submitting-patches.rst
> @@ -119,10 +119,10 @@ web, point to it.
>  
>  When linking to mailing list archives, preferably use the lore.kernel.org
>  message archiver service. To create the link URL, use the contents of the
> -``Message-Id`` header of the message without the surrounding angle brackets.
> +``Message-ID`` header of the message without the surrounding angle brackets.
>  For example::
>  
> -    Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
> +    Link: https://lore.kernel.org/30th.anniversary.repost@klaava.Helsinki.FI
>  
>  Please check the link to make sure that it is actually working and points
>  to the relevant message.
> @@ -243,11 +243,9 @@ linux-kernel@vger.kernel.org should be used by default for all patches, but the
>  volume on that list has caused a number of developers to tune it out.  Please
>  do not spam unrelated lists and unrelated people, though.
>  
> -Many kernel-related lists are hosted on vger.kernel.org; you can find a
> -list of them at http://vger.kernel.org/vger-lists.html.  There are
> -kernel-related lists hosted elsewhere as well, though.
> -
> -Do not send more than 15 patches at once to the vger mailing lists!!!
> +Many kernel-related lists are hosted at kernel.org; you can find a list
> +of them at https://subspace.kernel.org.  There are kernel-related lists
> +hosted elsewhere as well, though.
>  
>  Linus Torvalds is the final arbiter of all changes accepted into the
>  Linux kernel.  His e-mail address is <torvalds@linux-foundation.org>.
> @@ -866,9 +864,6 @@ Greg Kroah-Hartman, "How to piss off a kernel subsystem maintainer".
>  
>    <http://www.kroah.com/log/linux/maintainer-06.html>
>  
> -NO!!!! No more huge patch bombs to linux-kernel@vger.kernel.org people!
> -  <https://lore.kernel.org/r/20050711.125305.08322243.davem@davemloft.net>
> -
>  Kernel Documentation/process/coding-style.rst
>  
>  Linus Torvalds's mail on the canonical patch format:
>

Thanks,
Carlos

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

[Konstantin Ryabitsev]

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

Cc: ksummit@lists.linux.dev
Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat # [1]
Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
---
 Documentation/process/maintainer-tip.rst | 24 ++++++++++++++++++------
 1 file changed, 18 insertions(+), 6 deletions(-)

diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
index 64739968afa6..57ffa553c21e 100644
--- a/Documentation/process/maintainer-tip.rst
+++ b/Documentation/process/maintainer-tip.rst
@@ -375,14 +375,26 @@ following tag ordering scheme:
    For referring to an email on LKML or other kernel mailing lists,
    please use the lore.kernel.org redirector URL::
 
-     https://lore.kernel.org/r/email-message@id
+     Link: https://lore.kernel.org/email-message@id
 
-   The kernel.org redirector is considered a stable URL, unlike other email
-   archives.
+   This URL should be used when referring to relevant mailing list
+   resources, related patch sets, or other notable discussion threads.
+   A convenient way to associate Link trailers with the accompanying
+   message is to use markdown-like bracketed notation, for example::
 
-   Maintainers will add a Link tag referencing the email of the patch
-   submission when they apply a patch to the tip tree. This tag is useful
-   for later reference and is also used for commit notifications.
+     A similar approach was attempted before as part of a different
+     effort [1], but the initial implementation caused too many
+     regressions [2], so it was backed out and reimplemented.
+
+     Link: https://lore.kernel.org/some-msgid@here # [1]
+     Link: https://bugzilla.example.org/bug/12345  # [2]
+
+   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
 
 Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
 they just complicate automated extraction of tags.

-- 
2.45.2

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

[Leon Romanovsky]

On Tue, Jun 18, 2024 at 12:42:11PM -0400, 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
> 
> Cc: ksummit@lists.linux.dev
> Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat # [1]
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> ---
>  Documentation/process/maintainer-tip.rst | 24 ++++++++++++++++++------
>  1 file changed, 18 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> index 64739968afa6..57ffa553c21e 100644
> --- a/Documentation/process/maintainer-tip.rst
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -375,14 +375,26 @@ following tag ordering scheme:
>     For referring to an email on LKML or other kernel mailing lists,
>     please use the lore.kernel.org redirector URL::
>  
> -     https://lore.kernel.org/r/email-message@id
> +     Link: https://lore.kernel.org/email-message@id
>  
> -   The kernel.org redirector is considered a stable URL, unlike other email
> -   archives.
> +   This URL should be used when referring to relevant mailing list
> +   resources, related patch sets, or other notable discussion threads.
> +   A convenient way to associate Link trailers with the accompanying
> +   message is to use markdown-like bracketed notation, for example::
>  
> -   Maintainers will add a Link tag referencing the email of the patch
> -   submission when they apply a patch to the tip tree. This tag is useful
> -   for later reference and is also used for commit notifications.
> +     A similar approach was attempted before as part of a different
> +     effort [1], but the initial implementation caused too many
> +     regressions [2], so it was backed out and reimplemented.
> +
> +     Link: https://lore.kernel.org/some-msgid@here # [1]
> +     Link: https://bugzilla.example.org/bug/12345  # [2]
> +
> +   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

Default b4.linkmask points to https://msgid.link/ and not to https://patch.msgid.link/

https://git.kernel.org/pub/scm/utils/b4/b4.git/tree/.b4-config#n3
https://git.kernel.org/pub/scm/utils/b4/b4.git/tree/docs/config.rst#n46

It will be good to update the default value in b4 to point to the correct domain.

Thanks

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

[Konstantin Ryabitsev]

On Wed, Jun 19, 2024 at 10:12:51AM GMT, Leon Romanovsky wrote:
> Default b4.linkmask points to https://msgid.link/ and not to https://patch.msgid.link/

That's the default for the b4 project itself, though, not the global default.

> https://git.kernel.org/pub/scm/utils/b4/b4.git/tree/.b4-config#n3
> https://git.kernel.org/pub/scm/utils/b4/b4.git/tree/docs/config.rst#n46
> 
> It will be good to update the default value in b4 to point to the correct domain.

Once the series is accepted and becomes the official documentation, I will be
happy to change the global default.

-K

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

[Dan Carpenter]

On Tue, Jun 18, 2024 at 12:42:11PM -0400, 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

You should add something to checkpatch to complain about patch.msgid.link
URLs.  Those URLs should only be added by the committers, not the patch
authors.

regards,
dan carpenter

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

[Michael S. Tsirkin]

On Tue, Jun 18, 2024 at 12:42:11PM -0400, 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
> 
> Cc: ksummit@lists.linux.dev
> Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat # [1]
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> ---
>  Documentation/process/maintainer-tip.rst | 24 ++++++++++++++++++------
>  1 file changed, 18 insertions(+), 6 deletions(-)
> 
> diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> index 64739968afa6..57ffa553c21e 100644
> --- a/Documentation/process/maintainer-tip.rst
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -375,14 +375,26 @@ following tag ordering scheme:
>     For referring to an email on LKML or other kernel mailing lists,
>     please use the lore.kernel.org redirector URL::
>  
> -     https://lore.kernel.org/r/email-message@id
> +     Link: https://lore.kernel.org/email-message@id
>  
> -   The kernel.org redirector is considered a stable URL, unlike other email
> -   archives.
> +   This URL should be used when referring to relevant mailing list
> +   resources, related patch sets, or other notable discussion threads.
> +   A convenient way to associate Link trailers with the accompanying
> +   message is to use markdown-like bracketed notation, for example::
>  
> -   Maintainers will add a Link tag referencing the email of the patch
> -   submission when they apply a patch to the tip tree. This tag is useful
> -   for later reference and is also used for commit notifications.
> +     A similar approach was attempted before as part of a different
> +     effort [1], but the initial implementation caused too many
> +     regressions [2], so it was backed out and reimplemented.
> +
> +     Link: https://lore.kernel.org/some-msgid@here # [1]
> +     Link: https://bugzilla.example.org/bug/12345  # [2]
> +
> +   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
>  
>  Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
>  they just complicate automated extraction of tags.

I don't really understand what this is saying.
So when is msgid.link preferable to kernel.org?
And when is kernel.org preferable to msgid?



> -- 
> 2.45.2
> 

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

[Michael S. Tsirkin]

On Wed, Jun 19, 2024 at 04:41:49AM -0400, Michael S. Tsirkin wrote:
> On Tue, Jun 18, 2024 at 12:42:11PM -0400, 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
> > 
> > Cc: ksummit@lists.linux.dev
> > Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat # [1]
> > Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> > ---
> >  Documentation/process/maintainer-tip.rst | 24 ++++++++++++++++++------
> >  1 file changed, 18 insertions(+), 6 deletions(-)
> > 
> > diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> > index 64739968afa6..57ffa553c21e 100644
> > --- a/Documentation/process/maintainer-tip.rst
> > +++ b/Documentation/process/maintainer-tip.rst
> > @@ -375,14 +375,26 @@ following tag ordering scheme:
> >     For referring to an email on LKML or other kernel mailing lists,
> >     please use the lore.kernel.org redirector URL::
> >  
> > -     https://lore.kernel.org/r/email-message@id
> > +     Link: https://lore.kernel.org/email-message@id
> >  
> > -   The kernel.org redirector is considered a stable URL, unlike other email
> > -   archives.
> > +   This URL should be used when referring to relevant mailing list
> > +   resources, related patch sets, or other notable discussion threads.
> > +   A convenient way to associate Link trailers with the accompanying
> > +   message is to use markdown-like bracketed notation, for example::
> >  
> > -   Maintainers will add a Link tag referencing the email of the patch
> > -   submission when they apply a patch to the tip tree. This tag is useful
> > -   for later reference and is also used for commit notifications.
> > +     A similar approach was attempted before as part of a different
> > +     effort [1], but the initial implementation caused too many
> > +     regressions [2], so it was backed out and reimplemented.
> > +
> > +     Link: https://lore.kernel.org/some-msgid@here # [1]
> > +     Link: https://bugzilla.example.org/bug/12345  # [2]
> > +
> > +   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
> >  
> >  Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
> >  they just complicate automated extraction of tags.
> 
> I don't really understand what this is saying.
> So when is msgid.link preferable to kernel.org?
> And when is kernel.org preferable to msgid?


After reading the discussion in the commit log, it's now clearer what's meant
to me, but the Documentation patch itself does not really make it clear
IMHO.


It is also sad that instead of just setting
[am]
        messageid = true

one now apparently has to resort to funky scripts.
Any chance to at least document the best practices - what has to be done
as part of this patch to make git-am create these Link: things?


Thanks!


> 
> 
> > -- 
> > 2.45.2
> > 

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

[Jani Nikula]

On Tue, 18 Jun 2024, Konstantin Ryabitsev <konstantin@linuxfoundation.org> 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
>
> Cc: ksummit@lists.linux.dev
> Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat # [1]
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> ---
>  Documentation/process/maintainer-tip.rst | 24 ++++++++++++++++++------
>  1 file changed, 18 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> index 64739968afa6..57ffa553c21e 100644
> --- a/Documentation/process/maintainer-tip.rst
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -375,14 +375,26 @@ following tag ordering scheme:
>     For referring to an email on LKML or other kernel mailing lists,
>     please use the lore.kernel.org redirector URL::
>  
> -     https://lore.kernel.org/r/email-message@id
> +     Link: https://lore.kernel.org/email-message@id
>  
> -   The kernel.org redirector is considered a stable URL, unlike other email
> -   archives.
> +   This URL should be used when referring to relevant mailing list
> +   resources, related patch sets, or other notable discussion threads.
> +   A convenient way to associate Link trailers with the accompanying
> +   message is to use markdown-like bracketed notation, for example::
>  
> -   Maintainers will add a Link tag referencing the email of the patch
> -   submission when they apply a patch to the tip tree. This tag is useful
> -   for later reference and is also used for commit notifications.
> +     A similar approach was attempted before as part of a different
> +     effort [1], but the initial implementation caused too many
> +     regressions [2], so it was backed out and reimplemented.
> +
> +     Link: https://lore.kernel.org/some-msgid@here # [1]
> +     Link: https://bugzilla.example.org/bug/12345  # [2]
> +
> +   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::

Mostly highlighting my own ignorance here, but s/provenance/origin/
would've felt more obvious to me, as a non-native speaker.

BR,
Jani.


> +
> +     Link: https://patch.msgid.link/patch-source-msgid@here
>  
>  Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
>  they just complicate automated extraction of tags.

-- 
Jani Nikula, Intel

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

[Michael S. Tsirkin]

On Wed, Jun 19, 2024 at 11:50:48AM +0300, Jani Nikula wrote:
> On Tue, 18 Jun 2024, Konstantin Ryabitsev <konstantin@linuxfoundation.org> 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
> >
> > Cc: ksummit@lists.linux.dev
> > Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat # [1]
> > Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> > ---
> >  Documentation/process/maintainer-tip.rst | 24 ++++++++++++++++++------
> >  1 file changed, 18 insertions(+), 6 deletions(-)
> >
> > diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> > index 64739968afa6..57ffa553c21e 100644
> > --- a/Documentation/process/maintainer-tip.rst
> > +++ b/Documentation/process/maintainer-tip.rst
> > @@ -375,14 +375,26 @@ following tag ordering scheme:
> >     For referring to an email on LKML or other kernel mailing lists,
> >     please use the lore.kernel.org redirector URL::
> >  
> > -     https://lore.kernel.org/r/email-message@id
> > +     Link: https://lore.kernel.org/email-message@id
> >  
> > -   The kernel.org redirector is considered a stable URL, unlike other email
> > -   archives.
> > +   This URL should be used when referring to relevant mailing list
> > +   resources, related patch sets, or other notable discussion threads.
> > +   A convenient way to associate Link trailers with the accompanying
> > +   message is to use markdown-like bracketed notation, for example::
> >  
> > -   Maintainers will add a Link tag referencing the email of the patch
> > -   submission when they apply a patch to the tip tree. This tag is useful
> > -   for later reference and is also used for commit notifications.
> > +     A similar approach was attempted before as part of a different
> > +     effort [1], but the initial implementation caused too many
> > +     regressions [2], so it was backed out and reimplemented.
> > +
> > +     Link: https://lore.kernel.org/some-msgid@here # [1]
> > +     Link: https://bugzilla.example.org/bug/12345  # [2]
> > +
> > +   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::
> 
> Mostly highlighting my own ignorance here, but s/provenance/origin/
> would've felt more obvious to me, as a non-native speaker.
> 
> BR,
> Jani.

Or even "origin (message id)" to be very explicit.






> 
> > +
> > +     Link: https://patch.msgid.link/patch-source-msgid@here
> >  
> >  Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
> >  they just complicate automated extraction of tags.
> 
> -- 
> Jani Nikula, Intel

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

[Thorsten Leemhuis]

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

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

[Carlos Bilbao]

On 6/18/24 11: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
>
> Cc: ksummit@lists.linux.dev
> Link: https://lore.kernel.org/20240617-arboreal-industrious-hedgehog-5b84ae@meerkat # [1]
> Signed-off-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>


Nice! 

Acked-by: Carlos Bilbao <carlos.bilbao.osdev@gmail.com>


> ---
>  Documentation/process/maintainer-tip.rst | 24 ++++++++++++++++++------
>  1 file changed, 18 insertions(+), 6 deletions(-)
>
> diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> index 64739968afa6..57ffa553c21e 100644
> --- a/Documentation/process/maintainer-tip.rst
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -375,14 +375,26 @@ following tag ordering scheme:
>     For referring to an email on LKML or other kernel mailing lists,
>     please use the lore.kernel.org redirector URL::
>  
> -     https://lore.kernel.org/r/email-message@id
> +     Link: https://lore.kernel.org/email-message@id
>  
> -   The kernel.org redirector is considered a stable URL, unlike other email
> -   archives.
> +   This URL should be used when referring to relevant mailing list
> +   resources, related patch sets, or other notable discussion threads.
> +   A convenient way to associate Link trailers with the accompanying
> +   message is to use markdown-like bracketed notation, for example::
>  
> -   Maintainers will add a Link tag referencing the email of the patch
> -   submission when they apply a patch to the tip tree. This tag is useful
> -   for later reference and is also used for commit notifications.
> +     A similar approach was attempted before as part of a different
> +     effort [1], but the initial implementation caused too many
> +     regressions [2], so it was backed out and reimplemented.
> +
> +     Link: https://lore.kernel.org/some-msgid@here # [1]
> +     Link: https://bugzilla.example.org/bug/12345  # [2]
> +
> +   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
>  
>  Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
>  they just complicate automated extraction of tags.


Thanks,
Carlos

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

[Steven Rostedt]

On Tue, 18 Jun 2024 12:42:11 -0400
Konstantin Ryabitsev <konstantin@linuxfoundation.org> wrote:

> 
> diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> index 64739968afa6..57ffa553c21e 100644
> --- a/Documentation/process/maintainer-tip.rst
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -375,14 +375,26 @@ following tag ordering scheme:
>     For referring to an email on LKML or other kernel mailing lists,
>     please use the lore.kernel.org redirector URL::
>  
> -     https://lore.kernel.org/r/email-message@id
> +     Link: https://lore.kernel.org/email-message@id
>  
> -   The kernel.org redirector is considered a stable URL, unlike other email
> -   archives.
> +   This URL should be used when referring to relevant mailing list
> +   resources, related patch sets, or other notable discussion threads.
> +   A convenient way to associate Link trailers with the accompanying
> +   message is to use markdown-like bracketed notation, for example::
>  
> -   Maintainers will add a Link tag referencing the email of the patch
> -   submission when they apply a patch to the tip tree. This tag is useful
> -   for later reference and is also used for commit notifications.
> +     A similar approach was attempted before as part of a different
> +     effort [1], but the initial implementation caused too many
> +     regressions [2], so it was backed out and reimplemented.
> +
> +     Link: https://lore.kernel.org/some-msgid@here # [1]
> +     Link: https://bugzilla.example.org/bug/12345  # [2]
> +
> +   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

Hmm, I mentioned this in the other thread, but I also like the fact
that my automated script uses the list that it was Cc'd to. That is, if
it Cc'd linux-trace-kernel, if not, if it Cc'd linux-trace-devel, it
adds that, otherwise it uses lkml. Now, I could just make the lkml use
the patch-source-msgid instead.

This does give me some information about what the focus of the patch
was. Hmm, maybe I could just make it:

  Link: https://patch.msgid.link/patch-source-msgid@here # linux-trace-devel

Would anyone have an issue with that?

-- Steve


>  
>  Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
>  they just complicate automated extraction of tags.
> 

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

[Geert Uytterhoeven]

Hi Steven,

On Tue, Jun 25, 2024 at 11:27 PM Steven Rostedt <rostedt@goodmis.org> wrote:
> On Tue, 18 Jun 2024 12:42:11 -0400
> Konstantin Ryabitsev <konstantin@linuxfoundation.org> wrote:
> > +     A similar approach was attempted before as part of a different
> > +     effort [1], but the initial implementation caused too many
> > +     regressions [2], so it was backed out and reimplemented.
> > +
> > +     Link: https://lore.kernel.org/some-msgid@here # [1]
> > +     Link: https://bugzilla.example.org/bug/12345  # [2]
> > +
> > +   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
>
> Hmm, I mentioned this in the other thread, but I also like the fact
> that my automated script uses the list that it was Cc'd to. That is, if
> it Cc'd linux-trace-kernel, if not, if it Cc'd linux-trace-devel, it
> adds that, otherwise it uses lkml. Now, I could just make the lkml use
> the patch-source-msgid instead.
>
> This does give me some information about what the focus of the patch
> was. Hmm, maybe I could just make it:
>
>   Link: https://patch.msgid.link/patch-source-msgid@here # linux-trace-devel
>
> Would anyone have an issue with that?

Or, just like with lore links:

    https://patch.msgid.link/linux-trace-devel/patch-source-msgid@here

Gr{oetje,eeting}s,

                        Geert

-- 
Geert Uytterhoeven -- There's lots of Linux beyond ia32 -- geert@linux-m68k.org

In personal conversations with technical people, I call myself a hacker. But
when I'm talking to journalists I just say "programmer" or something like that.
                                -- Linus Torvalds

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

[Konstantin Ryabitsev]

On Wed, Jun 26, 2024 at 10:12:35AM GMT, Geert Uytterhoeven wrote:
> > > +     Link: https://patch.msgid.link/patch-source-msgid@here
> >
> > Hmm, I mentioned this in the other thread, but I also like the fact
> > that my automated script uses the list that it was Cc'd to. That is, if
> > it Cc'd linux-trace-kernel, if not, if it Cc'd linux-trace-devel, it
> > adds that, otherwise it uses lkml. Now, I could just make the lkml use
> > the patch-source-msgid instead.
> >
> > This does give me some information about what the focus of the patch
> > was. Hmm, maybe I could just make it:
> >
> >   Link: https://patch.msgid.link/patch-source-msgid@here # linux-trace-devel
> >
> > Would anyone have an issue with that?
> 
> Or, just like with lore links:
> 
>     https://patch.msgid.link/linux-trace-devel/patch-source-msgid@here

I don't recommend this because it is not always a reliable mechanism to just
take the local part of the list address and assume that it will match the list
directory on lore.kernel.org. We've had lists that moved around or got
renamed, or disambiguated for clarity.

Overall, we're generally moving away from "where was this sent?" having any
importance -- we already support lei queries and should soon have bridges
exposing patches submitted via forge interfaces. If you want to indicate the
focus of the patch, then going by the list to which it was sent is going to
increasingly lose importance.

-K