Thread (17 messages) 17 messages, 10 authors, 2024-06-26

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

From: Leon Romanovsky <leon@kernel.org>
Date: 2024-06-19 07:12:57
Also in: linux-doc, lkml, workflows

On Tue, Jun 18, 2024 at 12:42:11PM -0400, Konstantin Ryabitsev wrote:
quoted hunk ↗ jump to hunk
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 <redacted>
---
 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
Keyboard shortcuts
hback out one level
jnext message in thread
kprevious message in thread
ldrill in
Escclose help / fold thread tree
?toggle this help