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

[PATCH v2 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>
---
Changes in v2:
- Minor wording changes to text and commit messages based on feedback.
- Link to v1: https://lore.kernel.org/r/20240618-docs-patch-msgid-link-v1-0-30555f3f5ad4@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     | 30 ++++++++++++++++++++--------
 Documentation/process/submitting-patches.rst | 15 +++++---------
 6 files changed, 40 insertions(+), 33 deletions(-)
---
base-commit: 6ba59ff4227927d3a8530fc2973b80e94b54d58f
change-id: 20240618-docs-patch-msgid-link-6961045516e0

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

[PATCH v2 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. This patch does the following:

1. fixes links that are pointing at the outdated resources
2. removes an outdated patchbomb admonition

We still don't particularly want or welcome huge patchbombs, but they
are less likely to overload our systems.

Acked-by: Dan Williams <dan.j.williams@intel.com>
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

[PATCH v2 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 | 30 ++++++++++++++++++++++--------
 1 file changed, 22 insertions(+), 8 deletions(-)

diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
index 64739968afa6..ba312345d030 100644
--- a/Documentation/process/maintainer-tip.rst
+++ b/Documentation/process/maintainer-tip.rst
@@ -372,17 +372,31 @@ following tag ordering scheme:
 
  - Link: ``https://link/to/information``
 
-   For referring to an email on LKML or other kernel mailing lists,
-   please use the lore.kernel.org redirector URL::
+   For referring to an email posted to the 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@here
 
-   The kernel.org redirector is considered a stable URL, unlike other email
-   archives.
+   This URL should be used when referring to relevant mailing list
+   topics, related patch sets, or other notable discussion threads.
+   A convenient way to associate ``Link:`` trailers with the commit
+   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]
+
+   You can also use ``Link:`` trailers to indicate the origin of the
+   patch when applying it to your git tree. In that case, please use the
+   dedicated ``patch.msgid.link`` domain instead of ``lore.kernel.org``.
+   This practice makes it possible for automated tooling to identify
+   which link to use to retrieve the original patch submission. For
+   example::
+
+     Link: https://patch.msgid.link/patch-source-message-id@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 v2 2/2] Documentation: best practices for using Link trailers

[Michael S. Tsirkin]

On Wed, Jun 19, 2024 at 02:24:07PM -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 | 30 ++++++++++++++++++++++--------
>  1 file changed, 22 insertions(+), 8 deletions(-)
> 
> diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> index 64739968afa6..ba312345d030 100644
> --- a/Documentation/process/maintainer-tip.rst
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -372,17 +372,31 @@ following tag ordering scheme:
>  
>   - Link: ``https://link/to/information``
>  
> -   For referring to an email on LKML or other kernel mailing lists,
> -   please use the lore.kernel.org redirector URL::
> +   For referring to an email posted to the 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@here
>  
> -   The kernel.org redirector is considered a stable URL, unlike other email
> -   archives.
> +   This URL should be used when referring to relevant mailing list
> +   topics, related patch sets, or other notable discussion threads.
> +   A convenient way to associate ``Link:`` trailers with the commit
> +   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]
> +
> +   You can also use ``Link:`` trailers to indicate the origin of the
> +   patch when applying it to your git tree. In that case, please use the
> +   dedicated ``patch.msgid.link`` domain instead of ``lore.kernel.org``.
> +   This practice makes it possible for automated tooling to identify
> +   which link to use to retrieve the original patch submission. For
> +   example::
> +
> +     Link: https://patch.msgid.link/patch-source-message-id@here
>  
>  Please do not use combined tags, e.g. ``Reported-and-tested-by``, as
>  they just complicate automated extraction of tags.

Could you please add a hint on configuring git am to create these?

I think something like this in .git/hooks/applypatch-msg will work:

. git-sh-setup
perl -pi -e 's|^Message-Id:\s*<?([^>]+)>?$|Link: https://patch.msgid.link/$1|g;' "$1"
test -x "$GIT_DIR/hooks/commit-msg" &&
        exec "$GIT_DIR/hooks/commit-msg" ${1+"$@"}
:

but I didn't actually try.

Thanks!

> -- 
> 2.45.2
> 

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

[Kees Cook]

On Wed, Jun 19, 2024 at 02:24:07PM -0400, Konstantin Ryabitsev wrote:
> +   This URL should be used when referring to relevant mailing list
> +   topics, related patch sets, or other notable discussion threads.
> +   A convenient way to associate ``Link:`` trailers with the commit
> +   message is to use markdown-like bracketed notation, for example::
> ...
> +     Link: https://lore.kernel.org/some-msgid@here # [1]
> +     Link: https://bugzilla.example.org/bug/12345  # [2]

Why are we adding the extra "# " characters? The vast majority of
existing Link tags don't do this:

$ git log --grep Link: | grep 'Link:.*\[' > links.txt
$ wc -l links.txt
1687 links.txt

# Link: URL... [1]
$ grep 'Link: .*[^#] \[' links.txt | wc -l
1546

# Link: URL... # [1]
$ grep 'Link: .* # \[' links.txt | wc -l
83

# Link: [1] URL...
$ grep 'Link: \[' links.txt | wc -l
44

# Link: URL... [#1]
$ grep 'Link: .*\[#' links.txt | wc -l
12


-- 
Kees Cook

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

[Konstantin Ryabitsev]

On Fri, Jun 21, 2024 at 02:07:44PM GMT, Kees Cook wrote:
> On Wed, Jun 19, 2024 at 02:24:07PM -0400, Konstantin Ryabitsev wrote:
> > +   This URL should be used when referring to relevant mailing list
> > +   topics, related patch sets, or other notable discussion threads.
> > +   A convenient way to associate ``Link:`` trailers with the commit
> > +   message is to use markdown-like bracketed notation, for example::
> > ...
> > +     Link: https://lore.kernel.org/some-msgid@here # [1]
> > +     Link: https://bugzilla.example.org/bug/12345  # [2]
> 
> Why are we adding the extra "# " characters? The vast majority of
> existing Link tags don't do this:

That's just convention. In general, the hash separates the trailer from the
comment:

    Trailer-name: actual-trailer-body # comment

-K

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

[Jonathan Corbet]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

> On Fri, Jun 21, 2024 at 02:07:44PM GMT, Kees Cook wrote:
>> On Wed, Jun 19, 2024 at 02:24:07PM -0400, Konstantin Ryabitsev wrote:
>> > +   This URL should be used when referring to relevant mailing list
>> > +   topics, related patch sets, or other notable discussion threads.
>> > +   A convenient way to associate ``Link:`` trailers with the commit
>> > +   message is to use markdown-like bracketed notation, for example::
>> > ...
>> > +     Link: https://lore.kernel.org/some-msgid@here # [1]
>> > +     Link: https://bugzilla.example.org/bug/12345  # [2]
>> 
>> Why are we adding the extra "# " characters? The vast majority of
>> existing Link tags don't do this:
>
> That's just convention. In general, the hash separates the trailer from the
> comment:
>
>     Trailer-name: actual-trailer-body # comment
>

Did we ever come to a conclusion on this?  This one character seems to
be the main source of disagreement in this series, I'm wondering if I
should just apply it and let the painting continue thereafter...?

jon

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

[Randy Dunlap]

On 6/26/24 4:13 PM, Jonathan Corbet wrote:
> Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:
> 
>> On Fri, Jun 21, 2024 at 02:07:44PM GMT, Kees Cook wrote:
>>> On Wed, Jun 19, 2024 at 02:24:07PM -0400, Konstantin Ryabitsev wrote:
>>>> +   This URL should be used when referring to relevant mailing list
>>>> +   topics, related patch sets, or other notable discussion threads.
>>>> +   A convenient way to associate ``Link:`` trailers with the commit
>>>> +   message is to use markdown-like bracketed notation, for example::
>>>> ...
>>>> +     Link: https://lore.kernel.org/some-msgid@here # [1]
>>>> +     Link: https://bugzilla.example.org/bug/12345  # [2]
>>>
>>> Why are we adding the extra "# " characters? The vast majority of
>>> existing Link tags don't do this:
>>
>> That's just convention. In general, the hash separates the trailer from the
>> comment:
>>
>>     Trailer-name: actual-trailer-body # comment
>>
> 
> Did we ever come to a conclusion on this?  This one character seems to
> be the main source of disagreement in this series, I'm wondering if I
> should just apply it and let the painting continue thereafter...?

We have used '#' for ages for adding comments to by: tags.
I'm surprised that it's not documented.

-- 
~Randy

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

[Thorsten Leemhuis]

On 27.06.24 01:17, Randy Dunlap wrote:
> On 6/26/24 4:13 PM, Jonathan Corbet wrote:
>> Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:
>>> On Fri, Jun 21, 2024 at 02:07:44PM GMT, Kees Cook wrote:
>>>> On Wed, Jun 19, 2024 at 02:24:07PM -0400, Konstantin Ryabitsev wrote:
>>>>> +   This URL should be used when referring to relevant mailing list
>>>>> +   topics, related patch sets, or other notable discussion threads.
>>>>> +   A convenient way to associate ``Link:`` trailers with the commit
>>>>> +   message is to use markdown-like bracketed notation, for example::
>>>>> ...
>>>>> +     Link: https://lore.kernel.org/some-msgid@here # [1]
>>>>> +     Link: https://bugzilla.example.org/bug/12345  # [2]
>>>>
>>>> Why are we adding the extra "# " characters? The vast majority of
>>>> existing Link tags don't do this:
>>>
>>> That's just convention. In general, the hash separates the trailer from the
>>> comment:
>>>
>>>     Trailer-name: actual-trailer-body # comment
>>
>> Did we ever come to a conclusion on this?  This one character seems to
>> be the main source of disagreement in this series, I'm wondering if I
>> should just apply it and let the painting continue thereafter...?
> 
> We have used '#' for ages for adding comments to by: tags.
> I'm surprised that it's not documented.

I thought it was documented, but either I was wrong or can't find it.
But I found process/5.Posting.rst, which provides this example:

        Link: https://example.com/somewhere.html  optional-other-stuff

So no "# " there. So to avoid inconsistencies I guess this should not be
applied, unless that document is changed as well.

Ciao, Thorsten

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

[Randy Dunlap]

On 6/26/24 8:51 PM, Thorsten Leemhuis wrote:
> On 27.06.24 01:17, Randy Dunlap wrote:
>> On 6/26/24 4:13 PM, Jonathan Corbet wrote:
>>> Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:
>>>> On Fri, Jun 21, 2024 at 02:07:44PM GMT, Kees Cook wrote:
>>>>> On Wed, Jun 19, 2024 at 02:24:07PM -0400, Konstantin Ryabitsev wrote:
>>>>>> +   This URL should be used when referring to relevant mailing list
>>>>>> +   topics, related patch sets, or other notable discussion threads.
>>>>>> +   A convenient way to associate ``Link:`` trailers with the commit
>>>>>> +   message is to use markdown-like bracketed notation, for example::
>>>>>> ...
>>>>>> +     Link: https://lore.kernel.org/some-msgid@here # [1]
>>>>>> +     Link: https://bugzilla.example.org/bug/12345  # [2]
>>>>>
>>>>> Why are we adding the extra "# " characters? The vast majority of
>>>>> existing Link tags don't do this:
>>>>
>>>> That's just convention. In general, the hash separates the trailer from the
>>>> comment:
>>>>
>>>>     Trailer-name: actual-trailer-body # comment
>>>
>>> Did we ever come to a conclusion on this?  This one character seems to
>>> be the main source of disagreement in this series, I'm wondering if I
>>> should just apply it and let the painting continue thereafter...?
>>
>> We have used '#' for ages for adding comments to by: tags.
>> I'm surprised that it's not documented.
> 
> I thought it was documented, but either I was wrong or can't find it.
> But I found process/5.Posting.rst, which provides this example:
> 
>         Link: https://example.com/somewhere.html  optional-other-stuff
> 
> So no "# " there. So to avoid inconsistencies I guess this should not be
> applied, unless that document is changed as well.

In my use cases, other-optional-stuff begins with '#'.


-- 
~Randy

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

[Konstantin Ryabitsev]

On Thu, Jun 27, 2024 at 05:51:47AM GMT, Thorsten Leemhuis wrote:
> I thought it was documented, but either I was wrong or can't find it.
> But I found process/5.Posting.rst, which provides this example:
> 
>         Link: https://example.com/somewhere.html  optional-other-stuff
> 
> So no "# " there. So to avoid inconsistencies I guess this should not be
> applied, unless that document is changed as well.

This is inconsistent with every other trailer that includes comments.
Currently, there are two mechanisms to provide comments with trailers:

1:

    | Trailer-name: trailer-content # trailer-comment

2:

    | Trailer-name: trailer-content
    | [trailer-comment]

For the sake of consistency, all trailers, including Link, should use one of
these two mechanisms for "optional-other-stuff".

-K

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

[Steven Rostedt]

On Fri, 28 Jun 2024 10:52:37 -0400
Konstantin Ryabitsev <konstantin@linuxfoundation.org> wrote:

> On Thu, Jun 27, 2024 at 05:51:47AM GMT, Thorsten Leemhuis wrote:
> > I thought it was documented, but either I was wrong or can't find it.
> > But I found process/5.Posting.rst, which provides this example:
> > 
> >         Link: https://example.com/somewhere.html  optional-other-stuff
> > 
> > So no "# " there. So to avoid inconsistencies I guess this should not be
> > applied, unless that document is changed as well.  
> 
> This is inconsistent with every other trailer that includes comments.
> Currently, there are two mechanisms to provide comments with trailers:
> 
> 1:
> 
>     | Trailer-name: trailer-content # trailer-comment
> 
> 2:
> 
>     | Trailer-name: trailer-content
>     | [trailer-comment]

Where do you see that?

Whenever I do the second one, it has nothing to do with the tag, but
what I have done to the patch/commit.

    Signed-off-by: Random Developer <rdevelop@company.com>
    [ Fixed formatting ]
    Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>

That is, if I do any modification of the original submission, I
document it this way.

-- Steve


> 
> For the sake of consistency, all trailers, including Link, should use one of
> these two mechanisms for "optional-other-stuff".
> 
> -K

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

[Michael Ellerman]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:
> 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 | 30 ++++++++++++++++++++++--------
>  1 file changed, 22 insertions(+), 8 deletions(-)
>
> diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
> index 64739968afa6..ba312345d030 100644
> --- a/Documentation/process/maintainer-tip.rst
> +++ b/Documentation/process/maintainer-tip.rst
> @@ -372,17 +372,31 @@ following tag ordering scheme:
>  
>   - Link: ``https://link/to/information``
>  
> -   For referring to an email on LKML or other kernel mailing lists,
> -   please use the lore.kernel.org redirector URL::
> +   For referring to an email posted to the 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@here
>  
> -   The kernel.org redirector is considered a stable URL, unlike other email
> -   archives.
> +   This URL should be used when referring to relevant mailing list
> +   topics, related patch sets, or other notable discussion threads.
> +   A convenient way to associate ``Link:`` trailers with the commit
> +   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]

Does it actually make sense to use the Link: prefix here? These sort of
links are part of the prose, they're not something a script can download
and make any sense of.

I see some existing usage of the above style, but equally there's lots
of examples of footnote-style links without the Link: tag, eg:

commit 40b561e501768ef24673d0e1d731a7b9b1bc6709
Merge: d9f843fbd45e 31611cc8faa0
Author: Arnd Bergmann <arnd@arndb.de>
Date:   Mon Apr 29 22:29:44 2024 +0200

    Merge tag 'tee-ts-for-v6.10' of https://git.linaro.org/people/jens.wiklander/linux-tee into soc/drivers

    TEE driver for Trusted Services

    This introduces a TEE driver for Trusted Services [1].

    Trusted Services is a TrustedFirmware.org project that provides a
    framework for developing and deploying device Root of Trust services in
    FF-A [2] Secure Partitions. The project hosts the reference
    implementation of Arm Platform Security Architecture [3] for Arm
    A-profile devices.

    ...

    [1] https://www.trustedfirmware.org/projects/trusted-services/
    [2] https://developer.arm.com/documentation/den0077/
    [3] https://www.arm.com/architecture/security-features/platform-security


The above style is standard markdown style for reference links (or as
standard as markdown gets).

cheers

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

[Kees Cook]

On June 21, 2024 9:27:34 PM PDT, Michael Ellerman <mpe@ellerman.id.au> wrote:
>Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:
>> 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 | 30 ++++++++++++++++++++++--------
>>  1 file changed, 22 insertions(+), 8 deletions(-)
>>
>> diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
>> index 64739968afa6..ba312345d030 100644
>> --- a/Documentation/process/maintainer-tip.rst
>> +++ b/Documentation/process/maintainer-tip.rst
>> @@ -372,17 +372,31 @@ following tag ordering scheme:
>>  
>>   - Link: ``https://link/to/information``
>>  
>> -   For referring to an email on LKML or other kernel mailing lists,
>> -   please use the lore.kernel.org redirector URL::
>> +   For referring to an email posted to the 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@here
>>  
>> -   The kernel.org redirector is considered a stable URL, unlike other email
>> -   archives.
>> +   This URL should be used when referring to relevant mailing list
>> +   topics, related patch sets, or other notable discussion threads.
>> +   A convenient way to associate ``Link:`` trailers with the commit
>> +   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]
>
>Does it actually make sense to use the Link: prefix here? These sort of
>links are part of the prose, they're not something a script can download
>and make any sense of.
>
>I see some existing usage of the above style, but equally there's lots
>of examples of footnote-style links without the Link: tag, eg:

I moved from that to using Link: because checkpatch would complain about my long (URL) lines unless it had a Link tag :P

>commit 40b561e501768ef24673d0e1d731a7b9b1bc6709
>Merge: d9f843fbd45e 31611cc8faa0
>Author: Arnd Bergmann <arnd@arndb.de>
>Date:   Mon Apr 29 22:29:44 2024 +0200
>
>    Merge tag 'tee-ts-for-v6.10' of https://git.linaro.org/people/jens.wiklander/linux-tee into soc/drivers
>
>    TEE driver for Trusted Services
>
>    This introduces a TEE driver for Trusted Services [1].
>
>    Trusted Services is a TrustedFirmware.org project that provides a
>    framework for developing and deploying device Root of Trust services in
>    FF-A [2] Secure Partitions. The project hosts the reference
>    implementation of Arm Platform Security Architecture [3] for Arm
>    A-profile devices.
>
>    ...
>
>    [1] https://www.trustedfirmware.org/projects/trusted-services/
>    [2] https://developer.arm.com/documentation/den0077/
>    [3] https://www.arm.com/architecture/security-features/platform-security
>
>
>The above style is standard markdown style for reference links (or as
>standard as markdown gets).

It's a good point. If we're formalizing this, why not literally use markdown instead? (I guess the answer is that out-of-line links/footnotes isn't standardized.)

Playing devil's advocate, outside of the kernel, these are the two most common styles I've seen:

Foo[1]
...
[1]: https://....

and

Bar[^1]
...
[^1] https://...

Personally, I only want to have a single official way to do this, and don't care much what it is. I have a minor preference for what you've described:

Baz[1]
...
[1] https://...

-Kees

-- 
Kees Cook

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

[Randy Dunlap]

On 6/22/24 7:40 AM, Kees Cook wrote:
>> I see some existing usage of the above style, but equally there's lots
>> of examples of footnote-style links without the Link: tag, eg:
> I moved from that to using Link: because checkpatch would complain about my long (URL) lines unless it had a Link tag :P

We know that checkpatch isn't perfect. It's safe to ignore such complaints.

-- 
~Randy

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

[Carlos Bilbao]

On 6/19/24 13:24, Konstantin Ryabitsev wrote:

> 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>
> ---
> Changes in v2:
> - Minor wording changes to text and commit messages based on feedback.
> - Link to v1: https://lore.kernel.org/r/20240618-docs-patch-msgid-link-v1-0-30555f3f5ad4@linuxfoundation.org


I prefer 'origin'over 'provenance'as well. My Ack/R-b from version 1
still stands.

>
> ---
> 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     | 30 ++++++++++++++++++++--------
>  Documentation/process/submitting-patches.rst | 15 +++++---------
>  6 files changed, 40 insertions(+), 33 deletions(-)
> ---
> base-commit: 6ba59ff4227927d3a8530fc2973b80e94b54d58f
> change-id: 20240618-docs-patch-msgid-link-6961045516e0
>
> Best regards,


Thanks,
Carlos

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

[Steven Rostedt]

On Wed, 19 Jun 2024 14:24:05 -0400
Konstantin Ryabitsev <konstantin@linuxfoundation.org> wrote:

> - 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>
> ---
> Changes in v2:
> - Minor wording changes to text and commit messages based on feedback.
> - Link to v1: https://lore.kernel.org/r/20240618-docs-patch-msgid-link-v1-0-30555f3f5ad4@linuxfoundation.org

Should drop the '/r' ;-)

-- Steve

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

[Jonathan Corbet]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

> 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>
> ---
> Changes in v2:
> - Minor wording changes to text and commit messages based on feedback.
> - Link to v1: https://lore.kernel.org/r/20240618-docs-patch-msgid-link-v1-0-30555f3f5ad4@linuxfoundation.org
>
So I have gone ahead and applied this.  There are some important changes
here that shouldn't miss the merge window, and we can argue about the #
marking with it in-tree.

I am rather amused, though, that b4 added a few extra tag lines:

> Link: https://example.com/somewhere.html  optional-other-stuff
> Signed-off-by: Random Developer <rdevelop@company.com>
>      [ Fixed formatting ]
> Signed-off-by: Steven Rostedt (Google) <rostedt@goodmis.org>

I do believe I'll amend the changelog before pushing this one :)

Thanks,

jon