From 33161f2ae4a2eb694fec3c68cbad3579ad74c527 Mon Sep 17 00:00:00 2001 From: huntedbytheirs Date: Mon, 14 Sep 2026 20:49:17 -0400 Subject: [PATCH] docs: add a roadmapped Far section and a ROADMAP.md ROADMAP.md tracks the work past the scaffold: closing the loop, patch series with cover letters, doctor, config and init, more quest sources, more checks, review tracking, and packaging. Its Not planned section records the refusals, so what spectral will not do is as reviewable as what it will. Far specifies two front ends over the same verbs: a TUI session view, and spectral auto for the mechanical half of the loop. Both need the verbs to exist first. The TUI's real cost is that the verbs block and a TUI cannot block its render loop, so it needs the command modules to grow a progress story they do not have yet. The Not planned entry that refused a TUI outright is narrowed to a GUI or web UI, since a TUI is now on the roadmap. Everything the TUI can do still has to stay reachable as a typed command. Also links the roadmap from the README's Where to pitch in section. --- README.md | 3 + ROADMAP.md | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 183 insertions(+) create mode 100644 ROADMAP.md diff --git a/README.md b/README.md index 7b6c5e1..b930488 100644 --- a/README.md +++ b/README.md @@ -207,6 +207,9 @@ easiest place to start. There are no tests yet. The naming rule in `reroll_path` and the recipient split in `lookup` are the two that most want one. +Longer-term work, and the things spectral deliberately will not do, are in +`ROADMAP.md`. + ## Development ```console diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..5a4e84a --- /dev/null +++ b/ROADMAP.md @@ -0,0 +1,180 @@ +# Roadmap + +Where spectral is heading. Nothing here has a date attached. The order is +roughly the order the work is worth doing, and the distance between items +ranges from one afternoon to a design conversation first. + +## Now + +Implement the stubs. `README.md` lists them grouped by how much they +unblock, and `patch submit` is where most people should start, since it is +the only verb that needs no network. + +The milestone worth having is the loop closing: + +```text +quest -> edit -> check -> format -> commit -> create -> submit -> v2 +``` + +One patch through one review cycle without dropping to a shell to run git or +checkpatch by hand. Until that works, nothing else on this page is worth +building. + +Two tests belong here too, both named in the README: the `vN-` naming rule in +`reroll_path`, and the `To:`/`Cc:` split in `lookup`. + +## Next + +### A series instead of a single patch + +Everything today produces one file. Real submissions are often a patch set +with a cover letter, which means: + +- `patch create` writing a numbered set from a commit range, and a + `0000-cover-letter.patch` alongside it +- `patch submit` taking several files at once, which `git send-email` + already supports +- `patch update` re-rolling the whole set, so every file in it moves to v2 + together, the way `git format-patch --reroll-count` does it +- per-patch version numbers, for the same reason + +This is the widest gap between what spectral does and how kernel patches are +actually sent, so it comes first once the stubs are done. + +### spectral doctor + +The README asks for three things before spectral is useful: a kernel tree, +`git send-email` that works, and `qemu-system-x86_64` on `$PATH`. Today you +find out that `send-email` was never configured at the moment you try to +submit, which is the worst time to learn it. + +A `doctor` subcommand would check the tree, the two scripts inside it, the +`send-email` config, qemu, and the resolved paths, then name whichever one is +missing. The `Error` variants for the tree cases already exist. + +### Config file and init + +`src/config.rs` carries the TODO. Two additions: + +- `~/.config/spectral/config.toml` holding the tree path, the patch + directory, your send-email identity, and any addresses you always want + CC'd. The environment variable keeps winning over the file. +- `spectral init`, to clone a tree or point at one you already have and + verify it, so nobody has to read the Configuration section twice. + +## Later + +### More quest sources + +`QuestSource` exists so this costs one impl per source. Candidates, roughly +in order of how useful they look: syzbot, the kernel-janitors TODO list, and +lore.kernel.org threads marked as needing work. + +Worth doing at the same time: remembering what quest has already shown you. A +random picker that keeps handing back the same bug is worse than no picker. + +### More checks + +`patch check` runs checkpatch today. The kernel holds more opinions than +that, and each of these is a flag on the existing verb rather than a new one: +sparse through `make C=1`, `make W=1` for the extra warnings, and +`dt_binding_check` for device tree patches. + +`kernel test` could grow kselftests and a syzkaller run, which answer a +different question from "did it boot". + +### Review tracking + +Submitting is half the loop. The other half is waiting, and spectral has +nothing to say about it today. A `spectral patch status` could read the +thread for a patch you sent, report the tags it found (`Reviewed-by:`, +`Tested-by:`, `Acked-by:`), and let `patch update` fold them in when you +re-roll. + +That needs spectral to record what it sent and where, which nothing does +today. Where that state lives is the design question to settle before the +feature. + +### Packaging and polish + +- shell completions through `clap_complete`, and a man page through + `clap_mangen`, once the command surface stops moving +- the three gates from the README wired into CI, so they stop being + something a contributor has to remember +- release packaging: crates.io, plus an AUR package for the Arch systems + this has been developed on + +## Far + +Both of these are front ends over verbs that do not exist yet, so neither is +worth starting before `Now` and most of `Next` are done. They are listed so +the intent is on record before anyone starts building either one. + +### A TUI + +A session view over the same verbs, for the loop rather than for one command +at a time. The panes that matter: + +- the issue you are working on, from `kernel quest`, with its URL +- the tree: branch, dirty files, and what checkpatch reports +- the patch files on disk and which revision each one is at +- the recipients for the selected patch, so you see who is being mailed + before you send rather than after +- the qemu serial console, streaming, while `kernel test` runs + +The constraint that keeps it honest: the TUI calls the same functions the +verbs call. Nothing is implemented twice, and every action in it stays +available as a typed command. `src/cli.rs` and the rule that command modules +return what they produced are what make that possible. + +The cost is that the verbs block. `git`, `checkpatch.pl`, `make`, and qemu +all run synchronously to completion, and a TUI cannot block its render loop. +The work has to move onto background tasks that report progress back through +a channel, which means the command modules need a progress story they do not +have today. That is the actual work in the TUI, and it is why the TUI comes +after the verbs rather than alongside them. + +`ratatui` is the obvious crate for it. + +### spectral auto + +This automates the mechanical part of the loop, not the judgment. Deciding +what to fix and writing the fix are yours. Running checkpatch twice, creating +the patch, and looking up maintainers are not. + +So `auto` walks the chain to a halt point and stops there: + +```console +$ spectral auto # dirty tree to a patch that is ready to send +$ spectral auto --stop-at create # or stop earlier +``` + +It never sends mail unless told to. Submitting to a mailing list is the one +step that rerunning a command cannot undo, so `auto` stops one step short by +default and shows the recipients and the command line, the same way `patch +submit --dry-run` does. + +Once review tracking lands, `auto` picks up the more useful half of its job: +find the thread for the patch you sent, collect the tags, re-roll to vN, +recompute the recipients, then stop at the same place. That is most of what a +v2 cycle consists of. + +It has to be idempotent. Running it twice on a tree that has not changed +should not produce a v3. `reroll_path` is already specified as a no-op at the +same revision, and `auto` inherits that requirement. + +It depends on the verbs, on `doctor` to fail fast instead of halfway, and on +the config and state files the sections above describe. + +## Not planned + +- Reimplementing checkpatch.pl or get_maintainer.pl, or shipping copies of + them. They come from your tree on purpose, so spectral cannot end up + disagreeing with the kernel about style or maintainers. +- Managing your tree's remotes, branches, or rebases. spectral reads git + state; it does not take the repository over. +- A GUI or a web UI. The TUI in `Far` is a front end over the same verbs, and + anything it can do stays reachable by typing the command yourself. A + graphical app would mean building those verbs a second time. +- Answering review mail for you. Reporting the tags in a thread is useful; + writing replies in your name is not.