[PATCH v3 0/1] docs: improve when and how to use Link: tags

[PATCH v3 0/1] docs: improve when and how to use Link: tags

[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 trouble
finding the explanation myself at first, as I simply grepped for 'Link:'
and only found an explanation in configure-git.rst. But that only covers
how maintainers should use it to make git automatically add links to the
patch review in the archives.

v3:
- drop the first patch (merged)
- slightly improve the text again due to the questions raised during the
  review (that's also why I didn't pick up Konstantin's 'reviewed-by' on
  v2) and something Linus meanwhile said coincidentally

v2: https://lore.kernel.org/r/cover.1633593385.git.linux@leemhuis.info/
- 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

Thorsten Leemhuis (1):
  docs: submitting-patches: make section about the Link: tag more
    explicit

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


base-commit: 2df9f7f57905e61cf638284bf86af30f7849ed6b
-- 
2.31.1

[PATCH v3 1/1] docs: submitting-patches: make section about the Link: tag more explicit

[Thorsten Leemhuis]

Mention the 'Link' tag in the section about adding URLs to the commit
msg, to make it clearer they "_primarily_ [...] should be about
background", as Linus recently stated (see the link below). That makes
the explanation also easier to find with a text search. For the same
reason and to improve comprehensibility provide an example, too.

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.

Link: https://lore.kernel.org/lkml/CAHk-=wgBhyLhQLPem1vybKNt7BKP+=qF=veBgc7VirZaXn4FUw@mail.gmail.com/
CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/process/submitting-patches.rst | 33 +++++++++++++-------
 1 file changed, 22 insertions(+), 11 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index b0f31aa82fcd..cbe9ddbe2775 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -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,28 @@ 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.
 
+If related discussions or any other background information behind the change
+can be found on the web, add 'Link:' tags pointing to it. In case 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 is a result of some
+earlier mailing list discussion or something documented on the 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.
+For example::
+
+    Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
+
+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
-- 
2.31.1

Re: [PATCH v3 1/1] docs: submitting-patches: make section about the Link: tag more explicit

[Konstantin Ryabitsev]

On Mon, Oct 25, 2021 at 11:06:35AM +0200, Thorsten Leemhuis wrote:
> +If related discussions or any other background information behind the change
> +can be found on the web, add 'Link:' tags pointing to it. In case 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 is a result of some
> +earlier mailing list discussion or something documented on the web, point to
> +it.

The "for example" is splitting the sentence awkwardly, so I would move it to
the beginning of the sentence:

"For example, in case your patch fixes a bug, add ..." etc

Otherwise,

Reviewed-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

-K

Re: [PATCH v3 1/1] docs: submitting-patches: make section about the Link: tag more explicit

[Jonathan Corbet]

Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:

> On Mon, Oct 25, 2021 at 11:06:35AM +0200, Thorsten Leemhuis wrote:
>> +If related discussions or any other background information behind the change
>> +can be found on the web, add 'Link:' tags pointing to it. In case 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 is a result of some
>> +earlier mailing list discussion or something documented on the web, point to
>> +it.
>
> The "for example" is splitting the sentence awkwardly, so I would move it to
> the beginning of the sentence:
>
> "For example, in case your patch fixes a bug, add ..." etc
>
> Otherwise,
>
> Reviewed-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

I tweaked things along these lines and applied the patch, thanks.

jon

Re: [PATCH v3 1/1] docs: submitting-patches: make section about the Link: tag more explicit

[Thorsten Leemhuis]

On 26.10.21 17:49, Jonathan Corbet wrote:
> Konstantin Ryabitsev <konstantin@linuxfoundation.org> writes:
> 
>> On Mon, Oct 25, 2021 at 11:06:35AM +0200, Thorsten Leemhuis wrote:
>>> +If related discussions or any other background information behind the change
>>> +can be found on the web, add 'Link:' tags pointing to it. In case 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 is a result of some
>>> +earlier mailing list discussion or something documented on the web, point to
>>> +it.
>>
>> The "for example" is splitting the sentence awkwardly, so I would move it to
>> the beginning of the sentence:
>>
>> "For example, in case your patch fixes a bug, add ..." etc
>>
>> Otherwise,
>>
>> Reviewed-by: Konstantin Ryabitsev <konstantin@linuxfoundation.org>

BTW: thx, Konstantin, good idea.

> I tweaked things along these lines and applied the patch, thanks.

Great, many thx Jon!

Ciao, Thorsten