Mention the 'Link' tag in the section about adding URLs to the commit
msg, which makes it easier to find their meaning with a text search. For
the same reason and to improve comprehensibility also 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 not jump back and forth
between aspects relevant for the top and the bottom part of the commit
msg.
Signed-off-by: Thorsten Leemhuis <[email protected]>
---
Lo! The regression tracking bot I'm working on can automatically mark
entries as resolved, if a commit message uses a 'Link' tag to the
report. Many developers already add them, but it afaics would improve
matters to make this more explicit. Especially as I had missed the
section about it myself at first, as I simply grepped for 'Link:' and
only found an explanation in configure-git.rst.
Konstantin, let me known if I should do a
s!lkml.kernel.org/r/!lore.kernel.org/r/! at the same time. If it is a
good idea, I'll prepare a second patch that does this here and other
places refering to lkml.kernel.org/r/ in a similar fashion.
Ciao, Thorsten
---
Documentation/process/submitting-patches.rst | 26 +++++++++++---------
1 file changed, 15 insertions(+), 11 deletions(-)
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 21125d299ce6..0318a8e1dcd6 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://lkml.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,21 @@ 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 follows from a mailing list
+discussion, point to it. When linking to mailing list archives, use the
+https://lkml.kernel.org/r/ redirector with a ``Message-Id``, to ensure
+that the links cannot become stale. These tags should look like this::
+
+ Link: https://lkml.kernel.org/r/<message-id>
+
+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
base-commit: b19511926cb50d59c57189739d03c21df325710f
--
2.31.1
On Wed, Oct 06, 2021 at 06:37:38PM +0200, Thorsten Leemhuis wrote:
> +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 follows from a mailing list
> +discussion, point to it. When linking to mailing list archives, use the
> +https://lkml.kernel.org/r/ redirector with a ``Message-Id``, to ensure
We shouldn't be using "lkml.kernel.org" because that domain name can create
confusion that this is only valid for messages sent to "the LKML"
([email protected]). The convention has been to use
https://lore.kernel.org/r/msgid for this reason. I would also reword that a
bit:
... or a bug tracker; if the patch was discussed on a mailing list, you
may point to it using the lore.kernel.org message archiver service. To
create the link URL, use the contents of the ``Message-Id`` header of the
patch 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.
-K
On 06.10.21 19:00, Konstantin Ryabitsev wrote:
> On Wed, Oct 06, 2021 at 06:37:38PM +0200, Thorsten Leemhuis wrote:
>> +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 follows from a mailing list
>> +discussion, point to it. When linking to mailing list archives, use the
>> +https://lkml.kernel.org/r/ redirector with a ``Message-Id``, to ensure
>
> We shouldn't be using "lkml.kernel.org" because that domain name can create
> confusion that this is only valid for messages sent to "the LKML"
> ([email protected]). The convention has been to use
> https://lore.kernel.org/r/msgid for this reason. I would also reword that a
> bit:
>
> ... or a bug tracker; if the patch was discussed on a mailing list, you
> may point to it using the lore.kernel.org message archiver service. To
> create the link URL, use the contents of the ``Message-Id`` header of the
> patch 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.
Thx, feedback like this was exactly why I CCed you. So I'll do what I
outlined in my earlier mail already: prepare a patch that first does a
s!lkml.kernel.org!lore.kernel.org! in everywhere in Documentation/ where
it makes sense.
Ciao, Thorsten