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.