[PATCH v1 0/2] Prefer lore.kernel.org and explain Link: tags better

[PATCH v1 0/2] Prefer lore.kernel.org and explain Link: tags better

[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

Ciao, Thorsten

Thorsten Leemhuis (2):
  docs: use the lore redirector everywhere
  docs: submitting-patches: make section about the Link: tag more
    explicit

 Documentation/asm-annotations.rst             |  2 +-
 .../kbuild/Kconfig.recursion-issue-02         |  2 +-
 Documentation/maintainer/pull-requests.rst    |  2 +-
 Documentation/networking/msg_zerocopy.rst     |  2 +-
 Documentation/process/maintainer-tip.rst      |  4 +--
 Documentation/process/submitting-patches.rst  | 34 ++++++++++++-------
 .../it_IT/process/submitting-patches.rst      |  4 +--
 .../zh_CN/maintainer/pull-requests.rst        |  2 +-
 .../zh_CN/process/submitting-patches.rst      |  4 +--
 .../zh_TW/process/submitting-patches.rst      |  4 +--
 Documentation/x86/entry_64.rst                |  2 +-
 Documentation/x86/orc-unwinder.rst            |  4 +--
 12 files changed, 38 insertions(+), 28 deletions(-)


base-commit: b19511926cb50d59c57189739d03c21df325710f
-- 
2.31.1

[PATCH v1 1/2] docs: use the lore redirector everywhere

[Thorsten Leemhuis]

Change all links from using the lkml redirector to the lore redirector,
as the kernel.org admin recently indicated: we shouldn't be using
lkml.kernel.org anymore because the domain can create confusion, as it
indicates it is only valid for messages sent to the LKML; the convention
has been to use https://lore.kernel.org/r/msgid for this reason.

In this process also change three links from using http to https.

Link: https://lore.kernel.org/r/20211006170025.qw3glxvocczfuhar@meerkat.local
CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
CC: Thomas Gleixner <tglx@linutronix.de>
CC: Ingo Molnar <mingo@redhat.com>
CC: Borislav Petkov <bp@alien8.de>
CC: Hu Haowen <src.res@email.cn>
CC: Alex Shi <alexs@kernel.org>
CC: Federico Vaga <federico.vaga@vaga.pv.it>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/asm-annotations.rst                             | 2 +-
 Documentation/kbuild/Kconfig.recursion-issue-02               | 2 +-
 Documentation/maintainer/pull-requests.rst                    | 2 +-
 Documentation/networking/msg_zerocopy.rst                     | 2 +-
 Documentation/process/maintainer-tip.rst                      | 4 ++--
 Documentation/process/submitting-patches.rst                  | 4 ++--
 .../translations/it_IT/process/submitting-patches.rst         | 4 ++--
 Documentation/translations/zh_CN/maintainer/pull-requests.rst | 2 +-
 .../translations/zh_CN/process/submitting-patches.rst         | 4 ++--
 .../translations/zh_TW/process/submitting-patches.rst         | 4 ++--
 Documentation/x86/entry_64.rst                                | 2 +-
 Documentation/x86/orc-unwinder.rst                            | 4 ++--
 12 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/Documentation/asm-annotations.rst b/Documentation/asm-annotations.rst
index 76424e0431f4..f4bf0f6395fb 100644
--- a/Documentation/asm-annotations.rst
+++ b/Documentation/asm-annotations.rst
@@ -64,7 +64,7 @@ macros, it was decided that brand new macros should be introduced instead::
     of importing all the crappy, historic, essentially randomly chosen
     debug symbol macro names from the binutils and older kernels?
 
-.. _discussion: https://lkml.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz
+.. _discussion: https://lore.kernel.org/r/20170217104757.28588-1-jslaby@suse.cz
 
 Macros Description
 ------------------
diff --git a/Documentation/kbuild/Kconfig.recursion-issue-02 b/Documentation/kbuild/Kconfig.recursion-issue-02
index 0034eb494d11..09dcb92d9b43 100644
--- a/Documentation/kbuild/Kconfig.recursion-issue-02
+++ b/Documentation/kbuild/Kconfig.recursion-issue-02
@@ -42,7 +42,7 @@
 # "select FW_LOADER" [0], in the end the simple alternative solution to this
 # problem consisted on matching semantics with newly introduced features.
 #
-# [0] https://lkml.kernel.org/r/1432241149-8762-1-git-send-email-mcgrof@do-not-panic.com
+# [0] https://lore.kernel.org/r/1432241149-8762-1-git-send-email-mcgrof@do-not-panic.com
 
 mainmenu "Simple example to demo cumulative kconfig recursive dependency implication"
 
diff --git a/Documentation/maintainer/pull-requests.rst b/Documentation/maintainer/pull-requests.rst
index 1a2f99b67d25..e072de60ccb0 100644
--- a/Documentation/maintainer/pull-requests.rst
+++ b/Documentation/maintainer/pull-requests.rst
@@ -15,7 +15,7 @@ please direct abuse to Tobin C. Harding <me@tobin.cc>.
 
 Original email thread::
 
-	http://lkml.kernel.org/r/20171114110500.GA21175@kroah.com
+	https://lore.kernel.org/r/20171114110500.GA21175@kroah.com
 
 
 Create Branch
diff --git a/Documentation/networking/msg_zerocopy.rst b/Documentation/networking/msg_zerocopy.rst
index ace56204dd03..15920db8d35d 100644
--- a/Documentation/networking/msg_zerocopy.rst
+++ b/Documentation/networking/msg_zerocopy.rst
@@ -50,7 +50,7 @@ the excellent reporting over at LWN.net or read the original code.
 
   patchset
     [PATCH net-next v4 0/9] socket sendmsg MSG_ZEROCOPY
-    https://lkml.kernel.org/netdev/20170803202945.70750-1-willemdebruijn.kernel@gmail.com
+    https://lore.kernel.org/netdev/20170803202945.70750-1-willemdebruijn.kernel@gmail.com
 
 
 Interface
diff --git a/Documentation/process/maintainer-tip.rst b/Documentation/process/maintainer-tip.rst
index 2b495c8bcb5b..c74f4a81588b 100644
--- a/Documentation/process/maintainer-tip.rst
+++ b/Documentation/process/maintainer-tip.rst
@@ -371,9 +371,9 @@ following tag ordering scheme:
  - Link: ``https://link/to/information``
 
    For referring to an email on LKML or other kernel mailing lists,
-   please use the lkml.kernel.org redirector URL::
+   please use the lore.kernel.org redirector URL::
 
-     https://lkml.kernel.org/r/email-message@id
+     https://lore.kernel.org/r/email-message@id
 
    The kernel.org redirector is considered a stable URL, unlike other email
    archives.
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 21125d299ce6..b0f31aa82fcd 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -98,7 +98,7 @@ 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/
+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.
 
@@ -750,7 +750,7 @@ the bug report.  However, for a multi-patch series, it is generally
 best to avoid using In-Reply-To: to link to older versions of the
 series.  This way multiple versions of the patch don't become an
 unmanageable forest of references in email clients.  If a link is
-helpful, you can use the https://lkml.kernel.org/ redirector (e.g., in
+helpful, you can use the https://lore.kernel.org/ redirector (e.g., in
 the cover email text) to link to an earlier version of the patch series.
 
 
diff --git a/Documentation/translations/it_IT/process/submitting-patches.rst b/Documentation/translations/it_IT/process/submitting-patches.rst
index 458d9d24b9c0..c2fb712a1377 100644
--- a/Documentation/translations/it_IT/process/submitting-patches.rst
+++ b/Documentation/translations/it_IT/process/submitting-patches.rst
@@ -107,7 +107,7 @@ comportamento.
 Se la patch corregge un baco conosciuto, fare riferimento a quel baco inserendo
 il suo numero o il suo URL.  Se la patch è la conseguenza di una discussione
 su una lista di discussione, allora fornite l'URL all'archivio di quella
-discussione;  usate i collegamenti a https://lkml.kernel.org/ con il
+discussione;  usate i collegamenti a https://lore.kernel.org/ con il
 ``Message-Id``, in questo modo vi assicurerete che il collegamento non diventi
 invalido nel tempo.
 
@@ -772,7 +772,7 @@ che lo riportava.  Tuttavia, per serie di patch multiple è generalmente
 sconsigliato l'uso di In-Reply-To: per collegare precedenti versioni.
 In questo modo versioni multiple di una patch non diventeranno un'ingestibile
 giungla di riferimenti all'interno dei programmi di posta.  Se un collegamento
-è utile, potete usare https://lkml.kernel.org/ per ottenere i collegamenti
+è utile, potete usare https://lore.kernel.org/ per ottenere i collegamenti
 ad una versione precedente di una serie di patch (per esempio, potete usarlo
 per l'email introduttiva alla serie).
 
diff --git a/Documentation/translations/zh_CN/maintainer/pull-requests.rst b/Documentation/translations/zh_CN/maintainer/pull-requests.rst
index f46d6f3f2498..ce9725f4674c 100644
--- a/Documentation/translations/zh_CN/maintainer/pull-requests.rst
+++ b/Documentation/translations/zh_CN/maintainer/pull-requests.rst
@@ -21,7 +21,7 @@ Harding <me@tobin.cc>。
 
 原始邮件线程::
 
-	http://lkml.kernel.org/r/20171114110500.GA21175@kroah.com
+	https://lore.kernel.org/r/20171114110500.GA21175@kroah.com
 
 
 创建分支
diff --git a/Documentation/translations/zh_CN/process/submitting-patches.rst b/Documentation/translations/zh_CN/process/submitting-patches.rst
index 3296b8f7bedf..3f1683cd4727 100644
--- a/Documentation/translations/zh_CN/process/submitting-patches.rst
+++ b/Documentation/translations/zh_CN/process/submitting-patches.rst
@@ -133,7 +133,7 @@ xyzzy do frotz”或“[I]changed xyzzy to do frotz”，就好像你在命令
 
 如果修补程序修复了一个记录的bug条目，请按编号和URL引用该bug条目。如果补丁来
 自邮件列表讨论，请给出邮件列表存档的URL；使用带有 ``Message-ID`` 的
-https://lkml.kernel.org/ 重定向，以确保链接不会过时。
+https://lore.kernel.org/ 重定向，以确保链接不会过时。
 
 但是，在没有外部资源的情况下，尽量让你的解释可理解。除了提供邮件列表存档或
 bug的URL之外，还要总结需要提交补丁的相关讨论要点。
@@ -599,7 +599,7 @@ e-mail 标题中的“一句话概述”扼要的描述 e-mail 中的补丁。
 将补丁与以前的相关讨论关联起来，例如，将bug修复程序链接到电子邮件和bug报告。
 但是，对于多补丁系列，最好避免在回复时使用链接到该系列的旧版本。这样，
 补丁的多个版本就不会成为电子邮件客户端中无法管理的引用序列。如果链接有用，
-可以使用 https://lkml.kernel.org/ 重定向器（例如，在封面电子邮件文本中）
+可以使用 https://lore.kernel.org/ 重定向器（例如，在封面电子邮件文本中）
 链接到补丁系列的早期版本。
 
 16) 发送git pull请求
diff --git a/Documentation/translations/zh_TW/process/submitting-patches.rst b/Documentation/translations/zh_TW/process/submitting-patches.rst
index cdf0b52e4a98..37eccf9e2746 100644
--- a/Documentation/translations/zh_TW/process/submitting-patches.rst
+++ b/Documentation/translations/zh_TW/process/submitting-patches.rst
@@ -136,7 +136,7 @@ xyzzy do frotz」或「[我]changed xyzzy to do frotz」，就好像你在命令
 
 如果修補程序修復了一個記錄的bug條目，請按編號和URL引用該bug條目。如果補丁來
 自郵件列表討論，請給出郵件列表存檔的URL；使用帶有 ``Message-ID`` 的
-https://lkml.kernel.org/ 重定向，以確保連結不會過時。
+https://lore.kernel.org/ 重定向，以確保連結不會過時。
 
 但是，在沒有外部資源的情況下，儘量讓你的解釋可理解。除了提供郵件列表存檔或
 bug的URL之外，還要總結需要提交補丁的相關討論要點。
@@ -602,7 +602,7 @@ e-mail 標題中的「一句話概述」扼要的描述 e-mail 中的補丁。
 將補丁與以前的相關討論關聯起來，例如，將bug修復程序連結到電子郵件和bug報告。
 但是，對於多補丁系列，最好避免在回復時使用連結到該系列的舊版本。這樣，
 補丁的多個版本就不會成爲電子郵件客戶端中無法管理的引用序列。如果連結有用，
-可以使用 https://lkml.kernel.org/ 重定向器（例如，在封面電子郵件文本中）
+可以使用 https://lore.kernel.org/ 重定向器（例如，在封面電子郵件文本中）
 連結到補丁系列的早期版本。
 
 16) 發送git pull請求
diff --git a/Documentation/x86/entry_64.rst b/Documentation/x86/entry_64.rst
index a48b3f6ebbe8..e433e08f7018 100644
--- a/Documentation/x86/entry_64.rst
+++ b/Documentation/x86/entry_64.rst
@@ -8,7 +8,7 @@ This file documents some of the kernel entries in
 arch/x86/entry/entry_64.S.  A lot of this explanation is adapted from
 an email from Ingo Molnar:
 
-http://lkml.kernel.org/r/<20110529191055.GC9835%40elte.hu>
+https://lore.kernel.org/r/20110529191055.GC9835%40elte.hu
 
 The x86 architecture has quite a few different ways to jump into
 kernel code.  Most of these entry points are registered in
diff --git a/Documentation/x86/orc-unwinder.rst b/Documentation/x86/orc-unwinder.rst
index d811576c1f3e..9a66a88be765 100644
--- a/Documentation/x86/orc-unwinder.rst
+++ b/Documentation/x86/orc-unwinder.rst
@@ -177,6 +177,6 @@ brutal, unyielding efficiency.
 ORC stands for Oops Rewind Capability.
 
 
-.. [1] https://lkml.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de
-.. [2] https://lkml.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz
+.. [1] https://lore.kernel.org/r/20170602104048.jkkzssljsompjdwy@suse.de
+.. [2] https://lore.kernel.org/r/d2ca5435-6386-29b8-db87-7f227c2b713a@suse.cz
 .. [3] http://dustin.wikidot.com/half-orcs-and-orcs
-- 
2.31.1

[PATCH v1 2/2] 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, 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 <konstantin@linuxfoundation.org>
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
---
 Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
 1 file changed, 21 insertions(+), 11 deletions(-)

diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index b0f31aa82fcd..8ba69332322f 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,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/git-send-email.555-1234@example.org
+
+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 v1 2/2] docs: submitting-patches: make section about the Link: tag more explicit

[Jani Nikula]

On Thu, 07 Oct 2021, Thorsten Leemhuis <linux@leemhuis.info> wrote:
> 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.

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. It gets automatically added by the tooling we use while applying
patches. You get to the discussion, patch series, and Intel CI test
results via the link.

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

BR,
Jani.

>
> CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
> ---
>  Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
>  1 file changed, 21 insertions(+), 11 deletions(-)
>
> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
> index b0f31aa82fcd..8ba69332322f 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,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/git-send-email.555-1234@example.org
> +
> +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

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH v1 0/2] Prefer lore.kernel.org and explain Link: tags better

[Konstantin Ryabitsev]

On Thu, Oct 07, 2021 at 10:04:59AM +0200, Thorsten Leemhuis wrote:
> 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

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

Thanks,
-K

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

[Thorsten Leemhuis]

(sorry, sending it a second time, vger rejected it earlier - and I have
an idea now what went wrong)

On 07.10.21 11:31, Jani Nikula wrote:
> On Thu, 07 Oct 2021, Thorsten Leemhuis <linux@leemhuis.info> wrote:
>> 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.
>
> 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.

> 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/20210922205525.570068-1-nathan@kernel.org
```

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


>> CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
>> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
>> ---
>>  Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
>>  1 file changed, 21 insertions(+), 11 deletions(-)
>>
>> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
>> index b0f31aa82fcd..8ba69332322f 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,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/git-send-email.555-1234@example.org
>> +
>> +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
> 

Re: [PATCH v1 0/2] Prefer lore.kernel.org and explain Link: tags better

[Jonathan Corbet]

Thorsten Leemhuis <linux@leemhuis.info> writes:

> 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

OK, I've applied this one, thanks.

>   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.

Thanks,

jon

Re: [PATCH v1 0/2] Prefer lore.kernel.org and explain Link: tags better

[Thorsten Leemhuis]

[sorry, once again I have to sent it a second time, as vger rejected it;
thunderbird once again messed for some reason used
"Content-Transfer-Encoding: 7bit" then it should have used 8bit; I tried
to track this down by sending mails to myself, but then it sets 8bit
correctly when needed :-/ ]

On 12.10.21 22:03, Jonathan Corbet wrote:
> Thorsten Leemhuis <linux@leemhuis.info> writes:
> 
>> 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
> 
> OK, I've applied this one, thanks.

Thx!

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

Yeah, totally fine.

> 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.

Well, that is already explained in
Documentation/maintainer/configure-git.rst afaics -- which is the better
place afaics, as that is something maintainers should do, and not
something people should do when submitting a patch.

Ciao, Thorsten

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

[Thorsten Leemhuis]

On 08.10.21 11:47, Thorsten Leemhuis wrote:
> On 07.10.21 11:31, Jani Nikula wrote:
>> On Thu, 07 Oct 2021, Thorsten Leemhuis <linux@leemhuis.info> wrote:
>>> 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.
>>
>> 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.
> 
>> 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/20210922205525.570068-1-nathan@kernel.org
> ```
> 
> 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...

> 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

> 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
> 
> 
>>> CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
>>> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
>>> ---
>>>  Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
>>>  1 file changed, 21 insertions(+), 11 deletions(-)
>>>
>>> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
>>> index b0f31aa82fcd..8ba69332322f 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,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/git-send-email.555-1234@example.org
>>> +
>>> +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
>>
> 

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

[Jani Nikula]

On Thu, 21 Oct 2021, Thorsten Leemhuis <linux@leemhuis.info> wrote:
> On 08.10.21 11:47, Thorsten Leemhuis wrote:
>> On 07.10.21 11:31, Jani Nikula wrote:
>>> On Thu, 07 Oct 2021, Thorsten Leemhuis <linux@leemhuis.info> wrote:
>>>> 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.
>>>
>>> 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.
>> 
>>> 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/20210922205525.570068-1-nathan@kernel.org
>> ```
>> 
>> 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".
> ```

Discussion about a patch *after* it was committed will likely happen in
the mailing list thread where the patch was posted. So kind of what we
do with Link.

> 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.

Fair enough.

I think the main thing to accept is that while we may add kernel wide
guidance, we'll end up with different subsystems and drivers having
varying conventions no matter what.

> FWIW, I'll...
>
>> 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.

That is going to be one massive bikeshed fest. :|

BR,
Jani.

>
> Ciao, Thorsten
>
>> 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
>> 
>> 
>>>> CC: Konstantin Ryabitsev <konstantin@linuxfoundation.org>
>>>> Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
>>>> ---
>>>>  Documentation/process/submitting-patches.rst | 32 +++++++++++++-------
>>>>  1 file changed, 21 insertions(+), 11 deletions(-)
>>>>
>>>> diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
>>>> index b0f31aa82fcd..8ba69332322f 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,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/git-send-email.555-1234@example.org
>>>> +
>>>> +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
>>>
>> 

-- 
Jani Nikula, Intel Open Source Graphics Center