spectral/ROADMAP.md

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

Done. Every verb runs, and the loop closes end to end: a commit went from a working tree to a git send-email plan, then round again as v2 threaded off the original. README.md has the walkthrough and the acceptance evidence.

The milestone was this:

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. The one step that stays yours on purpose is git add: patch commit commits what you staged, because sweeping a dirty tree into a kernel patch is a review comment nobody asked for.

The two tests this section named are in place: the vN- naming rule in reroll_path, and the To:/Cc: split in lookup, the second of which is also asserted against the host's real get_maintainer.pl in an opt-in test.

rg -n 'todo!' src/ finds nothing. What is left overall is the three gaps in the README's What is not proven, and Later and Far below.

Next

All three landed, in this order. The sections below say what each one does now.

A series instead of a single patch

Done. patch create xhci-port-rearm --range master..HEAD --cover-letter "<blurb>" writes a numbered set through git format-patch, cover letter included; patch submit takes a directory or several files and sends them in one git send-email invocation; patch update <dir> re-rolls the whole set through --reroll-count, so every file moves to vN together, and the superseded files go only once the new revision is complete. The blurb's first line becomes the cover letter's subject, and leaving --cover-letter off leaves git's template in place, which git send-email refuses.

A series.toml in the directory records the range it was generated for: both ends as hashes, the revision, the files, and the blurb. The range is what makes a re-roll safe, since regenerating base..HEAD instead would quietly pick up every commit that landed on the branch since create and mail it with the set.

spectral doctor

Done. It checks, in the order a first run hits them: the tree path and where it came from, that the path is a kernel tree, scripts/checkpatch.pl, scripts/get_maintainer.pl, MAINTAINERS, git, git send-email, a sender identity, whether any mail route is configured, qemu on $PATH, that the patch directory is writable, and whether a config file exists.

One line per check with the fix under it, and the summary names the first hard failure. Exit 1 when something hard failed; a missing qemu or a missing mail route warns and keeps exit 0, because --dry-run is where the loop actually stops on this machine.

Config file and init

Done. ~/.config/spectral/config.toml (or $XDG_CONFIG_HOME), holding the tree path, the patch directory, always-CC addresses and a send-email identity. Precedence is the environment over the file over the built-in default, and $SPECTRAL_PATCH_DIR joined $SPECTRAL_KERNEL for symmetry.

spectral init --tree <path> verifies a tree, or --clone <url> [--depth N] fetches one, then writes the config. A second run with the same tree says so and writes nothing; a run that would change an existing answer is refused until --force. Malformed TOML, an unknown key and a relative path are named errors rather than surprises three commands later.

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. A series already carries series.toml, which is the smallest version of that record: it is what a re-roll reads.

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:

$ 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. doctor and the config file are here now; the state file is what review tracking still has to decide.

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.