Skip to content

Commit c719081

Browse files
knurdknurd
authored
Merge pull request #21 from alanpeixinho/main
docs: add high-level overview of regzbot
2 parents d0a9451 + 24d2c7d commit c719081

4 files changed

Lines changed: 138 additions & 15 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: 67 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,76 @@ 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-
To get an impression how regression tracking with regzbot is performed in
9-
practice, see the
10-
[about page for the Linux kernel regression tracking efforts](https://linux-regtracking.leemhuis.info/about/)
11-
and
12-
[the list of regressions regzbot currently tracks](https://linux-regtracking.leemhuis.info/regzbot/mainline/).
13-
If you want to interact with regzbot, check out
14-
[getting started with regzbot](docs/getting_started.md) or the bots
15-
[reference documentation](docs/reference.md).
8+
Anyone can make regzbot track a regression by adding a command such as
9+
`#regzbot introduced: <commit-id>` to an email sent to the Linux kernel mailing
10+
list (LKML) or `regressions@lists.linux.dev`. Regzbot later notices fixes
11+
automatically when a change points to the report using existing conventions such
12+
as `Link:` or `Closes:` tags, which avoids extra work for developers. If those
13+
links were forgotten, or if more details need to be recorded, the documentation
14+
below lists other `#regzbot` commands.
1615

17-
To install or develop for regzbot, see the [installation documentation](docs/installation.md).
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, and periodic mail
20+
summaries list outstanding issues ahead of releases. See the kernel
21+
documentation for
22+
[reporting regressions](https://docs.kernel.org/admin-guide/reporting-regressions.html) and
23+
[handling regressions](https://docs.kernel.org/process/handling-regressions.html).
1824

19-
## Licensing
25+
## Scope
2026

21-
Rezbot is available under the LGPL 2.1; see the file COPYING for details.
27+
Regzbot focuses on Linux kernel regressions in mainline, the latest mainline
28+
release, and the stable series derived from it. Tracking is best-effort:
29+
regzbot helps reports stay visible and helps connect fixes to reports, but it
30+
does not guarantee every regression is tracked or fixed.
2231

23-
Regzbot was started by Thorsten Leemhuis as part of a project that has received
24-
funding from the European Union’s Horizon 2020 research and innovation
32+
It is not intended to track ordinary bugs, monitor every bug tracker used by
33+
kernel subsystems, or produce complete regression statistics.
34+
35+
The public dashboards below show regression tracking in practice: start with
36+
the mainline regression list to see currently tracked issues, while this README
37+
gives background on the Linux kernel regression tracking effort. The
38+
documentation links cover reporting, fixing, installation, and development.
39+
40+
### Public dashboards
41+
42+
| Resource | URL |
43+
|----------|-----|
44+
| Tracked regressions (mainline) | https://linux-regtracking.leemhuis.info/regzbot/mainline/ |
45+
| All views (index) | https://linux-regtracking.leemhuis.info/regzbot/ |
46+
| About the effort | [README](README.md) |
47+
| Weekly reports (lore search) | [lore.kernel.org](https://lore.kernel.org/lkml/?q=%22Linux+regressions+report%22+f%3Aregzbot) |
48+
49+
### Documentation
50+
51+
* [Getting started](docs/getting_started.md) — report, fix, or update a tracked regression
52+
* [Reference](docs/reference.md) — full `#regzbot` command syntax
53+
* [Installation](docs/installation.md) — run your own instance
54+
* [Contributing](CONTRIBUTING.md) — codebase layout and development
55+
56+
## History
57+
58+
Linux had no formal regression tracking for most of its history. Rafael J.
59+
Wysocki tracked regressions for several years in the 2000s, but that effort
60+
ended in 2012.
61+
62+
Thorsten Leemhuis restarted the work manually in 2017. That showed the value of
63+
regression tracking, but also that manual tracking did not scale.
64+
65+
Development of regzbot started in 2021, and Thorsten began tracking
66+
regressions with it later that year.
67+
68+
## Licensing and funding
69+
70+
Regzbot is available under the LGPL 2.1; see the file COPYING for details.
71+
72+
Regzbot was started by Thorsten Leemhuis as part of a project that received
73+
funding from the European Union's Horizon 2020 research and innovation
2574
programme under grant agreement No 871528.
2675

27-
Since May 2022 regzbot development and the Linux kernel regression tracking
28-
efforts performed by Thorsten are supported with funds from Meta.
76+
Starting in May 2022, regzbot development and the Linux kernel regression
77+
tracking efforts performed by Thorsten were supported with funds from Meta for
78+
about two years. Regzbot is now part of [KernelCI](https://kernelci.org/),
79+
where it contributes to coordinated regression tracking across the kernel
80+
ecosystem and receives funding for current development.

‎docs/getting_started.md‎

Lines changed: 25 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,19 @@
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+
This guide focuses on the `#regzbot` commands reporters and developers can use
16+
to add or update tracked regressions.
17+
18+
619
## Why and how to make regzbot track a Linux kernel regression
720

821
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
2639
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.
2740

2841

42+
## How to help keep tracking accurate
43+
44+
If a tracked issue turns out not to be a regression, if discussion moved
45+
elsewhere, or if important details such as the title or introduced range are
46+
wrong, please reply publicly and include the appropriate `#regzbot` command.
47+
That keeps the public record clear and helps regzbot show useful status.
48+
49+
Developers do not need to CC individual regression trackers on every follow-up.
50+
Keep `regressions@lists.linux.dev` in the loop and use `Link:` or `Closes:`
51+
tags that point to the report when posting fixes.
52+
53+
2954
## More regzbot features relevant for both reporters and developers
3055

3156

‎docs/installation.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -47,6 +47,26 @@ Now you are ready to run regzbot
4747

4848
It will generate web reports at `~/.cache/regzbot/websites/`
4949

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

5272
### Ruff

0 commit comments

Comments
 (0)