diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e78241b..c838e15 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,3 +1,29 @@ +Codebase overview +================= + +| Area | Files | Role | +|------|-------|------| +| Core + DB | `__init__.py` | Regression model, `GitTree`/`GitBranch`, `ReportThread`, `run()`/`generate_web()`/`report()` | +| Bot commands | `_rbcmd.py` | Parse and execute `#regzbot` subcommands | +| CLI | `commandl.py` | argparse-based subcommands | +| Web export | `export_web.py` | Static HTML generation | +| Mail reports | `export_mail.py` | Weekly text/mail report layout | +| CSV export | `export_csv.py` | CSV-oriented export (tests) | +| Lore ingestion | `_repsources/_lore.py` | NNTP and HTTPS access to lore archives | +| Tracker sources | `_bugzilla.py`, `_gitlab.py`, `_github.py`, `_generic.py` | Tracker-specific API integrations | +| Tests | `testing_online.py`, `testing_offline.py`, `testing_trackers.py`, `testdata/*` | Offline/online/tracker tests/expected results | + +Report sources (pluggable backends): + +| Source | Implementation | Notes | +|--------|----------------|-------| +| **lore** (NNTP/HTTPS) | `_repsources/_lore.py` | Primary source; kernel mailing list archives | +| **bugzilla.kernel.org** | `_repsources/_bugzilla.py` | REST API with API key | +| **GitLab** | `_repsources/_gitlab.py` | Issue tracker integration | +| **GitHub** | `_repsources/_github.py` | Issue tracker integration | + +Tracker polling logic lives in `_repsources/_trackers.py`. + Sign-off Process ================ diff --git a/README.md b/README.md index a3ec101..8c43c71 100644 --- a/README.md +++ b/README.md @@ -5,6 +5,24 @@ driven Linux kernel development process. It's actually used in the field, but 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 +to coordinated regression tracking across the kernel ecosystem. It monitors +mailing lists, bug trackers, and Git repositories so reported regressions do +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. + +Kernel development treats regressions with high urgency — fixing them takes +priority over new features. Before automated tracking, regression reports on +mailing lists could disappear in the traffic. Regzbot automates the +bookkeeping: open regressions appear on a public dashboard, periodic mail +summaries list outstanding issues ahead of releases, and `Link:` tags in fix +commits tie into tracked regressions without extra manual steps. See the +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). + To get an impression how regression tracking with regzbot is performed in practice, see the [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 To install or develop for regzbot, see the [installation documentation](docs/installation.md). +### Public dashboards + +| Resource | URL | +|----------|-----| +| Tracked regressions (mainline) | https://linux-regtracking.leemhuis.info/regzbot/mainline/ | +| All views (index) | https://linux-regtracking.leemhuis.info/regzbot/ | +| About the effort | https://linux-regtracking.leemhuis.info/about/ | +| Weekly reports (lore search) | [lore.kernel.org](https://lore.kernel.org/lkml/?q=%22Linux+regressions+report%22+f%3Aregzbot) | + +### Documentation + +* [Getting started](docs/getting_started.md) — report or fix a tracked regression +* [Reference](docs/reference.md) — full `#regzbot` command syntax +* [Installation](docs/installation.md) — run your own instance +* [Contributing](CONTRIBUTING.md) — codebase layout and development + ## Licensing Rezbot is available under the LGPL 2.1; see the file COPYING for details. diff --git a/docs/getting_started.md b/docs/getting_started.md index 5c1af74..eb12762 100644 --- a/docs/getting_started.md +++ b/docs/getting_started.md @@ -3,6 +3,35 @@ [[_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). + +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. + + ## 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]. diff --git a/docs/installation.md b/docs/installation.md index 5e3620d..55dfe28 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -42,3 +42,23 @@ Now you are ready to run regzbot ./regzbot.sh run It will generate web reports at `~/.cache/regzbot/websites/` + +## available commands + +| Command | Purpose | +|---------|---------| +| `setup` | Initialize database, register sources, first Git tree sync | +| `run` | Full update cycle (sources → git → web) | +| `pages` | Regenerate web output only | +| `report` | Build interactive mail reports (operator sends manually) | +| `recheck` | Reprocess specific message IDs | +| `test` | Run offline/online test suites | + +## data paths + +| Path | Contents | +|------|----------| +| `~/.local/share/regzbot/database.db` | SQLite database (tracked regressions, processed message IDs, repository metadata) | +| `~/.cache/regzbot/gittrees/` | Local Git clones (mainline, next, stable) | +| `~/.cache/regzbot/websites/` | Generated static HTML output | +| `~/.config/regzbot/regzbot.cfg` | Configuration file (API keys) |