docs: add two texts covering regressions
Thorsten Leemhuis
maintainerv4 cover docs: add two texts covering regressions
"We don't cause regressions" might be the first rule of Linux kernel development, but it and other aspects of regressions nevertheless are hardly described in the Linux kernel's documentation. The following patches change this by creating two documents dedicated to the topic.
The second patch could easily be folded into the first one, but was kept separate, as it might be a bit controversial. This also allows the patch description to explain some backgrounds for this part of the document. Additionally, ACKs and Reviewed-by tags can be collected separately this way.
v4 (this version):
- countless small and medium changes after review feedback from Jon (thx), which also lead to a big change:
- split the document into two, one for users and one for developers (both added by the first patch, as they are interlinked)
- fixed and improved a bunch of areas I stumbled upon while checking the text again after the split
- add a third patch to get one of the user-centric document on regressions mentioned in Documentation/admin-guide/reporting-issues.rst
- note: the content added by the second patch did not change significantly, that's why I left an earlier reviewed-by for the patch and an ACK for the series in place there, but dropped the ACK for the first patch of the series
v3 (https://lore.kernel.org/regressions/[email protected]/):
- drop RFC tag
- heavily reshuffled and slightly adjusted the text in the sections "The important bits for people fixing regressions" and "How to add a regression to regzbot's tracking somebody else reported?" to make them easier to grasp
- a few small fixes and improvements
- add ACK for the series from Greg (now for real)
v2/RFC (https://lore.kernel.org/linux-doc/[email protected]/):
- a lot of small fixes, most are for spelling mistakes and grammar errors/problems pointed out in the review feedback I got so far
- add ACK for the series from Greg
v1/RFC (https://lore.kernel.org/linux-doc/[email protected]/):
- initial version
---
Hi! Here is a updated version of my patch-set adding documentation regarding regression. This bring bigger changes after Jon took a look and suggested splitting the text up. I did that and changed a bunch of other things along the way. But I for now decided against splitting off the regression tracking stuff into one or two other documents, as suggested by Jon, as that IMHO distributes the information over too many places.
Ciao, Thorsten
Thorsten Leemhuis (3):
docs: add two documents about regression handling
docs: regressions*rst: rules of thumb for handling regressions
docs: reporting-issues.rst: link new document about regressions
Documentation/admin-guide/index.rst | 1 + .../admin-guide/regressions-users.rst | 448 +++++++++++ .../admin-guide/reporting-issues.rst | 60 +- Documentation/process/index.rst | 1 + Documentation/process/regressions-devs.rst | 753 ++++++++++++++++++ MAINTAINERS | 2 + 6 files changed, 1234 insertions(+), 31 deletions(-) create mode 100644 Documentation/admin-guide/regressions-users.rst create mode 100644 Documentation/process/regressions-devs.rst
base-commit: b8f4eee6a630ef8c5f00594e25c377463b4f299c
Signature · 1 line
2.31.1
Thorsten Leemhuis
maintainerPATCH v4 1/3 docs: add two documents about regression handling
Create two documents explaining various aspects around regression handling and tracking; one is aimed at users, the other targets developers.
The texts among others describe the first rule of Linux kernel development and what it means in practice. They also explain what a regression actually is and how to report one properly.
Both texts additionally provide a brief introduction to the bot the kernel's regression tracker uses to facilitate the work, but mention the use is optional.
To sum things up, provide a few quotes from Linus in the document for developers to show how serious he takes regressions.
--- Documentation/admin-guide/index.rst | 1 + .../admin-guide/regressions-users.rst | 436 ++++++++++++ Documentation/process/index.rst | 1 + Documentation/process/regressions-devs.rst | 672 ++++++++++++++++++ MAINTAINERS | 2 + 5 files changed, 1112 insertions(+) create mode 100644 Documentation/admin-guide/regressions-users.rst create mode 100644 Documentation/process/regressions-devs.rst
Documentation/admin-guide/index.rst +1 -0
@@ -35,6 +35,7 @@ problems and bugs in particular. :maxdepth: 1 reporting-issues + regressions-users security-bugs bug-hunting bug-bisect
Documentation/admin-guide/regressions-users.rst new file +436 -0
436 lines not on this page · raw message
Documentation/process/index.rst +1 -0
@@ -27,6 +27,7 @@ Below are the essential guides that every developer should read. submitting-patches programming-language coding-style + regressions-devs maintainer-handbooks maintainer-pgp-guide email-clients
Documentation/process/regressions-devs.rst new file +672 -0
672 lines not on this page · raw message
MAINTAINERS +2 -0
@@ -10438,6 +10438,8 @@ KERNEL REGRESSIONS M: Thorsten Leemhuis <[email protected]> L: [email protected] S: Supported +F: Documentation/admin-guide/regressions-users.rst +F: Documentation/process/regressions-devs.rst KERNEL SELFTEST FRAMEWORK M: Shuah Khan <[email protected]>
Signature · 1 line
2.31.1
Jonathan Corbet
maintainerRe: [PATCH v4 1/3] docs: add two documents about regression handling
OK, I'll try not to take so long to have a look at it this time.
Quoted 15 lines · Thorsten Leemhuis
Create two documents explaining various aspects around regression handling and tracking; one is aimed at users, the other targets developers.
The texts among others describe the first rule of Linux kernel development and what it means in practice. They also explain what a regression actually is and how to report one properly.
Both texts additionally provide a brief introduction to the bot the kernel's regression tracker uses to facilitate the work, but mention the use is optional.
To sum things up, provide a few quotes from Linus in the document for developers to show how serious he takes regressions.
Quoted 6 lines
Signed-off-by Thorsten Leemhuis <[email protected]>--- Documentation/admin-guide/index.rst | 1 + .../admin-guide/regressions-users.rst | 436 ++++++++++++ Documentation/process/index.rst | 1 + Documentation/process/regressions-devs.rst | 672 ++++++++++++++++++
I'll start with some *serious* bikesheddery...it's best if the names of the files tell readers what's inside. This isn't something I feel really strongly about, but we could consider
admin-guide/reporting-regressions.txt (or just regressions.txt) process/regression-policy.txt
Quoted 5 lines
MAINTAINERS | 2 + 5 files changed, 1112 insertions(+) create mode 100644 Documentation/admin-guide/regressions-users.rst create mode 100644 Documentation/process/regressions-devs.rst
[...]
Documentation/admin-guide/regressions-users.rst line 169
Quoted 3 lines
Documentation/admin-guide/regressions-users.rst new file +3
-0+Send a mail to the regressions mailing list ([email protected]) while +CCing the Linux kernel's regression tracker ([email protected]); if the +issue might better be dealt with in private, feel free to omit the list.
Perhaps a separate concern, but might you want to set up an @kernel.org alias for the regression tracker? Trust me, you're not gonna want to run it forever, and the ability to quickly redirect the mail may prove to be a nice thing to have. An email address with your domain sitting in the docs will circulate for years after it gets changed.
Quoted 14 lines
Documentation/admin-guide/regressions-users.rst new file +14
-0+ +Additional details about regressions +------------------------------------ + + +What is the goal of the "no regressions rule"? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users should feel safe when updating kernel versions and not have to worry +something might break. This is in the interest of the kernel developers to make +updating attractive: they don't want users to stay on stable or longterm Linux +series that are either abandoned or more than one and a half years old. That's +in everybody's interest, as `those series might have known bugs, security +issues, or other problematic aspects already fixed in later versions
Documentation/admin-guide/regressions-users.rst line 194
Quoted 10 lines
Documentation/admin-guide/regressions-users.rst new file +10
-0+<http://www.kroah.com/log/blog/2018/08/24/what-stable-kernel-should-i-use/>`_. +Additionally, the kernel developers want to make it simple and appealing for +users to test the latest pre-release or regular release. That's also in +everybody's interest, as it's a lot easier to track down and fix problems, if +they are reported shortly after being introduced. + +Is the "no regressions" rule really adhered in practice? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's taken really serious, as can be seen by many mailing list posts from Linux
serious*ly*
Otherwise I can't find a lot to complain about at this point. I'm not really convinced that we need all those Quotations From Chairman Linus, but I won't fight about it either :)
In general, though, unless objections show up, I don't see any real reason to not apply this one.
Thanks,
jon
Thorsten Leemhuis
maintainerRe: [PATCH v4 1/3] docs: add two documents about regression handling
Quoted 26 lines · Jonathan Corbet
OK, I'll try not to take so long to have a look at it this time.
Quoted 15 lines · Thorsten Leemhuis
Create two documents explaining various aspects around regression handling and tracking; one is aimed at users, the other targets developers.
The texts among others describe the first rule of Linux kernel development and what it means in practice. They also explain what a regression actually is and how to report one properly.
Both texts additionally provide a brief introduction to the bot the kernel's regression tracker uses to facilitate the work, but mention the use is optional.
To sum things up, provide a few quotes from Linus in the document for developers to show how serious he takes regressions.
Quoted 6 lines
Signed-off-by Thorsten Leemhuis <[email protected]>--- Documentation/admin-guide/index.rst | 1 + .../admin-guide/regressions-users.rst | 436 ++++++++++++ Documentation/process/index.rst | 1 + Documentation/process/regressions-devs.rst | 672 ++++++++++++++++++
Quoted 3 lines
I'll start with some *serious* bikesheddery...it's best if the names of the files tell readers what's inside. This isn't something I feel really strongly about, but we could consider
I wasn't totally happy with the file names myself, so it's good that you bring it up.
Quoted 2 lines
admin-guide/reporting-regressions.txt(or just regressions.txt)process/regression-policy.txt
I like "reporting-regressions.txt", but I wonder if using the word "policy" is a good idea. I tried to avoid it (and similar words, like guidelines), as they might do more harm then good. So how about:
admin-guide/reporting-regressions.rst
process/regressions.rst
Quoted 10 lines
[...]
Documentation/admin-guide/regressions-users.rst line 169
Quoted 3 lines
Documentation/admin-guide/regressions-users.rst new file +3
-0+Send a mail to the regressions mailing list ([email protected]) while +CCing the Linux kernel's regression tracker ([email protected]); if the +issue might better be dealt with in private, feel free to omit the list.Perhaps a separate concern, but might you want to set up an @kernel.org alias for the regression tracker? Trust me, you're not gonna want to run it forever, and the ability to quickly redirect the mail may prove to be a nice thing to have. An email address with your domain sitting in the docs will circulate for years after it gets changed.
Yeah, it's on my mental to do list for a few weeks already, but never set down to actually get this rolling. You are right, I'll ask for an alias.
Quoted 6 lines
Documentation/admin-guide/regressions-users.rst line 194
Quoted 4 lines
Documentation/admin-guide/regressions-users.rst new file +4
-0+Is the "no regressions" rule really adhered in practice? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +It's taken really serious, as can be seen by many mailing list posts from Linuxserious*ly*
Fixed.
Quoted 3 lines
Otherwise I can't find a lot to complain about at this point. I'm not really convinced that we need all those Quotations From Chairman Linus, but I won't fight about it either :)
I'll take a look again and consider kicking a few.
Quoted 2 lines
In general, though, unless objections show up, I don't see any real reason to not apply this one.
Great, many thx!
Ciao, Thorsten
Thorsten Leemhuis
maintainerRe: [PATCH v4 1/3] docs: add two documents about regression handling
Quoted 37 lines · Thorsten Leemhuis
Quoted 26 lines · Jonathan Corbet
OK, I'll try not to take so long to have a look at it this time.
Quoted 15 lines · Thorsten Leemhuis
Create two documents explaining various aspects around regression handling and tracking; one is aimed at users, the other targets developers.
The texts among others describe the first rule of Linux kernel development and what it means in practice. They also explain what a regression actually is and how to report one properly.
Both texts additionally provide a brief introduction to the bot the kernel's regression tracker uses to facilitate the work, but mention the use is optional.
To sum things up, provide a few quotes from Linus in the document for developers to show how serious he takes regressions.
Quoted 6 lines
Signed-off-by Thorsten Leemhuis <[email protected]>--- Documentation/admin-guide/index.rst | 1 + .../admin-guide/regressions-users.rst | 436 ++++++++++++ Documentation/process/index.rst | 1 + Documentation/process/regressions-devs.rst | 672 ++++++++++++++++++Quoted 3 lines
I'll start with some *serious* bikesheddery...it's best if the names of the files tell readers what's inside. This isn't something I feel really strongly about, but we could consider
I wasn't totally happy with the file names myself, so it's good that you bring it up.
Quoted 2 lines
admin-guide/reporting-regressions.txt(or just regressions.txt)process/regression-policy.txt
Quoted 6 lines
I like "reporting-regressions.txt", but I wonder if using the word "policy" is a good idea. I tried to avoid it (and similar words, like guidelines), as they might do more harm then good. So how about:
admin-guide/reporting-regressions.rst
process/regressions.rst
BTW, I settled on these:
admin-guide/reporting-regressions.rst
process/handling-regressions.rst
Quoted 11 lines
Quoted 10 lines
[...]
Documentation/admin-guide/regressions-users.rst line 169
Quoted 3 lines
Documentation/admin-guide/regressions-users.rst new file +3
-0+Send a mail to the regressions mailing list ([email protected]) while +CCing the Linux kernel's regression tracker ([email protected]); if the +issue might better be dealt with in private, feel free to omit the list.Perhaps a separate concern, but might you want to set up an @kernel.org alias for the regression tracker? Trust me, you're not gonna want to run it forever, and the ability to quickly redirect the mail may prove to be a nice thing to have. An email address with your domain sitting in the docs will circulate for years after it gets changed.
Quoted 2 lines
Yeah, it's on my mental to do list for a few weeks already, but never set down to actually get this rolling. You are right, I'll ask for an alias.
I liked the idea and requested this, but Konstantin raised a good point:
"we don't have generic aliases for all other subsystems, but the situation where someone may want to discuss something off-list arises for all of them". I have to agree with him. I first wanted to change the text to something like "look up the address in MAINTAINERS", but that just shifts the problem. Additionally: We have lot's of other private addresses from maintainers in the docs as well and don't consider that to be a problem. And if somebody else takes over I can also redirect that email or create a autoreply on my local server. So I'd say we just leave things as they are, it's not perfect, but good enough I'd say.
Ciao, Thorsten
Thorsten Leemhuis
maintainerPATCH v4 2/3 docs: regressions*rst: rules of thumb for handling regressions
In reply to Thorsten LeemhuisAdd a section with a few rules of thumb about how quickly developers should address regressions to Documentation/process/regressions-devs.rst; additionally, add a short paragraph about this to the companion document Documentation/admin-guide/regressions-users.rst as well.
The rules of thumb were written after studying the quotes from Linus found in regressions-devs.rst and especially influenced by statements like "Users are literally the _only_ thing that matters" and "without users, your program is not a program, it's a pointless piece of code that you might as well throw away". The author interpreted those in perspective to how the various Linux kernel series are maintained currently and what those practices might mean for users running into a regression on a small or big kernel update.
That for example lead to the paragraph starting with "Aim to get fixes for regressions mainlined within one week after identifying the culprit, if the regression was introduced in a stable/longterm release or the devel cycle for the latest mainline release". Some might see this as pretty high bar, but on the other hand something like that is needed to not leave users out in the cold for too long -- which can quickly happen when updating to the latest stable series, as the previous one is normally stamped "End of Life" about three or four weeks after a new mainline release. This makes a lot of users switch during this timeframe. Any of them thus risk running into regressions not promptly fixed; even worse, once the previous stable series is EOLed for real, users that face a regression might be left with only three options:
(1) continue running an outdated and thus potentially insecure kernel version from an abandoned stable series
(2) run the kernel with the regression
(3) downgrade to an earlier longterm series still supported
This is better avoided, as (1) puts users and their data in danger, (2) will only be possible if it's a minor regression that doesn't interfere with booting or serious usage, and (3) might be regression itself or impossible on the particular machine, as the users might require drivers or features only introduced after the latest longterm series branched of.
In the end this lead to the aforementioned "Aim to fix regression within one week" part. It's also the reason for the "Try to resolve any regressions introduced in the current development cycle before its end.".
---
Hi! A lot of developers are doing a good job in fixing regressions in a reasonable time span, but I noticed it sometimes takes many weeks to get even simple fixes for regressions merged. Most of the time this is due to one of these factors:
* it takes a long time to get the fix ready, as some developers apparently don't prioritize work on fixing regressions
* fully developed fixes linger in git trees of maintainers for weeks, sometimes even without the fix being in linux-next
This afaics is especially a problem for regressions introduced in mainline, but only found after a new versions was released and a new stable kernel series derived from it. Sometimes fixes for these regressions are even left lying around for weeks until the next merge window, which contributes to a huge pile of fixes getting backported to stable and longterm releases after a merge window ended. Asking developers to speed things up rarely helped, as people have different opinions on how fast regression fixes need to be developed and merged upstream.
That's why it would be a great help to my work as regression tracker if we had some rough written down guidelines for handling regressions, as proposed by the patch below. I'm well aware that the text sets a pretty high bar. That's because I approached the problem primarily from the point of a user, as can be seen by the patch description.
The text added by this patch likely will lead to some discussions, that's why I submit it separately from the rest of the new documents on regressions, which are found in patch 1/3; I also CCed Linus on this patch and hope he states his opinion or even ACKs is. In the end I can easily tone this down or write something totally different: that's totally fine for me, I'm mainly interested in having some expectations roughly documented to get everyone on the same page.
Ciao, Thorsten
--- .../admin-guide/regressions-users.rst | 12 +++ Documentation/process/regressions-devs.rst | 81 +++++++++++++++++++ 2 files changed, 93 insertions(+)
Documentation/admin-guide/regressions-users.rst +12 -0
@@ -214,6 +214,18 @@ your report on the radar of these people by CCing or forwarding each report to the regressions mailing list, ideally with a "regzbot command" in your mail to get it tracked. +How quickly are regressions normally fixed? +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Developers should fix any reported regression as quickly as possible, to provide +affected users with a solution in a timely manner and prevent more users from +running into the issue; nevertheless developers need to take enough time and +care to ensure regression fixes do not cause additional damage. + +The answer thus depends on various factors like the impact of a regression, its +age, or the Linux series in which it occurs. In the end though, most regressions +should be fixed within two weeks. + Is it a regression, if the issue can be avoided by updating some software? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Documentation/process/regressions-devs.rst +81 -0
93 lines not on this page · raw message
Signature · 1 line
2.31.1
Jonathan Corbet
maintainerRe: [PATCH v4 2/3] docs: regressions*rst: rules of thumb for handling regressions
Thorsten Leemhuis <[email protected]> writes:
One thing that caught my eye this time around...
Documentation/process/regressions-devs.rst or others might need to look into the fix months or years later; these links are · line 161
Quoted 5 lines
+ * Address regressions in stable, longterm, or proper mainline releases with
Documentation/process/regressions-devs.rst +4
-0+ more urgency than regressions in mainline pre-releases. That changes after + the release of the fifth pre-release, aka "-rc5": mainline then becomes as + important, to ensure all the improvements and fixes are ideally tested + together for at least one week before Linus releases a new mainline version.
Is that really what we want to suggest? I ask because (1) fixes for stable releases need to show up in mainline first anyway, and (2) Greg has often stated that the stable releases shouldn't be something that most maintainers need to worry about. So if the bug is in mainline, that has to get fixed first, and if it's something special to a stable release, well, then the stable folks should fix it :)
Documentation/process/regressions-devs.rst or others might need to look into the fix months or years later; these links are · line 175
Quoted 13 lines
+ * Fix regressions within two or three days, if they are critical for some
Documentation/process/regressions-devs.rst +12
-0+ reason -- for example, if the issue is likely to affect many users of the + kernel series in question on all or certain architectures. Note, this + includes mainline, as issues like compile errors otherwise might prevent many + testers or continuous integration systems from testing the series. + + * Aim to merge regression fixes into mainline within one week after the culprit + was identified, if the regression was introduced in a stable/longterm release + or the development cycle for the latest mainline release (say v5.14). If + possible, try to address the issue even quicker, if the previous stable + series (v5.13.y) will be abandoned soon or already was stamped "End-of-Life" + (EOL) -- this usually happens about three to four weeks after a new mainline + release.
How much do we really think developers should worry about nearly-dead stable kernels? We're about to tell users they shouldn't be running the kernel anyway...
Thanks,
jon
Thorsten Leemhuis
maintainerRe: [PATCH v4 2/3] docs: regressions*rst: rules of thumb for handling regressions
Quoted 10 lines · Jonathan Corbet
Thorsten Leemhuis <[email protected]> writes:
One thing that caught my eye this time around...
Documentation/process/regressions-devs.rst or others might need to look into the fix months or years later; these links are · line 161
Quoted 5 lines
+ * Address regressions in stable, longterm, or proper mainline releases with
Documentation/process/regressions-devs.rst +4
-0+ more urgency than regressions in mainline pre-releases. That changes after + the release of the fifth pre-release, aka "-rc5": mainline then becomes as + important, to ensure all the improvements and fixes are ideally tested + together for at least one week before Linus releases a new mainline version.
Quoted 6 lines
Is that really what we want to suggest? I ask because (1) fixes for stable releases need to show up in mainline first anyway, and (2) Greg has often stated that the stable releases shouldn't be something that most maintainers need to worry about. So if the bug is in mainline, that has to get fixed first, and if it's something special to a stable release, well, then the stable folks should fix it :)
Hmmm. Well, afaics in the end many (most?) of the regressions that happen in these series are present in mainline as well: either they where introduced in an earlier devel cycle or came with a backport to stable/longterm and thus are present in mainline as well (unless the backport was incomplete or broken). So I'd say it's up to the regular developers and not the stable team to fix many (most?) of them.
That being said: yes, I think you have a point. This could be fixed with some small adjustments to the wording above, but...
Quoted 5 lines
Documentation/process/regressions-devs.rst or others might need to look into the fix months or years later; these links are · line 167
Quoted 5 lines
+ * Fix regressions within two or three days, if they are critical for some
Documentation/process/regressions-devs.rst +4
-0+ reason -- for example, if the issue is likely to affect many users of the + kernel series in question on all or certain architectures. Note, this + includes mainline, as issues like compile errors otherwise might prevent many + testers or continuous integration systems from testing the series.
...the same aspect is relevant for other points like this one, too. And there it's not as easily solved. So maybe this is better addressed with a separate point early in the list:
``` * Developers are expected to handle regressions in all kernel series, but are free to leave them to the stable team, if the regression probably at no point in time occurred with mainline. ```
Regressions for example caused by incomplete or broken backports thus would be something developers could leave to Greg (and I expect he won't mind).
Quoted 11 lines
Documentation/process/regressions-devs.rst or others might need to look into the fix months or years later; these links are · line 175
Quoted 7 lines
+ * Aim to merge regression fixes into mainline within one week after the culprit
Documentation/process/regressions-devs.rst +6
-0+ was identified, if the regression was introduced in a stable/longterm release + or the development cycle for the latest mainline release (say v5.14). If + possible, try to address the issue even quicker, if the previous stable + series (v5.13.y) will be abandoned soon or already was stamped "End-of-Life" + (EOL) -- this usually happens about three to four weeks after a new mainline + release.How much do we really think developers should worry about nearly-dead stable kernels? We're about to tell users they shouldn't be running the kernel anyway...
I'd expect we handle near EOL stable release round about normally until they become EOL. But anyway, I had something different in mind when I wrote the above and I get the feeling my text didn't express it well and got you on the wrong track. :-/
My intention was: I want to prevent users getting stuck on EOLed stable series (say 5.13.y) when a regression makes it hard or impossible for the user to run the directly succeeding stable series (5.14.y).
I think this expresses it better:
``` * Aim to merge regression fixes into mainline within one week after the culprit was identified, if the regression was introduced in either: * the development cycle of the latest proper mainline release * a recent release in a stable/longterm series Try to address regressions in the latest stable series even quicker, if the previous series will be abandoned soon or already was stamped "End-of-Life" (EOL) -- this usually happens about three to four weeks after a new mainline release. Remember to mark the fix for backporting by using both the ``Fixes:`` tag and ``Cc: [email protected]``. ```
How does that sound?
Thx for the feedback, it's good that these things turned up.
Ciao, Thorsten
Thorsten Leemhuis
maintainerPATCH v4 3/3 docs: reporting-issues.rst: link new document about regressions
In reply to Thorsten LeemhuisMake Documentation/admin-guide/reporting-issues.rst point to the newly created document about regressions (Documentation/admin-guide/regressions-users.rst). This allows to shorten a few explanations the new document describes better and in more detail.
While at it move the copyright hint to the end of the file, as suggested during review of the new documents about regressions.
--- .../admin-guide/reporting-issues.rst | 60 +++++++++---------- 1 file changed, 29 insertions(+), 31 deletions(-)
Documentation/admin-guide/reporting-issues.rst +29 -31
@@ -1,14 +1,5 @@ .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0) -.. - If you want to distribute this text under CC-BY-4.0 only, please use 'The - Linux kernel developers' for author attribution and link this as source: - https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst -.. - Note: Only the content of this RST file as found in the Linux kernel sources - is available under CC-BY-4.0, as versions of this text that were processed - (for example by the kernel's build system) might contain content taken from - files which use a more restrictive license. - +.. See the bottom of this file for additional redistribution information. Reporting issues ++++++++++++++++
@@ -395,19 +386,13 @@ fixed as soon as possible, hence there are 'issues of high priority' that get handled slightly differently in the reporting process. Three type of cases qualify: regressions, security issues, and really severe problems. -You deal with a 'regression' if something that worked with an older version of -the Linux kernel does not work with a newer one or somehow works worse with it. -It thus is a regression when a WiFi driver that did a fine job with Linux 5.7 -somehow misbehaves with 5.8 or doesn't work at all. It's also a regression if -an application shows erratic behavior with a newer kernel, which might happen -due to incompatible changes in the interface between the kernel and the -userland (like procfs and sysfs). Significantly reduced performance or -increased power consumption also qualify as regression. But keep in mind: the -new kernel needs to be built with a configuration that is similar to the one -from the old kernel (see below how to achieve that). That's because the kernel -developers sometimes can not avoid incompatibilities when implementing new -features; but to avoid regressions such features have to be enabled explicitly -during build time configuration. +You deal with 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 document +'Documentation/admin-guide/regressions-users.rst' explains this in more detail. +It also provides a good deal of other information about regressions you might +want to be aware of; it for example explains how to add your issue to the list +of tracked regressions, to ensure it won't fall through the cracks. What qualifies as security issue is left to your judgment. Consider reading 'Documentation/admin-guide/security-bugs.rst' before proceeding, as it
@@ -1073,10 +1058,10 @@ When dealing with regressions make sure the issue you face is really caused by the kernel and not by something else, as outlined above already. In the whole process keep in mind: an issue only qualifies as regression if the -older and the newer kernel got built with a similar configuration. The best way -to archive this: copy the configuration file (``.config``) from the old working -kernel freshly to each newer kernel version you try. Afterwards run ``make -olddefconfig`` to adjust it for the needs of the new version. +older and the newer kernel got built with a similar configuration. This can be +achieved by using ``make olddefconfig``, as explained in more detail by +Documentation/admin-guide/regressions-users.rst; that document also provides a +good deal of other information about regressions you might want to be aware of. Write and send the report
@@ -1756,10 +1741,23 @@ art will lay some groundwork to improve the situation over time. .. - This text is maintained by Thorsten Leemhuis <[email protected]>. If you - spot a typo or small mistake, feel free to let him know directly and he'll - fix it. You are free to do the same in a mostly informal way if you want - to contribute changes to the text, but for copyright reasons please CC + end-of-content +.. + This document is maintained by Thorsten Leemhuis <[email protected]>. If + you spot a typo or small mistake, feel free to let him know directly and + he'll fix it. You are free to do the same in a mostly informal way if you + want to contribute changes to the text, but for copyright reasons please CC [email protected] and "sign-off" your contribution as Documentation/process/submitting-patches.rst outlines in the section "Sign your work - the Developer's Certificate of Origin". +.. + This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top + of the file. If you want to distribute this text under CC-BY-4.0 only, + please use "The Linux kernel developers" for author attribution and link + this as source: + https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/reporting-issues.rst +.. + Note: Only the content of this RST file as found in the Linux kernel sources + is available under CC-BY-4.0, as versions of this text that were processed + (for example by the kernel's build system) might contain content taken from + files which use a more restrictive license.
Signature · 1 line
2.31.1
Jonathan Corbet
maintainerRe: [PATCH v4 3/3] docs: reporting-issues.rst: link new document about regressions
Quoted 13 lines · Thorsten Leemhuis
Make
Documentation/admin-guide/reporting-issues.rstpoint to the newly created document about regressions (Documentation/admin-guide/regressions-users.rst). This allows to shorten a few explanations the new document describes better and in more detail.While at it move the copyright hint to the end of the file, as suggested during review of the new documents about regressions.
Signed-off-by Thorsten Leemhuis <[email protected]>--- .../admin-guide/reporting-issues.rst | 60 +++++++++---------- 1 file changed, 29 insertions(+), 31 deletions(-)
[...]
Documentation/admin-guide/reporting-issues.rst fixed as soon as possible, hence there are 'issues of high priority' that get · line 392
Quoted 4 lines
Documentation/admin-guide/reporting-issues.rst +4
-0+You deal with 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 document +'Documentation/admin-guide/regressions-users.rst' explains this in more detail.
Some of those quotes around file names are still sneaking in.
Thanks,
jon
Thorsten Leemhuis
maintainerRe: [PATCH v4 3/3] docs: reporting-issues.rst: link new document about regressions
Quoted 16 lines · Jonathan Corbet
Quoted 6 lines · Thorsten Leemhuis
Make
Documentation/admin-guide/reporting-issues.rstpoint to the newly created document about regressions (Documentation/admin-guide/regressions-users.rst). This allows to shorten a few explanations the new document describes better and in more detail.Quoted 7 lines
While at it move the copyright hint to the end of the file, as suggested during review of the new documents about regressions.
Signed-off-by Thorsten Leemhuis <[email protected]>--- .../admin-guide/reporting-issues.rst | 60 +++++++++---------- 1 file changed, 29 insertions(+), 31 deletions(-)
Quoted 8 lines
[...]
Documentation/admin-guide/reporting-issues.rst fixed as soon as possible, hence there are 'issues of high priority' that get · line 392
Quoted 4 lines
Documentation/admin-guide/reporting-issues.rst +4
-0+You deal with 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 document +'Documentation/admin-guide/regressions-users.rst' explains this in more detail.Some of those quotes around file names are still sneaking in.
I did that on purpose here, as the file right now uses single quotes for doc references almost everywhere and I thought I better stick to its style -- especially as one such a quoted references is pretty close by in this case, so it would look odd to quote one but not the other:
``` [...] compiled using a similar configuration. The document 'Documentation/admin-guide/regressions-users.rst' explains this in more detail. It also provides a good deal of other information about regressions you might want to be aware of; it for example explains how to add your issue to the list of tracked regressions, to ensure it won't fall through the cracks. What qualifies as security issue is left to your judgment. Consider reading 'Documentation/admin-guide/security-bugs.rst' before proceeding, as it [...] ```
Stupid me just forgot to use single quotes for the second link to Documentation/admin-guide/regressions-users.rst. Will fix this up :-/
That being said: in a mail on Monday I already raised the issue like this (slightly reworded):
----
I noticed I quoted internal references in reporting-issues.rst quite often. IMHO it improves readability sometimes (it depends a lot on the title of the target document), as can be seen in this example.
The source text looks like this:
``` If your kernel is tainted, study 'Documentation/admin-guide/tainted-kernels.rst' to find out why. [...] To find the change there is a process called 'bisection' which the document 'Documentation/admin-guide/bug-bisect.rst' describes in detail. ```
After processing to HTML the text looks like this:
``` If your kernel is tainted, study ‘Tainted kernels‘ to find out why. [...] To find the change there is a process called ‘bisection’ which the document ‘Bisecting a bug’ describes in detail. ```
Sure, "Tainted kernels" and "Bisecting a bug" are links and hence displayed differently by the browser, but I think the quotes help. But YMMV.
I sooner or later hope to improve and fix a few things in reporting-issues.rst anyway. Let me know if I should take the opportunity to remove the single quotes then.
----
So I'd say: I add two more quoted doc links to the file now and fix this up later, if you still think removing the quotes is a good idea. Or do you want me to remove the single quotes now in that patch (or a separate one?)? It's not a big deal, there are only about 10 docs references.
Ciao, Thorsten