Skip to content

Commit 739f89e

Browse files
alanpeixinhoalanpeixinho
committed
docs: add high-level overview of regzbot
Signed-off-by: Alan Peixinho <alan.peixinho@profusion.mobi>
1 parent c2bee9e commit 739f89e

4 files changed

Lines changed: 109 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,29 @@
1+
Codebase overview
2+
=================
3+
4+
| Area | Files | Role |
5+
|------|-------|------|
6+
| Core + DB | `__init__.py` | Regression model, `GitTree`/`GitBranch`, `ReportThread`, `run()`/`generate_web()`/`report()` |
7+
| Bot commands | `_rbcmd.py` | Parse and execute `#regzbot` subcommands |
8+
| CLI | `commandl.py` | argparse-based subcommands |
9+
| Web export | `export_web.py` | Static HTML generation |
10+
| Mail reports | `export_mail.py` | Weekly text/mail report layout |
11+
| CSV export | `export_csv.py` | CSV-oriented export (tests) |
12+
| Lore ingestion | `_repsources/_lore.py` | NNTP and HTTPS access to lore archives |
13+
| Tracker sources | `_bugzilla.py`, `_gitlab.py`, `_github.py`, `_generic.py` | Tracker-specific API integrations |
14+
| Tests | `testing_online.py`, `testing_offline.py`, `testing_trackers.py`, `testdata/*` | Offline/online/tracker tests/expected results |
15+
16+
Report sources (pluggable backends):
17+
18+
| Source | Implementation | Notes |
19+
|--------|----------------|-------|
20+
| **lore** (NNTP/HTTPS) | `_repsources/_lore.py` | Primary source; kernel mailing list archives |
21+
| **bugzilla.kernel.org** | `_repsources/_bugzilla.py` | REST API with API key |
22+
| **GitLab** | `_repsources/_gitlab.py` | Issue tracker integration |
23+
| **GitHub** | `_repsources/_github.py` | Issue tracker integration |
24+
25+
Tracker polling logic lives in `_repsources/_trackers.py`.
26+
127
Sign-off Process
228
================
329

‎README.md‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,24 @@ driven Linux kernel development process. It's actually used in the field, but
55
still in a alpha stage: more adjustments are needed to make it better suite the
66
its intended purpose.
77

8+
Regzbot is now part of [KernelCI](https://kernelci.org/), where it contributes
9+
to coordinated regression tracking across the kernel ecosystem. It monitors
10+
mailing lists, bug trackers, and Git repositories so reported regressions do
11+
not slip between first report and a fix in the appropriate kernel tree.
12+
Reporters and developers interact with it through special lines in emails
13+
(`#regzbot` commands) or existing conventions (`Link:` / `Closes:` tags in
14+
commits), keeping overhead minimal.
15+
16+
Kernel development treats regressions with high urgency — fixing them takes
17+
priority over new features. Before automated tracking, regression reports on
18+
mailing lists could disappear in the traffic. Regzbot automates the
19+
bookkeeping: open regressions appear on a public dashboard, periodic mail
20+
summaries list outstanding issues ahead of releases, and `Link:` tags in fix
21+
commits tie into tracked regressions without extra manual steps. See the
22+
kernel documentation for
23+
[reporting regressions](https://docs.kernel.org/admin-guide/reporting-regressions.html) and
24+
[handling regressions](https://docs.kernel.org/process/handling-regressions.html).
25+
826
To get an impression how regression tracking with regzbot is performed in
927
practice, see the
1028
[about page for the Linux kernel regression tracking efforts](https://linux-regtracking.leemhuis.info/about/)
@@ -16,6 +34,22 @@ If you want to interact with regzbot, check out
1634

1735
To install or develop for regzbot, see the [installation documentation](docs/installation.md).
1836

37+
### Public dashboards
38+
39+
| Resource | URL |
40+
|----------|-----|
41+
| Tracked regressions (mainline) | https://linux-regtracking.leemhuis.info/regzbot/mainline/ |
42+
| All views (index) | https://linux-regtracking.leemhuis.info/regzbot/ |
43+
| About the effort | https://linux-regtracking.leemhuis.info/about/ |
44+
| Weekly reports (lore search) | [lore.kernel.org](https://lore.kernel.org/lkml/?q=%22Linux+regressions+report%22+f%3Aregzbot) |
45+
46+
### Documentation
47+
48+
* [Getting started](docs/getting_started.md) — report or fix a tracked regression
49+
* [Reference](docs/reference.md) — full `#regzbot` command syntax
50+
* [Installation](docs/installation.md) — run your own instance
51+
* [Contributing](CONTRIBUTING.md) — codebase layout and development
52+
1953
## Licensing
2054

2155
Rezbot is available under the LGPL 2.1; see the file COPYING for details.

‎docs/getting_started.md‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,35 @@
33
[[_TOC_]]
44

55

6+
## Background
7+
8+
A **regression** is a change in the kernel that breaks something that previously
9+
worked — degraded performance, a feature that stops working, or hardware that is
10+
no longer recognized. Regressions are treated with higher urgency than ordinary
11+
bugs; see the kernel documentation on
12+
[reporting regressions](https://docs.kernel.org/admin-guide/reporting-regressions.html) and
13+
[handling regressions](https://docs.kernel.org/process/handling-regressions.html).
14+
15+
Linux kernel development happens primarily over **email**. A few pieces of this
16+
infrastructure are relevant to regzbot:
17+
18+
* **Mailing lists** — developers communicate through lists organized by
19+
subsystem. `regressions@lists.linux.dev` is specifically for regression
20+
reports.
21+
* **lore.kernel.org** — the public archive of all kernel mailing lists, where
22+
every email has a permanent URL.
23+
* **Message-ID / In-Reply-To / References** — standard email headers that
24+
define threading. Regzbot uses these to tie replies, patches, and fixes to the
25+
original report.
26+
* **`Link:` and `Closes:` tags** — conventions in Git commit messages that
27+
reference mailing list discussions. Regzbot watches these to detect fixes.
28+
29+
Regzbot tracks three Git trees because fixes arrive at different times:
30+
**mainline** (`torvalds/linux.git`), **linux-next** (subsystem work before
31+
mainline), and **stable** (already-shipped kernels). A fix present only in
32+
linux-next shows as "fix incoming" until it reaches the relevant tree.
33+
34+
635
## Why and how to make regzbot track a Linux kernel regression
736

837
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].

‎docs/installation.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,3 +42,23 @@ Now you are ready to run regzbot
4242
./regzbot.sh run
4343

4444
It will generate web reports at `~/.cache/regzbot/websites/`
45+
46+
## available commands
47+
48+
| Command | Purpose |
49+
|---------|---------|
50+
| `setup` | Initialize database, register sources, first Git tree sync |
51+
| `run` | Full update cycle (sources → git → web) |
52+
| `pages` | Regenerate web output only |
53+
| `report` | Build interactive mail reports (operator sends manually) |
54+
| `recheck` | Reprocess specific message IDs |
55+
| `test` | Run offline/online test suites |
56+
57+
## data paths
58+
59+
| Path | Contents |
60+
|------|----------|
61+
| `~/.local/share/regzbot/database.db` | SQLite database (tracked regressions, processed message IDs, repository metadata) |
62+
| `~/.cache/regzbot/gittrees/` | Local Git clones (mainline, next, stable) |
63+
| `~/.cache/regzbot/websites/` | Generated static HTML output |
64+
| `~/.config/regzbot/regzbot.cfg` | Configuration file (API keys) |

0 commit comments

Comments
 (0)