* [PATCH 0/2] regressions documentation improvements @ 2024-03-28 19:29 Karel Balej 2024-03-28 19:29 ` [PATCH 1/2] docs: *-regressions.rst: unify quoting, add missing word Karel Balej 2024-03-28 19:29 ` [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too Karel Balej 0 siblings, 2 replies; 10+ messages in thread From: Karel Balej @ 2024-03-28 19:29 UTC (permalink / raw) To: Thorsten Leemhuis, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows Cc: balejk Hello, this small series suggests two (hopefully) improvements for the regressions-related documentation texts. The first one is perhaps unnecessarily nitpicky but if nothing else, it at least adds a missing word. The other one tries to clarify for future readers a question which was on my mind through the whole process during my first attempt at reporting a regression. Please take a look, I am eager to hear what you think. Thank you, kind regards, K. B. Karel Balej (2): docs: *-regressions.rst: unify quoting, add missing word docs: handling-regressions.rst: clarify that "Closes:" tags work too .../admin-guide/reporting-regressions.rst | 10 +++--- .../process/handling-regressions.rst | 32 ++++++++++--------- 2 files changed, 22 insertions(+), 20 deletions(-) -- 2.44.0 ^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH 1/2] docs: *-regressions.rst: unify quoting, add missing word 2024-03-28 19:29 [PATCH 0/2] regressions documentation improvements Karel Balej @ 2024-03-28 19:29 ` Karel Balej 2024-04-03 14:13 ` Linux regression tracking (Thorsten Leemhuis) 2024-03-28 19:29 ` [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too Karel Balej 1 sibling, 1 reply; 10+ messages in thread From: Karel Balej @ 2024-03-28 19:29 UTC (permalink / raw) To: Thorsten Leemhuis, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows Cc: balejk Quoting of the '"no regressions" rule' expression differs between occurrences, sometimes being presented as '"no regressions rule"'. Unify the quoting using the first form which seems semantically correct or is at least used dominantly, albeit marginally. One of the occurrences is obviously missing the 'rule' part -- add it. Signed-off-by: Karel Balej <balejk@matfyz.cz> --- Documentation/admin-guide/reporting-regressions.rst | 10 +++++----- Documentation/process/handling-regressions.rst | 2 +- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/Documentation/admin-guide/reporting-regressions.rst b/Documentation/admin-guide/reporting-regressions.rst index 76b246ecf21b..946518355a2c 100644 --- a/Documentation/admin-guide/reporting-regressions.rst +++ b/Documentation/admin-guide/reporting-regressions.rst @@ -42,12 +42,12 @@ The important basics -------------------- -What is a "regression" and what is the "no regressions rule"? +What is a "regression" and what is the "no regressions" rule? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ It's a regression if some application or practical use case running fine with one Linux kernel works worse or not at all with a newer version compiled using a -similar configuration. The "no regressions rule" forbids this to take place; if +similar configuration. The "no regressions" rule forbids this to take place; if it happens by accident, developers that caused it are expected to quickly fix the issue. @@ -173,7 +173,7 @@ Additional details about regressions ------------------------------------ -What is the goal of the "no regressions rule"? +What is the goal of the "no regressions" rule? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Users should feel safe when updating kernel versions and not have to worry @@ -199,8 +199,8 @@ Exceptions to this rule are extremely rare; in the past developers almost always turned out to be wrong when they assumed a particular situation was warranting an exception. -Who ensures the "no regressions" is actually followed? -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +Who ensures the "no regressions" rule is actually followed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The subsystem maintainers should take care of that, which are watched and supported by the tree maintainers -- e.g. Linus Torvalds for mainline and diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst index ce6753a674f3..49ba1410cfce 100644 --- a/Documentation/process/handling-regressions.rst +++ b/Documentation/process/handling-regressions.rst @@ -284,7 +284,7 @@ What else is there to known about regressions? Check out Documentation/admin-guide/reporting-regressions.rst, it covers a lot of other aspects you want might want to be aware of: - * the purpose of the "no regressions rule" + * the purpose of the "no regressions" rule * what issues actually qualify as regression -- 2.44.0 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH 1/2] docs: *-regressions.rst: unify quoting, add missing word 2024-03-28 19:29 ` [PATCH 1/2] docs: *-regressions.rst: unify quoting, add missing word Karel Balej @ 2024-04-03 14:13 ` Linux regression tracking (Thorsten Leemhuis) 2024-04-10 21:03 ` Jonathan Corbet 0 siblings, 1 reply; 10+ messages in thread From: Linux regression tracking (Thorsten Leemhuis) @ 2024-04-03 14:13 UTC (permalink / raw) To: Karel Balej, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows On 28.03.24 20:29, Karel Balej wrote: > Quoting of the '"no regressions" rule' expression differs between > occurrences, sometimes being presented as '"no regressions rule"'. Unify > the quoting using the first form which seems semantically correct or is > at least used dominantly, albeit marginally. > > One of the occurrences is obviously missing the 'rule' part -- add it. > > Signed-off-by: Karel Balej <balejk@matfyz.cz> Thx for this: Reviewed-by: Thorsten Leemhuis <linux@leemhuis.info> Ciao, Thorsten > --- > Documentation/admin-guide/reporting-regressions.rst | 10 +++++----- > Documentation/process/handling-regressions.rst | 2 +- > 2 files changed, 6 insertions(+), 6 deletions(-) > > diff --git a/Documentation/admin-guide/reporting-regressions.rst b/Documentation/admin-guide/reporting-regressions.rst > index 76b246ecf21b..946518355a2c 100644 > --- a/Documentation/admin-guide/reporting-regressions.rst > +++ b/Documentation/admin-guide/reporting-regressions.rst > @@ -42,12 +42,12 @@ The important basics > -------------------- > > > -What is a "regression" and what is the "no regressions rule"? > +What is a "regression" and what is the "no regressions" rule? > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > It's a regression if some application or practical use case running fine with > one Linux kernel works worse or not at all with a newer version compiled using a > -similar configuration. The "no regressions rule" forbids this to take place; if > +similar configuration. The "no regressions" rule forbids this to take place; if > it happens by accident, developers that caused it are expected to quickly fix > the issue. > > @@ -173,7 +173,7 @@ Additional details about regressions > ------------------------------------ > > > -What is the goal of the "no regressions rule"? > +What is the goal of the "no regressions" rule? > ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > Users should feel safe when updating kernel versions and not have to worry > @@ -199,8 +199,8 @@ Exceptions to this rule are extremely rare; in the past developers almost always > turned out to be wrong when they assumed a particular situation was warranting > an exception. > > -Who ensures the "no regressions" is actually followed? > -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > +Who ensures the "no regressions" rule is actually followed? > +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ > > The subsystem maintainers should take care of that, which are watched and > supported by the tree maintainers -- e.g. Linus Torvalds for mainline and > diff --git a/Documentation/process/handling-regressions.rst b/Documentation/process/handling-regressions.rst > index ce6753a674f3..49ba1410cfce 100644 > --- a/Documentation/process/handling-regressions.rst > +++ b/Documentation/process/handling-regressions.rst > @@ -284,7 +284,7 @@ What else is there to known about regressions? > Check out Documentation/admin-guide/reporting-regressions.rst, it covers a lot > of other aspects you want might want to be aware of: > > - * the purpose of the "no regressions rule" > + * the purpose of the "no regressions" rule > > * what issues actually qualify as regression > ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 1/2] docs: *-regressions.rst: unify quoting, add missing word 2024-04-03 14:13 ` Linux regression tracking (Thorsten Leemhuis) @ 2024-04-10 21:03 ` Jonathan Corbet 0 siblings, 0 replies; 10+ messages in thread From: Jonathan Corbet @ 2024-04-10 21:03 UTC (permalink / raw) To: Linux regression tracking (Thorsten Leemhuis), Karel Balej, regressions, linux-doc, linux-kernel, workflows "Linux regression tracking (Thorsten Leemhuis)" <regressions@leemhuis.info> writes: > On 28.03.24 20:29, Karel Balej wrote: >> Quoting of the '"no regressions" rule' expression differs between >> occurrences, sometimes being presented as '"no regressions rule"'. Unify >> the quoting using the first form which seems semantically correct or is >> at least used dominantly, albeit marginally. >> >> One of the occurrences is obviously missing the 'rule' part -- add it. >> >> Signed-off-by: Karel Balej <balejk@matfyz.cz> > > Thx for this: > > Reviewed-by: Thorsten Leemhuis <linux@leemhuis.info> I've applied this patch; part 2, it seems, is subject to further work so I have not applied that one. Thanks, jon ^ permalink raw reply [flat|nested] 10+ messages in thread
* [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too 2024-03-28 19:29 [PATCH 0/2] regressions documentation improvements Karel Balej 2024-03-28 19:29 ` [PATCH 1/2] docs: *-regressions.rst: unify quoting, add missing word Karel Balej @ 2024-03-28 19:29 ` Karel Balej 2024-04-01 8:38 ` Thorsten Leemhuis 1 sibling, 1 reply; 10+ messages in thread From: Karel Balej @ 2024-03-28 19:29 UTC (permalink / raw) To: Thorsten Leemhuis, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows Cc: balejk 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 ^ permalink raw reply related [flat|nested] 10+ messages in thread
* Re: [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too 2024-03-28 19:29 ` [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too Karel Balej @ 2024-04-01 8:38 ` Thorsten Leemhuis 2024-04-01 15:19 ` Randy Dunlap 0 siblings, 1 reply; 10+ messages in thread From: Thorsten Leemhuis @ 2024-04-01 8:38 UTC (permalink / raw) To: Karel Balej, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too 2024-04-01 8:38 ` Thorsten Leemhuis @ 2024-04-01 15:19 ` Randy Dunlap 2024-04-02 9:27 ` Thorsten Leemhuis 0 siblings, 1 reply; 10+ messages in thread From: Randy Dunlap @ 2024-04-01 15:19 UTC (permalink / raw) To: Thorsten Leemhuis, Karel Balej, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too 2024-04-01 15:19 ` Randy Dunlap @ 2024-04-02 9:27 ` Thorsten Leemhuis 2024-04-02 10:13 ` Karel Balej 0 siblings, 1 reply; 10+ messages in thread From: Thorsten Leemhuis @ 2024-04-02 9:27 UTC (permalink / raw) To: Randy Dunlap, Karel Balej, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too 2024-04-02 9:27 ` Thorsten Leemhuis @ 2024-04-02 10:13 ` Karel Balej 2024-04-03 14:13 ` Thorsten Leemhuis 0 siblings, 1 reply; 10+ messages in thread From: Karel Balej @ 2024-04-02 10:13 UTC (permalink / raw) To: Thorsten Leemhuis Cc: Randy Dunlap, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows 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. ^ permalink raw reply [flat|nested] 10+ messages in thread
* Re: [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too 2024-04-02 10:13 ` Karel Balej @ 2024-04-03 14:13 ` Thorsten Leemhuis 0 siblings, 0 replies; 10+ messages in thread From: Thorsten Leemhuis @ 2024-04-03 14:13 UTC (permalink / raw) To: Karel Balej Cc: Randy Dunlap, Jonathan Corbet, regressions, linux-doc, linux-kernel, workflows 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 ^ permalink raw reply [flat|nested] 10+ messages in thread
end of thread, other threads:[~2024-04-10 21:03 UTC | newest] Thread overview: 10+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2024-03-28 19:29 [PATCH 0/2] regressions documentation improvements Karel Balej 2024-03-28 19:29 ` [PATCH 1/2] docs: *-regressions.rst: unify quoting, add missing word Karel Balej 2024-04-03 14:13 ` Linux regression tracking (Thorsten Leemhuis) 2024-04-10 21:03 ` Jonathan Corbet 2024-03-28 19:29 ` [PATCH 2/2] docs: handling-regressions.rst: clarify that "Closes:" tags work too Karel Balej 2024-04-01 8:38 ` Thorsten Leemhuis 2024-04-01 15:19 ` Randy Dunlap 2024-04-02 9:27 ` Thorsten Leemhuis 2024-04-02 10:13 ` Karel Balej 2024-04-03 14:13 ` Thorsten Leemhuis
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.