thunderbird-patch-review

Easy-to-use patch review interface for Thunderbird

Contribute: ~marcc/thunderbird-review-plugin@lists.sr.ht

git clone git://mccd.space/thunderbird-patch-review

patch-review.1 (6952B)

 .TH PATCH\-REVIEW 1 "July 2026" "patch-review 0.1.0" "Thunderbird Patch Review"
 .SH NAME
 patch\-review \- review git patches from email inside Thunderbird
 .SH SYNOPSIS
 A Thunderbird MailExtension.
 Open a patch email, press
 .BR Review ,
 comment on hunks, send the review as a mailing-list reply, and apply the
 series to a local repository with
 .BR git\-am (1).
 .SH DESCRIPTION
 .B patch\-review
 brings a review interface to git-by-email workflows
 .RB ( git\-send\-email (1)
 style).
 When the selected messages (or thread) look like a patch \(em a
 .B [PATCH]
 subject tag or a unified diff in the body \(em the
 .B Review
 button in the main toolbar becomes active.
 It opens a dedicated review tab that shows the whole series:
 cover letter, per-patch commit messages, and every file and hunk rendered
 as a colored diff.
 Within replaced lines, the span that actually changed gets a stronger
 highlight, computed from the common prefix and suffix of each
 deleted/added line pair.
 .PP
 Clicking a diff line attaches an inline comment to it; comments are saved
 as drafts (keyed by Message-ID) and survive restarting Thunderbird.
 .B Send review
 turns the comments of each commented patch into one plain-text reply-to-all,
 quoting the relevant hunks kernel-style with the comments interleaved
 unquoted below the lines they target, and sends the replies immediately;
 the draft comments are then cleared and the review tab closes.
 The attached drop-down offers
 .I "Preview in compose"
 instead, which leaves the reply drafts open in compose windows.
 A reply that fails to send also stays open, so nothing is lost.
 .B Apply series
 runs
 .B git am \-\-3way
 on the raw patch messages in the configured repository.
 On conflict
 .B git am \-\-abort
 is run and its output reported, leaving the repository untouched.
 Its drop-down offers
 .I "Modify and apply"
 \(em apply, then open the touched files in your editor \(em and
 .I "Download patchset"
 \(em save the raw series as one mbox file, ready for
 .BR "git am" .
 .SH INSTALLATION
 Package the extension as an
 .B .xpi
 and install it via the Add-ons Manager gear menu
 .RB ( "Install Add-on From File..." ).
 From the project root:
 .RS
 .PP
 (cd extension && zip -qrX ../patch\-review.xpi .)
 .RE
 .PP
 The subshell runs the
 .BR zip (1)
 from inside
 .I extension/
 so the archive holds
 .B manifest.json
 at its root, not under
 .IR extension/ .
 .BR git (1)
 is a dependency (for
 .BR Apply ).
 For development, instead pick
 .IR "Tools \(-> Developer Tools \(-> Debug Add\-ons \(-> Load Temporary Add\-on..." ,
 and select
 .BR extension/manifest.json ;
 it is dropped on restart.
 .SH CONFIGURATION
 Open the extension's preferences:
 .TP
 .B Editor command
 Run from the repository after a successful apply, with the changed files as
 arguments.
 Use a non-blocking GUI-capable command such as
 .B code \-n
 or
 .BR "emacsclient \-n" ;
 a bare terminal editor has no terminal to open in.
 Empty means
 .BR $EDITOR .
 .TP
 .B Apply strategy
 .B git am \-\-3way
 (default) or plain
 .BR "git am" .
 .TP
 .B Repository mappings
 Substring matches against a patch's List-Id header or sender, mapped to an
 absolute repository path.
 When no mapping matches, the last path a series was applied to is used;
 it is remembered until changed.
 .PP
 Repository paths can be chosen with the
 .B Browse
 button, which opens Thunderbird's native directory chooser; the path field
 stays editable either way.
 .SH PERMISSIONS
 The extension requests the fewest permissions it needs;
 none are granted to remote content.
 .TP
 .B messagesRead
 Reads the selected message and its sibling patches in the same folder
 (subject, author, body) to build the review.
 .TP
 .B accountsRead
 Resolves the default identity of the account that owns the reviewed
 message, for the From-address label and send-as.
 .TP
 .B storage
 Persists draft comments (keyed by Message-ID) across restarts,
 plus the editor command, apply strategy, repo mappings, and the last
 applied repository path.
 .TP
 .BR compose , " (compose.send)"
 Opens reply-to-all compose windows from
 .B "Send review"
 and sends them in
 .I "Send now"
 mode.
 Without
 .B compose.send
 the review can only be previewed in compose, never sent.
 .TP
 .B downloads
 Writes the
 .I "Download patchset"
 .B .mbox
 to disk.
 .TP
 .B tabs
 Opens the review tab and removes it after a successful send.
 .PP
 The privileged
 .BR Apply ,
 .IR "Browse... " ,
 and
 .I "Open editor"
 code does not use a Mozilla permission:
 it is a WebExtension Experiment
 .RB ( experiment_apis.patchHost )
 shipped inside the XPI and runs only when the extension is loaded.
 .SH SOURCEHUT INTEGRATION
 When the series arrives via a sourcehut mailing list (a
 .B lists.sr.ht
 address in the List-Id or recipients), the review tab shows a
 .B "set status"
 checkbox with the patchset states sourcehut understands:
 APPROVED, NEEDS_REVISION, REJECTED, PROPOSED, SUPERSEDED, APPLIED.
 When enabled, the first reply of the review carries an
 .B X\-Sourcehut\-Patchset\-Update
 header with the chosen status, which sourcehut applies to the patchset.
 A status can also be sent without any line comments \(em
 .B Send review
 then sends a single, empty reply to the cover letter (or first patch)
 carrying just the header.
 .SH REVIEW WORKFLOW
 .nf
 1. Select any message of the series \(em or the whole
    thread \(em and press Review in the main toolbar.
 2. The tab collects the sibling patches from the same folder
    (same series tag, version, and patch count).
 3. Click lines, write comments; Ctrl+Enter saves.
    "Comment on patch" attaches a general remark instead.
 4. Send review: one reply per commented patch, sent
    immediately (or use the drop-down to preview first).
 5. Apply series: git am into the mapped repository,
    then Open editor on the touched files.
 .fi
 .SH FILES
 .TP
 .I extension/
 The MailExtension (manifest v2, vanilla ES modules, no build step).
 .TP
 .I extension/api/patchHost/
 The privileged part (a WebExtension Experiment): runs
 .BR git\-am (1)
 and the editor through Thunderbird's Subprocess API and shows the
 directory chooser with nsIFilePicker.
 Everything outside this directory runs as ordinary sandboxed WebExtension
 code.
 .TP
 .I tests/
 .B node tests/run.mjs
 exercises the pure modules (subject parsing, diff parsing, reply
 formatting) against fixtures generated by
 .BR git\-format\-patch (1),
 and checks the experiment's manifest wiring.
 Regenerate fixtures with
 .BR tests/gen\-fixtures.sh .
 .SH CAVEATS
 Patches arriving as attachments, HTML-only mail, and reviewing from a git
 worktree preview are not supported yet.
 Series collection searches the folder of the opened message only.
 .SH SEE ALSO
 .PP
 The introductory post can be found at
 .MT https://mccd.space/posts/26-07-18/3-patch-review-tool-for-thunderbird
 .ME
 .SH CONTRIBUTING
 Disclaimer: this plugin was vibe coded \(em written by an AI agent under
 human direction.
 .PP
 Contributions and bug reports go to the mailing list:
 .MT ~marcc/thunderbird\-review\-plugin@lists.sr.ht
 .ME 
 .SH AUTHOR
 Marc Coquand
 .MT marc@coquand.email
 .ME