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
| Log | Files | Refs | README | LICENSE |
README (7363B)
1 PATCH-REVIEW(1) Thunderbird Patch Review PATCH-REVIEW(1)
2
3 NAME
4 patch-review - review git patches from email inside Thunderbird
5
6 SYNOPSIS
7 A Thunderbird MailExtension. Open a patch email, press Review, comment
8 on hunks, send the review as a mailing-list reply, and apply the series
9 to a local repository with git-am(1).
10
11 DESCRIPTION
12 patch-review brings a review interface to git-by-email workflows
13 (git-send-email(1) style). When the selected messages (or thread) look
14 like a patch -- a [PATCH] subject tag or a unified diff in the body --
15 the Review button in the main toolbar becomes active. It opens a
16 dedicated review tab that shows the whole series: cover letter, per-
17 patch commit messages, and every file and hunk rendered as a colored
18 diff. Within replaced lines, the span that actually changed gets a
19 stronger highlight, computed from the common prefix and suffix of each
20 deleted/added line pair.
21
22 Clicking a diff line attaches an inline comment to it; comments are
23 saved as drafts (keyed by Message-ID) and survive restarting
24 Thunderbird. Send review turns the comments of each commented patch
25 into one plain-text reply-to-all, quoting the relevant hunks kernel-
26 style with the comments interleaved unquoted below the lines they
27 target, and sends the replies immediately; the draft comments are then
28 cleared and the review tab closes. The attached drop-down offers
29 Preview in compose instead, which leaves the reply drafts open in
30 compose windows. A reply that fails to send also stays open, so
31 nothing is lost. Apply series runs git am --3way on the raw patch
32 messages in the configured repository. On conflict git am --abort is
33 run and its output reported, leaving the repository untouched. Its
34 drop-down offers Modify and apply -- apply, then open the touched files
35 in your editor -- and Download patchset -- save the raw series as one
36 mbox file, ready for git am.
37
38 INSTALLATION
39 Package the extension as an .xpi and install it via the Add-ons Manager
40 gear menu (Install Add-on From File...). From the project root:
41
42 (cd extension && zip -qrX ../patch-review.xpi .)
43
44 The subshell runs the zip(1) from inside extension/ so the archive
45 holds manifest.json at its root, not under extension/. git(1) is a
46 dependency (for Apply). For development, instead pick Tools ->
47 Developer Tools -> Debug Add-ons -> Load Temporary Add-on..., and
48 select extension/manifest.json; it is dropped on restart.
49
50 CONFIGURATION
51 Open the extension's preferences:
52
53 Editor command
54 Run from the repository after a successful apply, with the
55 changed files as arguments. Use a non-blocking GUI-capable
56 command such as code -n or emacsclient -n; a bare terminal
57 editor has no terminal to open in. Empty means $EDITOR.
58
59 Apply strategy
60 git am --3way (default) or plain git am.
61
62 Repository mappings
63 Substring matches against a patch's List-Id header or sender,
64 mapped to an absolute repository path. When no mapping matches,
65 the last path a series was applied to is used; it is remembered
66 until changed.
67
68 Repository paths can be chosen with the Browse button, which opens
69 Thunderbird's native directory chooser; the path field stays editable
70 either way.
71
72 PERMISSIONS
73 The extension requests the fewest permissions it needs; none are
74 granted to remote content.
75
76 messagesRead
77 Reads the selected message and its sibling patches in the same
78 folder (subject, author, body) to build the review.
79
80 accountsRead
81 Resolves the default identity of the account that owns the
82 reviewed message, for the From-address label and send-as.
83
84 storage
85 Persists draft comments (keyed by Message-ID) across restarts,
86 plus the editor command, apply strategy, repo mappings, and the
87 last applied repository path.
88
89 compose, (compose.send)
90 Opens reply-to-all compose windows from Send review and sends
91 them in Send now mode. Without compose.send the review can only
92 be previewed in compose, never sent.
93
94 downloads
95 Writes the Download patchset .mbox to disk.
96
97 tabs Opens the review tab and removes it after a successful send.
98
99 The privileged Apply, Browse... , and Open editor code does not use a
100 Mozilla permission: it is a WebExtension Experiment
101 (experiment_apis.patchHost) shipped inside the XPI and runs only when
102 the extension is loaded.
103
104 SOURCEHUT INTEGRATION
105 When the series arrives via a sourcehut mailing list (a lists.sr.ht
106 address in the List-Id or recipients), the review tab shows a set
107 status checkbox with the patchset states sourcehut understands:
108 APPROVED, NEEDS_REVISION, REJECTED, PROPOSED, SUPERSEDED, APPLIED.
109 When enabled, the first reply of the review carries an
110 X-Sourcehut-Patchset-Update header with the chosen status, which
111 sourcehut applies to the patchset. A status can also be sent without
112 any line comments -- Send review then sends a single, empty reply to
113 the cover letter (or first patch) carrying just the header.
114
115 REVIEW WORKFLOW
116 1. Select any message of the series -- or the whole
117 thread -- and press Review in the main toolbar.
118 2. The tab collects the sibling patches from the same folder
119 (same series tag, version, and patch count).
120 3. Click lines, write comments; Ctrl+Enter saves.
121 "Comment on patch" attaches a general remark instead.
122 4. Send review: one reply per commented patch, sent
123 immediately (or use the drop-down to preview first).
124 5. Apply series: git am into the mapped repository,
125 then Open editor on the touched files.
126
127 FILES
128 extension/
129 The MailExtension (manifest v2, vanilla ES modules, no build
130 step).
131
132 extension/api/patchHost/
133 The privileged part (a WebExtension Experiment): runs git-am(1)
134 and the editor through Thunderbird's Subprocess API and shows
135 the directory chooser with nsIFilePicker. Everything outside
136 this directory runs as ordinary sandboxed WebExtension code.
137
138 tests/ node tests/run.mjs exercises the pure modules (subject parsing,
139 diff parsing, reply formatting) against fixtures generated by
140 git-format-patch(1), and checks the experiment's manifest
141 wiring. Regenerate fixtures with tests/gen-fixtures.sh.
142
143 CAVEATS
144 Patches arriving as attachments, HTML-only mail, and reviewing from a
145 git worktree preview are not supported yet. Series collection searches
146 the folder of the opened message only.
147
148 SEE ALSO
149 The introductory post can be found at
150 <https://mccd.space/posts/26-07-18/3-patch-review-tool-for-thunderbird>
151
152 CONTRIBUTING
153 Disclaimer: this plugin was vibe coded -- written by an AI agent under
154 human direction.
155
156 Contributions and bug reports go to the mailing list:
157 <~marcc/thunderbird-review-plugin@lists.sr.ht>
158
159 AUTHOR
160 Marc Coquand <marc@coquand.email>
161
162 patch-review 0.1.0 July 2026 PATCH-REVIEW(1)