The regressions handling manual claims that regzbot associates patches
fixing an issue with the report based on the occurrence of the
appropriate "Link:" trailers. It reasons that this does not add any
burden on the maintainers/bug fix authors as this is already mandated by
the "Submitting patches" guide. In fact however, the guide encourages
using "Link:" tags for related discussions or issues which the patch
fixes only partially, recommending "Closes:" for full resolutions.

Despite it not being mentioned anywhere in the "Handling regressions"
guide, regzbot does in fact take the "Closes:" tags into account and
seems to in fact treat them fully equivalently to "Link:" tags.

Clarify this in the regressions handling guide by always mentioning both
of the tags.

Signed-off-by: Karel Balej <balejk@matfyz.cz>
---
 .../process/handling-regressions.rst          | 30 ++++++++++---------
 1 file changed, 16 insertions(+), 14 deletions(-)

diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst
index 49ba1410cfce..b9f8c8aa5936 100644
--- a/Documentation/process/handling-regressions.rst
+++ b/Documentation/process/handling-regressions.rst
@@ -40,9 +40,9 @@ The important bits (aka "The TL;DR")
        #regzbot from: Some N. Ice Human <some.human@example.com>
        #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789
 
-#. When submitting fixes for regressions, add "Link:" tags to the patch
-   description pointing to all places where the issue was reported, as
-   mandated by Documentation/process/submitting-patches.rst and
+#. When submitting fixes for regressions, add "Closes:" (or "Link:") tags to
+   the patch description pointing to all places where the issue was reported,
+   as mandated by Documentation/process/submitting-patches.rst and
    :ref:`Documentation/process/5.Posting.rst <development_posting>`.
 
 #. Try to fix regressions quickly once the culprit has been identified; fixes
@@ -91,8 +91,8 @@ When doing either, consider making the Linux kernel regression tracking bot
    Note the caret (^) before the "introduced": it tells regzbot to treat the
    parent mail (the one you reply to) as the initial report for the regression
    you want to see tracked; that's important, as regzbot will later look out
-   for patches with "Link:" tags pointing to the report in the archives on
-   lore.kernel.org.
+   for patches with "Closes:" or "Link:" tags pointing to the report in the
+   archives on lore.kernel.org.
 
  * When forwarding a regressions reported to a bug tracker, include a paragraph
    with these regzbot commands::
@@ -102,7 +102,8 @@ When doing either, consider making the Linux kernel regression tracking bot
        #regzbot monitor: http://some.bugtracker.example.com/ticket?id=123456789
 
    Regzbot will then automatically associate patches with the report that
-   contain "Link:" tags pointing to your mail or the mentioned ticket.
+   contain "Closes:" or "Link:" tags pointing to your mail or the mentioned
+   ticket.
 
 What's important when fixing regressions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -112,7 +113,8 @@ remember to do what Documentation/process/submitting-patches.rst,
 :ref:`Documentation/process/5.Posting.rst <development_posting>`, and
 Documentation/process/stable-kernel-rules.rst already explain in more detail:
 
- * Point to all places where the issue was reported using "Link:" tags::
+ * Point to all places where the issue was reported using "Closes:" or "Link:"
+   tags::
 
        Link: https://lore.kernel.org/r/30th.anniversary.repost@klaava.Helsinki.FI/
        Link: https://bugzilla.kernel.org/show_bug.cgi?id=1234567890
@@ -126,8 +128,8 @@ All this is expected from you and important when it comes to regression, as
 these tags are of great value for everyone (you included) that might be looking
 into the issue weeks, months, or years later. These tags are also crucial for
 tools and scripts used by other kernel developers or Linux distributions; one of
-these tools is regzbot, which heavily relies on the "Link:" tags to associate
-reports for regression with changes resolving them.
+these tools is regzbot, which heavily relies on the "Closes:" and "Link:" tags
+to associate reports for regression with changes resolving them.
 
 Expectations and best practices for fixing regressions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -326,9 +328,9 @@ How does regression tracking work with regzbot?
 
 The bot watches for replies to reports of tracked regressions. Additionally,
 it's looking out for posted or committed patches referencing such reports
-with "Link:" tags; replies to such patch postings are tracked as well.
-Combined this data provides good insights into the current state of the fixing
-process.
+with "Closes:" or "Link:" tags; replies to such patch postings are tracked as
+well. Combined this data provides good insights into the current state of the
+fixing process.
 
 Regzbot tries to do its job with as little overhead as possible for both
 reporters and developers. In fact, only reporters are burdened with an extra
@@ -338,8 +340,8 @@ take care of that using ``#regzbot ^introduced``.
 
 For developers there normally is no extra work involved, they just need to make
 sure to do something that was expected long before regzbot came to light: add
-"Link:" tags to the patch description pointing to all reports about the issue
-fixed.
+"Closes:" (or "Link:") tags to the patch description pointing to all reports
+about the issue fixed.
 
 Do I have to use regzbot?
 ~~~~~~~~~~~~~~~~~~~~~~~~~
-- 
2.44.0

On 28.03.24 20:29, Karel Balej wrote:
> The regressions handling manual claims that regzbot associates patches
> fixing an issue with the report based on the occurrence of the
> appropriate "Link:" trailers. It reasons that this does not add any
> burden on the maintainers/bug fix authors as this is already mandated by
> the "Submitting patches" guide. In fact however, the guide encourages
> using "Link:" tags for related discussions or issues which the patch
> fixes only partially, recommending "Closes:" for full resolutions.
> 
> Despite it not being mentioned anywhere in the "Handling regressions"
> guide, regzbot does in fact take the "Closes:" tags into account and
> seems to in fact treat them fully equivalently to "Link:" tags.
> 
> Clarify this in the regressions handling guide by always mentioning both
> of the tags.

Many thx for this and the other patch. I had planned to do something
like this myself, but never got around to.

There is just one thing that makes me slightly unhappy: this tells
readers that they can use both, but leaves the question "what's the
difference" respectively "in which situation should I use one or the
other" unanswered.

To answer that question: in a ideal world developers would use "Closes:"
when a change resolves an issue, and "Link" when it's somehow related to
a report, but not resolving the problem.

But we don't live in that world and I wonder if we ever reach that point
where regzbot could act accordingly. Nevertheless I'd say it would be
wise to write the docs towards that ideal world. E.g.: tell developers
to uses 'Closes:', but in some places briefly hint that "'Link:' works
for now, too".

I also find the patch description a bit verbose; and it would be good to
turn the text upside down: first outline what the patch, then maybe
describe the "why".

Ciao, Thorsten

On 4/1/24 1:38 AM, Thorsten Leemhuis wrote:
> On 28.03.24 20:29, Karel Balej wrote:
>> The regressions handling manual claims that regzbot associates patches
>> fixing an issue with the report based on the occurrence of the
>> appropriate "Link:" trailers. It reasons that this does not add any
>> burden on the maintainers/bug fix authors as this is already mandated by
>> the "Submitting patches" guide. In fact however, the guide encourages
>> using "Link:" tags for related discussions or issues which the patch
>> fixes only partially, recommending "Closes:" for full resolutions.
>>
>> Despite it not being mentioned anywhere in the "Handling regressions"
>> guide, regzbot does in fact take the "Closes:" tags into account and
>> seems to in fact treat them fully equivalently to "Link:" tags.
>>
>> Clarify this in the regressions handling guide by always mentioning both
>> of the tags.
> 
> Many thx for this and the other patch. I had planned to do something
> like this myself, but never got around to.
> 
> There is just one thing that makes me slightly unhappy: this tells
> readers that they can use both, but leaves the question "what's the
> difference" respectively "in which situation should I use one or the
> other" unanswered.
> 
> To answer that question: in a ideal world developers would use "Closes:"
> when a change resolves an issue, and "Link" when it's somehow related to
> a report, but not resolving the problem.

I use Link: when I fix only part of an LKP report and Closes: when I fix
all of one.

> But we don't live in that world and I wonder if we ever reach that point
> where regzbot could act accordingly. Nevertheless I'd say it would be
> wise to write the docs towards that ideal world. E.g.: tell developers
> to uses 'Closes:', but in some places briefly hint that "'Link:' works
> for now, too".

I don't see Link: going away any time in the "near" future.

> I also find the patch description a bit verbose; and it would be good to
> turn the text upside down: first outline what the patch, then maybe
> describe the "why".

It's almost amusing that you find something verbose.  ;)

-- 
#Randy

On 01.04.24 17:19, Randy Dunlap wrote:
> On 4/1/24 1:38 AM, Thorsten Leemhuis wrote:
>> On 28.03.24 20:29, Karel Balej wrote:
>>> The regressions handling manual claims that regzbot associates patches
>>> fixing an issue with the report based on the occurrence of the
>>> appropriate "Link:" trailers. It reasons that this does not add any
>>> burden on the maintainers/bug fix authors as this is already mandated by
>>> the "Submitting patches" guide. In fact however, the guide encourages
>>> using "Link:" tags for related discussions or issues which the patch
>>> fixes only partially, recommending "Closes:" for full resolutions.
>>>
>>> Despite it not being mentioned anywhere in the "Handling regressions"
>>> guide, regzbot does in fact take the "Closes:" tags into account and
>>> seems to in fact treat them fully equivalently to "Link:" tags.
>>>
>>> Clarify this in the regressions handling guide by always mentioning both
>>> of the tags.
>>
>> Many thx for this and the other patch. I had planned to do something
>> like this myself, but never got around to.
>>
>> There is just one thing that makes me slightly unhappy: this tells
>> readers that they can use both, but leaves the question "what's the
>> difference" respectively "in which situation should I use one or the
>> other" unanswered.
>>
>> To answer that question: in a ideal world developers would use "Closes:"
>> when a change resolves an issue, and "Link" when it's somehow related to
>> a report, but not resolving the problem.
> 
> I use Link: when I fix only part of an LKP report and Closes: when I fix
> all of one.

Yup.

>> But we don't live in that world and I wonder if we ever reach that point
>> where regzbot could act accordingly. Nevertheless I'd say it would be
>> wise to write the docs towards that ideal world. E.g.: tell developers
>> to uses 'Closes:', but in some places briefly hint that "'Link:' works
>> for now, too".
> 
> I don't see Link: going away any time in the "near" future.

Sure, I didn't mean to imply that! Just in the scope of the document and
the sections where the tag is mentioned I think (but it would be good to
recheck) it's always about a "resolving a reported regression", so
Closes there makes more sense. But yeah, might be wise to spell that all
out.

Karel: if I'm asking too much here, I could pick up your patches and
improve upon them to handle this. Or we simply wait until two other
regzbot features are in place, then I could fix this as part of some
other changes.

>> I also find the patch description a bit verbose; and it would be good to
>> turn the text upside down: first outline what the patch, then maybe
>> describe the "why".
> It's almost amusing that you find something verbose.  ;)

:-D

I often wonder what the main reason for that verbosity it. That I used
to write for a mainstream computer magazine? Or that English is a second
language to me? Whatever.

Ciao, Thorsten

Thorsten,

thank you very much for your feedback.

Thorsten Leemhuis, 2024-04-02T11:27:57+02:00:
> On 01.04.24 17:19, Randy Dunlap wrote:
> > On 4/1/24 1:38 AM, Thorsten Leemhuis wrote:
> >> On 28.03.24 20:29, Karel Balej wrote:
> >>> The regressions handling manual claims that regzbot associates patches
> >>> fixing an issue with the report based on the occurrence of the
> >>> appropriate "Link:" trailers. It reasons that this does not add any
> >>> burden on the maintainers/bug fix authors as this is already mandated by
> >>> the "Submitting patches" guide. In fact however, the guide encourages
> >>> using "Link:" tags for related discussions or issues which the patch
> >>> fixes only partially, recommending "Closes:" for full resolutions.
> >>>
> >>> Despite it not being mentioned anywhere in the "Handling regressions"
> >>> guide, regzbot does in fact take the "Closes:" tags into account and
> >>> seems to in fact treat them fully equivalently to "Link:" tags.
> >>>
> >>> Clarify this in the regressions handling guide by always mentioning both
> >>> of the tags.
> >>
> >> Many thx for this and the other patch. I had planned to do something
> >> like this myself, but never got around to.
> >>
> >> There is just one thing that makes me slightly unhappy: this tells
> >> readers that they can use both, but leaves the question "what's the
> >> difference" respectively "in which situation should I use one or the
> >> other" unanswered.

I see your point and I agree. I have perceived something similar when
editing the document: I wondered whether it's really good to *always*
spell out both variants or whether it would perhaps be enough in some
places only.

I think the way that I ultimately did it counts on the reader being
familiar with the "Submitting patches" document and knowing the "true"
meanings of both Closes: and Link: and when to use each. So my goal was
only to mention it because the way it was written seemed to almost imply
to me that Closes: does *not* work and is thus not recommended which
seemed in conflict with the "Submitting patch" guide, which was even
more confusing since it literally referred to it.

In other words, it wasn't actually my goal to answer that question you
pose, because that is already answered in the other document.

I also didn't want to be too drastic with the changes because the
prevalence of Link: seemed so strong that I thought that I must be
missing something and that you have a good reason to write it like this.
So I wanted to stay safe :-)

Anyway, if you are OK with that, I can definitely change it to Closes:
everywhere and only mention Link: marginally, saying that it works too
and explaining the difference while referring the reader to "Submitting
patches" for more information (not that there would be too much more on
this subject).

> Just in the scope of the document and the sections where the tag is
> mentioned I think (but it would be good to recheck) it's always about
> a "resolving a reported regression", so Closes there makes more sense.

Exactly.

> Karel: if I'm asking too much here, I could pick up your patches and
> improve upon them to handle this. Or we simply wait until two other
> regzbot features are in place, then I could fix this as part of some
> other changes.

Not at all, I will be happy to make the changes, if you don't mind that
it might take me some time, but I would definitely get around to it
eventually.

Of course I wouldn't want to for example delay you so if you get around
to it sooner than I will then feel free to make the changes either as a
modification of this patch or just on its own.

Perhaps you could take the first patch already if you have no
reservations there and I will then just send v2 of this one?

> >> I also find the patch description a bit verbose; and it would be
> >> good to turn the text upside down: first outline what the patch,
> >> then maybe describe the "why".

I actually probably like it more this way. After all, the outline (or
"what") is the patch subject, everything that comes after it in the body
is usually meant to explain "why". But sure, I can swap it if you want
:-)

As for the verbosity, I will keep it in mind when working on v2,
although I also generally don't consider verbosity a bad thing. I might
have been too verbose, though, because as I have mentioned, I was
confused why it isn't like this already and wanted to offer my full
reasoning so that I could be shown where I err :-)

One more thing that I wanted but ultimately forgot to mention in the
cover letter: thank you very much for writing these guides in the first
place, I find them very instructive and useful.

Kind regards,
K. B.

On 02.04.24 12:13, Karel Balej wrote:
> thank you very much for your feedback.

yw!

> Thorsten Leemhuis, 2024-04-02T11:27:57+02:00:
>> On 01.04.24 17:19, Randy Dunlap wrote:
>>> On 4/1/24 1:38 AM, Thorsten Leemhuis wrote:
>>>> On 28.03.24 20:29, Karel Balej wrote:
>>>>> The regressions handling manual claims that regzbot associates patches
>>>>> fixing an issue with the report based on the occurrence of the
>>>>> appropriate "Link:" trailers. It reasons that this does not add any
>>>>> burden on the maintainers/bug fix authors as this is already mandated by
>>>>> the "Submitting patches" guide. In fact however, the guide encourages
>>>>> using "Link:" tags for related discussions or issues which the patch
>>>>> fixes only partially, recommending "Closes:" for full resolutions.
>>>>>
>>>>> Despite it not being mentioned anywhere in the "Handling regressions"
>>>>> guide, regzbot does in fact take the "Closes:" tags into account and
>>>>> seems to in fact treat them fully equivalently to "Link:" tags.
>>>>>
>>>>> Clarify this in the regressions handling guide by always mentioning both
>>>>> of the tags.
>>>>
>>>> Many thx for this and the other patch. I had planned to do something
>>>> like this myself, but never got around to.
>>>>
>>>> There is just one thing that makes me slightly unhappy: this tells
>>>> readers that they can use both, but leaves the question "what's the
>>>> difference" respectively "in which situation should I use one or the
>>>> other" unanswered.
> 
> I see your point and I agree. I have perceived something similar when
> editing the document: I wondered whether it's really good to *always*
> spell out both variants or whether it would perhaps be enough in some
> places only.
> 
> I think the way that I ultimately did it counts on the reader being
> familiar with the "Submitting patches" document and knowing the "true"
> meanings of both Closes: and Link: and when to use each. So my goal was
> only to mention it because the way it was written seemed to almost imply
> to me that Closes: does *not* work and is thus not recommended which
> seemed in conflict with the "Submitting patch" guide, which was even
> more confusing since it literally referred to it.
> 
> In other words, it wasn't actually my goal to answer that question you
> pose, because that is already answered in the other document.

Yeah, but documents ideally should work on their own, so offering two
solutions without at least hinting at the differences is not ideal.

> I also didn't want to be too drastic with the changes because the
> prevalence of Link: seemed so strong that I thought that I must be
> missing something and that you have a good reason to write it like this.

Just history: when that document was written we didn't have a "Closes"
tag yet.

> So I wanted to stay safe :-)

:-)

> Anyway, if you are OK with that, I can definitely change it to Closes:
> everywhere and only mention Link: marginally, saying that it works too
> and explaining the difference while referring the reader to "Submitting
> patches" for more information (not that there would be too much more on
> this subject).

Yeah. Maybe just write something along the lines of "using a 'Link:' tag
instead  works for now as well, as some subsystems prefer it over the
younger 'Closes:' tag" somewhere -- while using Closes: everywhere else.

> Of course I wouldn't want to for example delay you so if you get around
> to it sooner than I will then feel free to make the changes either as a
> modification of this patch or just on its own.

I doubt that will happen.

> Perhaps you could take the first patch already if you have no
> reservations there and I will then just send v2 of this one?

I'll send a reviewed-by for that, but I guess Jonathan will take that
for the next merge window anyway. So there is still some time to prepare
a updated series with both changes. And if time is running out, we can
still ask Jonathan to pick up the first patch.

>>>> I also find the patch description a bit verbose; and it would be
>>>> good to turn the text upside down: first outline what the patch,
>>>> then maybe describe the "why".
> 
> I actually probably like it more this way. After all, the outline (or
> "what") is the patch subject, everything that comes after it in the body
> is usually meant to explain "why". But sure, I can swap it if you want
> :-)

Well, imagine you have to read 25 shorts text that each explain the
"why" first and then the "what" while you only care about one certain
change. Then your preferred approach quickly becomes annoying, because
you have to read a lot of "why" for every patch before you can decide if
you actually care about it.

> As for the verbosity, I will keep it in mind when working on v2,
> although I also generally don't consider verbosity a bad thing. I might
> have been too verbose, though, because as I have mentioned, I was
> confused why it isn't like this already and wanted to offer my full
> reasoning so that I could be shown where I err :-)

:-)

> One more thing that I wanted but ultimately forgot to mention in the
> cover letter: thank you very much for writing these guides in the first
> place, I find them very instructive and useful.

Thx for saying that, I often wonder if they are really worth the trouble...

Ciao, Thosten