docs: add high-level overview of regzbot#21
Conversation
|
@alanpeixinho pls add you sign off in the commit |
|
So, on one hand this is great. It thus should be mentioned in README.md so that people find it – a file that also prominently mentions docs/getting_started.md as a starting point. Which leads to the question: do we really need three documents for this, that in parts overlap? Maybe we need three documents -- or four, if you count docs/reference.md, which we should not forget there:
Or what do others think? |
Good point, @knurd. I felt that friction too when deciding where to put this. I’m totally on board with consolidating these to reduce bloat in docs. Do you think splitting this content between the README.md and getting_started.md is cleaner? |
From a quick look I guess most of the stuff should go into those files. Maybe there are bits that are best put into the reference docs, too. And stuff like "Codebase organization" maybe should go to CONTRIBUTING.md (or a new file that is meant for developers, but I doubt one will be needed). Overall use your best judgement – and when you get a "this doesn't fit well" feeling or something like that really just ping me to discuss things in a chat, that might be easier for both of us that doing it here . |
Signed-off-by: Alan Peixinho <alan.peixinho@profusion.mobi>
I have redistributed the overview over the already existing documentation. Please, let me know if anything feels off. |
This looks better, thx It's okay for you if I do a small minor adjustments while applying this? I fear discussing all of those here might result in a lot of overhead for both of us. |
Sure. Feel free. |
knurd
left a comment
knurd
left a comment
There was a problem hiding this comment.
Really wanted to make this easy for you and fine tune things when applying, but maybe let's do one more round of review and improving, as I noticed a few things that were not easy to fix.
| ## 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). | ||
|
|
||
| Linux kernel development happens primarily over **email**. A few pieces of this | ||
| infrastructure are relevant to regzbot: | ||
|
|
||
| * **Mailing lists** — developers communicate through lists organized by | ||
| subsystem. `regressions@lists.linux.dev` is specifically for regression | ||
| reports. | ||
| * **lore.kernel.org** — the public archive of all kernel mailing lists, where | ||
| every email has a permanent URL. | ||
| * **Message-ID / In-Reply-To / References** — standard email headers that | ||
| define threading. Regzbot uses these to tie replies, patches, and fixes to the | ||
| original report. | ||
| * **`Link:` and `Closes:` tags** — conventions in Git commit messages that | ||
| reference mailing list discussions. Regzbot watches these to detect fixes. | ||
|
|
||
| Regzbot tracks three Git trees because fixes arrive at different times: | ||
| **mainline** (`torvalds/linux.git`), **linux-next** (subsystem work before | ||
| mainline), and **stable** (already-shipped kernels). A fix present only in | ||
| linux-next shows as "fix incoming" until it reaches the relevant tree. | ||
|
|
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.
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?
Having the definition of regression in plain text is very helpful to understand the scope of the project
There was a problem hiding this comment.
Now I see that this is bringing some info from […]
Ohh? Ohh, yeah, might totally be! 😀 To be honest I totally forgot about that page. 🫣
README, so how do you feel about putting most of it in there?
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
| still in a alpha stage: more adjustments are needed to make it better suite the | ||
| its intended purpose. | ||
|
|
||
| Regzbot is now part of [KernelCI](https://kernelci.org/), where it contributes |
There was a problem hiding this comment.
It's good to mention that, but the document at the end mentions it's supported by Meta; guess might be best to move it there and adjust things, as Meta does not sponsor it anymore.
There was a problem hiding this comment.
What should we add as the ending date for the Meta sponsorship? So we can keep the updated history.
There was a problem hiding this comment.
no need to specify dates I'd say; just something like "Meta sponsored for about two years. After some time without a sponsor, KernelCI stepped in…"
| not slip between first report and a fix in the appropriate kernel tree. | ||
| Reporters and developers interact with it through special lines in emails | ||
| (`#regzbot` commands) or existing conventions (`Link:` / `Closes:` tags in | ||
| commits), keeping overhead minimal. |
There was a problem hiding this comment.
That's fine, but if you want to do some fine tuning, something like this maybe (please check and fine tune):
Everyone can add a regression through a command like #regzbot introduced: <gitsha> in a email on the LKML or the regressions lists. Regzbot later automatically will notice a change fixing it if it points to the report using a Link: or Closes: tag, which is a existing convention and thus keeps overhead to zero for developers. See the documentation for other #regzbot commands that can be used if those links were forgotten.
| kernel documentation for | ||
| [reporting regressions](https://docs.kernel.org/admin-guide/reporting-regressions.html) and | ||
| [handling regressions](https://docs.kernel.org/process/handling-regressions.html). | ||
|
|
There was a problem hiding this comment.
I might be wrong, but isn't this at least in parts telling things a second time that are already covered?
There was a problem hiding this comment.
Yeah, you are right. In the rearrangement some information became redundant. Gonna take a look.
3 participants
Description
I’ve added documentation to provide high level context (targeted at new collaborators) on how Regzbot operates under the hood.
Summary: