docs: add high-level overview of regzbot #21
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -3,6 +3,19 @@ | |
| [[_TOC_]] | ||
|
|
||
|
|
||
| ## Background | ||
|
|
||
| A **regression** is a change in the kernel that breaks something that previously | ||
| worked — degraded performance, a feature that stops working, or hardware that is | ||
| no longer recognized. Regressions are treated with higher urgency than ordinary | ||
| bugs; see the kernel documentation on | ||
| [reporting regressions](https://docs.kernel.org/admin-guide/reporting-regressions.html) and | ||
| [handling regressions](https://docs.kernel.org/process/handling-regressions.html). | ||
|
|
||
| This guide focuses on the `#regzbot` commands reporters and developers can use | ||
| to add or update tracked regressions. | ||
|
|
||
|
Comment on lines
+6
to
+17
Collaborator
There was a problem hiding this comment. This IMHO is not a good fit for the head of a "getting started" document, as it's a kinda boring text at the start of document (ask yourself: would you want to read a lengthy background sections like this when all you want is to use a software or understand what is it?). Something like this would be better. ""Regzbot is a bot tracking Linux kernel regressions over multiple domains (email, issue trackers, git trees, …) to ensure they are resolved in a timely manner – which is expected from Linux developers, as regressions (e.g. something that worked fine at one point works worse or not at all with a newer version) are forbidden."" Needs a bit of fine tuning. One more sentence of that sort might be okay. But I guess all the other stuff in this section should go elsewhere or might be superfluous.
Collaborator
There was a problem hiding this comment. Now I see that this is bringing some info from your personal https://linux-regtracking.leemhuis.info/about/ into the project. I believe the "about" page of the repo is the README, so how do you feel about putting most of it in there?
Collaborator
There was a problem hiding this comment.
Ohh? Ohh, yeah, might totally be! 😀 To be honest I totally forgot about that page. 🫣
Sounds like a very good idea - at least unless it becomes a super long README. There might be overlap with getting_started, too. So one needs to be careful here. @alanpeixinho is that something you would be willing to do as part of these changes or separately? Here is the source file for that page: about.md
Author
There was a problem hiding this comment. Done. I have included some of the info on README and geeting_started.
Collaborator
There was a problem hiding this comment.
Not sure. Guess one or two sentences might be a worth it. Maybe even more or all of it; use your best judgement.
Collaborator
There was a problem hiding this comment. BTW, to avoid taking past each other: I still see the "Linux kernel development happens primarily over email. A few pieces of this infrastructure are relevant to regzbot: […] until it reaches the relevant tree." section in the patch (but maybe it's not the latest one?). I think that should also go or moved, as something like that feels misplaced and boring at the start of a "getting started" document.
Author
There was a problem hiding this comment. I considered simplifying it a little bit, but I decided to just remove this part completely. As this information is already covered in other places. |
||
|
|
||
| ## Why and how to make regzbot track a Linux kernel regression | ||
|
|
||
| When reporting a Linux kernel regression it is in your interest to make [regzbot](https://gitlab.com/knurd42/regzbot/) aware of the issue, as that ensures the report won't accidentally fall though the cracks; it also makes sure leading developers see the issue via the tracked regression website [or the weekly reports, which are not sent yet, but soon will be]. | ||
|
|
@@ -26,6 +39,18 @@ Regzbot is designed to normally not create any additional chores for Linux kerne | |
| But sometimes you might want to do more with regzbot, like specifying a culprit exactly after a bisection or marking a regression as resolved. The text below explains how to do these and other things; the instructions there also will tell you how to use regzbot to track regressions for your own code or the subsystem you maintain, as that will make sure none fall through the cracks unnoticed. | ||
|
|
||
|
|
||
| ## How to help keep tracking accurate | ||
|
|
||
| If a tracked issue turns out not to be a regression, if discussion moved | ||
| elsewhere, or if important details such as the title or introduced range are | ||
| wrong, please reply publicly and include the appropriate `#regzbot` command. | ||
| That keeps the public record clear and helps regzbot show useful status. | ||
|
|
||
| Developers do not need to CC individual regression trackers on every follow-up. | ||
| Keep `regressions@lists.linux.dev` in the loop and use `Link:` or `Closes:` | ||
| tags that point to the report when posting fixes. | ||
|
|
||
|
|
||
| ## More regzbot features relevant for both reporters and developers | ||
|
|
||
|
|
||
|
|
||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I might be wrong, but isn't this at least in parts telling things a second time that are already covered?
Uh oh!
There was an error while loading. Please reload this page.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yeah, you are right. In the rearrangement some information became redundant. Gonna take a look.