Prefer lore.kernel.org and explain Link: tags better

Mention the 'Link' tag in the section about adding URLs to the commit msg, which makes it easier to find its meaning with a text search. For the same reason and to also improve comprehensibility provide an example.

Slightly improve the text at the same time to make it more obvious developers are meant to add links to issue reports in mailing list archives, as those allow regression tracking efforts to automatically check which bugs got resolved.

Move the section also downwards slightly, to reduce jumping back and forth between aspects relevant for the top and the bottom part of the commit msg.

CC Konstantin Ryabitsev <[email protected]>

Signed-off-by Thorsten Leemhuis <[email protected]>

---
 Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
 1 file changed, 21 insertions(+), 11 deletions(-)

Documentation/process/submitting-patches.rst +21 -11

index b0f31aa82fcd..8ba69332322f 100644
@@ -96,17 +96,6 @@ instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
 to do frotz", as if you are giving orders to the codebase to change
 its behaviour.
 
-If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL.  If the patch follows from a mailing list discussion,
-give a URL to the mailing list archive; use the https://lore.kernel.org/
-redirector with a ``Message-Id``, to ensure that the links cannot become
-stale.
-
-However, try to make your explanation understandable without external
-resources.  In addition to giving a URL to a mailing list archive or
-bug, summarize the relevant points of the discussion that led to the
-patch as submitted.
-
 If you want to refer to a specific commit, don't just refer to the
 SHA-1 ID of the commit. Please also include the oneline summary of
 the commit, to make it easier for reviewers to know what it is about.

@@ -123,6 +112,27 @@ collisions with shorter IDs a real possibility.  Bear in mind that, even if
 there is no collision with your six-character ID now, that condition may
 change five years from now.
 
+Add 'Link:' tags with URLs pointing to related discussions and rationale
+behind the change whenever that makes sense. If your patch for example
+fixes a bug, add a tag with a URL referencing the report in the mailing
+list archives or a bug tracker; if the patch was discussed on a mailing
+list or originated in some discussion, 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.
+For example::
+
+    Link: https://lore.kernel.org/r/[email protected]
+
+Please check the link to make sure that it is actually working and points
+to the relevant message.
+
+However, try to make your explanation understandable without external
+resources.  In addition to giving a URL to a mailing list archive or
+bug, summarize the relevant points of the discussion that led to the
+patch as submitted.
+
 If your patch fixes a bug in a specific commit, e.g. you found an issue using
 ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
 the SHA-1 ID, and the one line summary.  Do not split the tag across multiple

Quoted 5 lines · Thorsten Leemhuis

Mention the 'Link' tag in the section about adding URLs to the commit msg, which makes it easier to find its meaning with a text search. For the same reason and to also improve comprehensibility provide an example.

Quoted 8 lines

Slightly improve the text at the same time to make it more obvious developers are meant to add links to issue reports in mailing list archives, as those allow regression tracking efforts to automatically check which bugs got resolved.

Move the section also downwards slightly, to reduce jumping back and forth between aspects relevant for the top and the bottom part of the commit msg.

FWIW, we've been using the Link: tag in the drm-misc and drm-intel trees to reference the patch (that became the commit) in the freedesktop.org patchwork instance by message-id. This is almost exclusively the only way we use the Link: tag, and we've been doing this for about 5 years now. [...]

For ages, References: tag has been used the way described in this patch.

Quoted 56 lines

CC Konstantin Ryabitsev <[email protected]>

Signed-off-by Thorsten Leemhuis <[email protected]>

---
 Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
 1 file changed, 21 insertions(+), 11 deletions(-)

Documentation/process/submitting-patches.rst +21 -11

index b0f31aa82fcd..8ba69332322f 100644
@@ -96,17 +96,6 @@ instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
 to do frotz", as if you are giving orders to the codebase to change
 its behaviour.
 
-If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL.  If the patch follows from a mailing list discussion,
-give a URL to the mailing list archive; use the https://lore.kernel.org/
-redirector with a ``Message-Id``, to ensure that the links cannot become
-stale.
-
-However, try to make your explanation understandable without external
-resources.  In addition to giving a URL to a mailing list archive or
-bug, summarize the relevant points of the discussion that led to the
-patch as submitted.
-
 If you want to refer to a specific commit, don't just refer to the
 SHA-1 ID of the commit. Please also include the oneline summary of
 the commit, to make it easier for reviewers to know what it is about.

@@ -123,6 +112,27 @@ collisions with shorter IDs a real possibility.  Bear in mind that, even if
 there is no collision with your six-character ID now, that condition may
 change five years from now.
 
+Add 'Link:' tags with URLs pointing to related discussions and rationale
+behind the change whenever that makes sense. If your patch for example
+fixes a bug, add a tag with a URL referencing the report in the mailing
+list archives or a bug tracker; if the patch was discussed on a mailing
+list or originated in some discussion, 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.
+For example::
+
+    Link: https://lore.kernel.org/r/[email protected]
+
+Please check the link to make sure that it is actually working and points
+to the relevant message.
+
+However, try to make your explanation understandable without external
+resources.  In addition to giving a URL to a mailing list archive or
+bug, summarize the relevant points of the discussion that led to the
+patch as submitted.
+
 If your patch fixes a bug in a specific commit, e.g. you found an issue using
 ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
 the SHA-1 ID, and the one line summary.  Do not split the tag across multiple

Quoted 15 lines · Jani Nikula

Quoted 5 lines · Thorsten Leemhuis

Mention the 'Link' tag in the section about adding URLs to the commit msg, which makes it easier to find its meaning with a text search. For the same reason and to also improve comprehensibility provide an example.

Quoted 8 lines

Slightly improve the text at the same time to make it more obvious developers are meant to add links to issue reports in mailing list archives, as those allow regression tracking efforts to automatically check which bugs got resolved.

Move the section also downwards slightly, to reduce jumping back and forth between aspects relevant for the top and the bottom part of the commit msg.

Quoted 5 lines

FWIW, we've been using the Link: tag in the drm-misc and drm-intel trees to reference the patch (that became the commit) in the freedesktop.org patchwork instance by message-id. This is almost exclusively the only way we use the Link: tag, and we've been doing this for about 5 years now. [...]

Which afaik is totally appropriate and the way it is used most of the time, especially since more and more maintainers use b4.

But it afaics also gets used to refer to bug reports:

$ git log v5.14.. | grep ' Link: https://bugzilla.kernel.org/' | wc -
8

But maybe that's not the way it is intended.

Quoted 1 line

For ages, References: tag has been used the way described in this patch.

Hmmm, seems other developers/subsystems handle that tag a bit different as well. I simply looked for "References:" in v5.14.. (excluding drm) and for example found the following in
https://git.kernel.org/torvalds/c/19532869feb9b0a97d17ddc14609d1e53a5b60db

```
>     Link: https://github.com/ClangBuiltLinux/linux/issues/1453
>     References: 6baec880d7a5 ("kasan: turn off asan-stack for clang-8 and earlier")
>     Link: https://lkml.kernel.org/r/[email protected]
```

This commit uses "References:" in a similar way:
https://git.kernel.org/torvalds/c/13be2efc390acd2a46a69a359f6efc00ca434599

Maybe it's time to generate a table with the "official tags" (and create separate tags for the different purposes at the same time as well?).

Wasn't something like that a topic in the past? My mind vaguely recalls a lwn.net article about tags and their misuse, but I couldn't find it. And maybe my mind is mixing things up anyway and remembers something that never happened. :-/

Ciao, Thorsten

Quoted 57 lines

Quoted 56 lines

CC Konstantin Ryabitsev <[email protected]>

Signed-off-by Thorsten Leemhuis <[email protected]>

---
 Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
 1 file changed, 21 insertions(+), 11 deletions(-)

Documentation/process/submitting-patches.rst +21 -11

index b0f31aa82fcd..8ba69332322f 100644
@@ -96,17 +96,6 @@ instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
 to do frotz", as if you are giving orders to the codebase to change
 its behaviour.
 
-If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL.  If the patch follows from a mailing list discussion,
-give a URL to the mailing list archive; use the https://lore.kernel.org/
-redirector with a ``Message-Id``, to ensure that the links cannot become
-stale.
-
-However, try to make your explanation understandable without external
-resources.  In addition to giving a URL to a mailing list archive or
-bug, summarize the relevant points of the discussion that led to the
-patch as submitted.
-
 If you want to refer to a specific commit, don't just refer to the
 SHA-1 ID of the commit. Please also include the oneline summary of
 the commit, to make it easier for reviewers to know what it is about.

@@ -123,6 +112,27 @@ collisions with shorter IDs a real possibility.  Bear in mind that, even if
 there is no collision with your six-character ID now, that condition may
 change five years from now.
 
+Add 'Link:' tags with URLs pointing to related discussions and rationale
+behind the change whenever that makes sense. If your patch for example
+fixes a bug, add a tag with a URL referencing the report in the mailing
+list archives or a bug tracker; if the patch was discussed on a mailing
+list or originated in some discussion, 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.
+For example::
+
+    Link: https://lore.kernel.org/r/[email protected]
+
+Please check the link to make sure that it is actually working and points
+to the relevant message.
+
+However, try to make your explanation understandable without external
+resources.  In addition to giving a URL to a mailing list archive or
+bug, summarize the relevant points of the discussion that led to the
+patch as submitted.
+
 If your patch fixes a bug in a specific commit, e.g. you found an issue using
 ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
 the SHA-1 ID, and the one line summary.  Do not split the tag across multiple

Quoted 39 lines · Thorsten Leemhuis

Quoted 15 lines · Jani Nikula

Quoted 5 lines · Thorsten Leemhuis

Mention the 'Link' tag in the section about adding URLs to the commit msg, which makes it easier to find its meaning with a text search. For the same reason and to also improve comprehensibility provide an example.

Quoted 8 lines

Slightly improve the text at the same time to make it more obvious developers are meant to add links to issue reports in mailing list archives, as those allow regression tracking efforts to automatically check which bugs got resolved.

Move the section also downwards slightly, to reduce jumping back and forth between aspects relevant for the top and the bottom part of the commit msg.

Quoted 5 lines

FWIW, we've been using the Link: tag in the drm-misc and drm-intel trees to reference the patch (that became the commit) in the freedesktop.org patchwork instance by message-id. This is almost exclusively the only way we use the Link: tag, and we've been doing this for about 5 years now. [...]

Which afaik is totally appropriate and the way it is used most of the time, especially since more and more maintainers use b4.

But it afaics also gets used to refer to bug reports:

$ git log v5.14.. | grep ' Link: https://bugzilla.kernel.org/' | wc -
8

But maybe that's not the way it is intended.

Quoted 1 line

For ages, References: tag has been used the way described in this patch.

Hmmm, seems other developers/subsystems handle that tag a bit different as well. I simply looked for "References:" in v5.14.. (excluding drm) and for example found the following in
https://git.kernel.org/torvalds/c/19532869feb9b0a97d17ddc14609d1e53a5b60db

Quoted 8 lines

```
>     Link: https://github.com/ClangBuiltLinux/linux/issues/1453
>     References: 6baec880d7a5 ("kasan: turn off asan-stack for clang-8 and earlier")
>     Link: https://lkml.kernel.org/r/[email protected]
```

This commit uses "References:" in a similar way:
https://git.kernel.org/torvalds/c/13be2efc390acd2a46a69a359f6efc00ca434599

FWIW, Linus today coincidentally in
https://lore.kernel.org/lkml/CAHk-=wgBhyLhQLPem1vybKNt7BKP+=qF=veBgc7VirZaXn4FUw@mail.gmail.com/
wrote:

```
So _primarily_ the "Link:" line should be about background - and for
"oh, there was discussion about this patch after it was committed".
```

I'd consider a bug/regression report as "background", so from my point of view I'd say what my patch does is correct. Or do you disagree Jani? If not I'd like to move on and ask Jonathan to merge it.

FWIW, I'll...

Quoted 2 lines

Maybe it's time to generate a table with the "official tags" (and create separate tags for the different purposes at the same time as well?).

...keep this in mind to maybe get back to it sooner or later.

Ciao, Thorsten

Quoted 66 lines

Wasn't something like that a topic in the past? My mind vaguely recalls a lwn.net article about tags and their misuse, but I couldn't find it. And maybe my mind is mixing things up anyway and remembers something that never happened. :-/

Ciao, Thorsten

Quoted 57 lines

Quoted 56 lines

CC Konstantin Ryabitsev <[email protected]>

Signed-off-by Thorsten Leemhuis <[email protected]>

---
 Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
 1 file changed, 21 insertions(+), 11 deletions(-)

Documentation/process/submitting-patches.rst +21 -11

index b0f31aa82fcd..8ba69332322f 100644
@@ -96,17 +96,6 @@ instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy
 to do frotz", as if you are giving orders to the codebase to change
 its behaviour.
 
-If the patch fixes a logged bug entry, refer to that bug entry by
-number and URL.  If the patch follows from a mailing list discussion,
-give a URL to the mailing list archive; use the https://lore.kernel.org/
-redirector with a ``Message-Id``, to ensure that the links cannot become
-stale.
-
-However, try to make your explanation understandable without external
-resources.  In addition to giving a URL to a mailing list archive or
-bug, summarize the relevant points of the discussion that led to the
-patch as submitted.
-
 If you want to refer to a specific commit, don't just refer to the
 SHA-1 ID of the commit. Please also include the oneline summary of
 the commit, to make it easier for reviewers to know what it is about.

@@ -123,6 +112,27 @@ collisions with shorter IDs a real possibility.  Bear in mind that, even if
 there is no collision with your six-character ID now, that condition may
 change five years from now.
 
+Add 'Link:' tags with URLs pointing to related discussions and rationale
+behind the change whenever that makes sense. If your patch for example
+fixes a bug, add a tag with a URL referencing the report in the mailing
+list archives or a bug tracker; if the patch was discussed on a mailing
+list or originated in some discussion, 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.
+For example::
+
+    Link: https://lore.kernel.org/r/[email protected]
+
+Please check the link to make sure that it is actually working and points
+to the relevant message.
+
+However, try to make your explanation understandable without external
+resources.  In addition to giving a URL to a mailing list archive or
+bug, summarize the relevant points of the discussion that led to the
+patch as submitted.
+
 If your patch fixes a bug in a specific commit, e.g. you found an issue using
 ``git bisect``, please use the 'Fixes:' tag with the first 12 characters of
 the SHA-1 ID, and the one line summary.  Do not split the tag across multiple

v2:
- slightly reword after suggestiones from Konstantin (thx!)
- make this a patch series with an preparatory patch that does s!lkml.kernel.org!lore.kernel.org! everywhere in the docs

Lo! The regression tracking bot I'm working on can automatically mark an entry as resolved, if the commit message of the fix uses a 'Link' tag to the report. Many developers already place them, but it afaics would improve matters to make this more explicit. Especially as I had missed the modified section myself at first, as I simply grepped for 'Link:' and only found an explanation in configure-git.rst.

Konstantin after posting v1 suggested to use lore.kernel.org instead or lkml.kernel.org, which made me add a patch to realize this everywhere in the docs.

v2:
- slightly reword after suggestiones from Konstantin (thx!)
- make this a patch series with an preparatory patch that does s!lkml.kernel.org!lore.kernel.org! everywhere in the docs

v1: https://lore.kernel.org/r/7dff33afec555fed0bf033c910ca59f9f19f22f1.1633537634.git.linux@leemhuis.info/
- initial version

Ciao, Thorsten

Thorsten Leemhuis (2):
docs: use the lore redirector everywhere

docs: submitting-patches: make section about the Link: tag more
explicit

Quoted 19 lines · Thorsten Leemhuis

Lo! The regression tracking bot I'm working on can automatically mark an entry as resolved, if the commit message of the fix uses a 'Link' tag to the report. Many developers already place them, but it afaics would improve matters to make this more explicit. Especially as I had missed the modified section myself at first, as I simply grepped for 'Link:' and only found an explanation in configure-git.rst.

Konstantin after posting v1 suggested to use lore.kernel.org instead or lkml.kernel.org, which made me add a patch to realize this everywhere in the docs.

v2:
- slightly reword after suggestiones from Konstantin (thx!)
- make this a patch series with an preparatory patch that does s!lkml.kernel.org!lore.kernel.org! everywhere in the docs

v1: https://lore.kernel.org/r/7dff33afec555fed0bf033c910ca59f9f19f22f1.1633537634.git.linux@leemhuis.info/
- initial version

Quoted 4 lines

Ciao, Thorsten

Thorsten Leemhuis (2):
docs: use the lore redirector everywhere

OK, I've applied this one, thanks.

Quoted 2 lines

docs: submitting-patches: make section about the Link: tag more
explicit

There was a comment on this one, so I've not (yet) applied it.

FWIW, I, too, have the Link: tags put in automatically when I apply a patch, as Jani described; it's a simple hook in .git/hooks/applypatch-msg. That seems worth mentioning here more than instructions on how to construct the link - I doubt many people do it manually.