| Message ID | 20240618-docs-patch-msgid-link-v1-2-30555f3f5ad4@linuxfoundation.org (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | Documentation: update information for mailing lists | expand |
| Context | Check | Description |
|---|---|---|
| netdev/tree_selection | success | Not a local patch |
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
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
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 >
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.
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 > >
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
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
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
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
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. >
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
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
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.
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(-)