From: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
To: Jonathan Corbet <corbet@lwn.net>,
Carlos Bilbao <carlos.bilbao.osdev@gmail.com>,
"David S. Miller" <davem@davemloft.net>,
Eric Dumazet <edumazet@google.com>,
Jakub Kicinski <kuba@kernel.org>,
Paolo Abeni <pabeni@redhat.com>
Cc: workflows@vger.kernel.org, linux-doc@vger.kernel.org,
linux-kernel@vger.kernel.org, netdev@vger.kernel.org,
Konstantin Ryabitsev <konstantin@linuxfoundation.org>,
ksummit@lists.linux.dev
Subject: [PATCH v2 2/2] Documentation: best practices for using Link trailers
Date: Wed, 19 Jun 2024 14:24:07 -0400 [thread overview]
Message-ID: <20240619-docs-patch-msgid-link-v2-2-72dd272bfe37@linuxfoundation.org> (raw)
In-Reply-To: <20240619-docs-patch-msgid-link-v2-0-72dd272bfe37@linuxfoundation.org>
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
next prev parent reply other threads:[~2024-06-19 18:24 UTC|newest]
Thread overview: 18+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-06-19 18:24 [PATCH v2 0/2] Documentation: update information for mailing lists Konstantin Ryabitsev
2024-06-19 18:24 ` [PATCH v2 1/2] Documentation: fix links to mailing list services Konstantin Ryabitsev
2024-06-19 18:24 ` Konstantin Ryabitsev [this message]
2024-06-21 10:34 ` [PATCH v2 2/2] Documentation: best practices for using Link trailers Michael S. Tsirkin
2024-06-21 21:07 ` Kees Cook
2024-06-21 21:37 ` Konstantin Ryabitsev
2024-06-26 23:13 ` Jonathan Corbet
2024-06-26 23:17 ` Randy Dunlap
2024-06-27 3:51 ` Thorsten Leemhuis
2024-06-27 4:24 ` Randy Dunlap
2024-06-28 14:52 ` Konstantin Ryabitsev
2024-06-28 18:32 ` Steven Rostedt
2024-06-22 4:27 ` Michael Ellerman
2024-06-22 14:40 ` Kees Cook
2024-06-22 15:15 ` Randy Dunlap
2024-06-22 20:13 ` [PATCH v2 0/2] Documentation: update information for mailing lists Carlos Bilbao
2024-07-02 20:47 ` Steven Rostedt
2024-07-03 23:04 ` Jonathan Corbet
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240619-docs-patch-msgid-link-v2-2-72dd272bfe37@linuxfoundation.org \
--to=konstantin@linuxfoundation.org \
--cc=carlos.bilbao.osdev@gmail.com \
--cc=corbet@lwn.net \
--cc=davem@davemloft.net \
--cc=edumazet@google.com \
--cc=ksummit@lists.linux.dev \
--cc=kuba@kernel.org \
--cc=linux-doc@vger.kernel.org \
--cc=linux-kernel@vger.kernel.org \
--cc=netdev@vger.kernel.org \
--cc=pabeni@redhat.com \
--cc=workflows@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.