logo

drewdevault.com

[mirror] blog and personal website of Drew DeVault git clone https://hacktivis.me/git/mirror/drewdevault.com.git

Code-review-with-aerc.md (7021B)

    

  1. ---
  2. title: Code review at the speed of email
  3. date: 2022-07-25
  4. ---
  6. I'm a big proponent of the email workflow for patch submission and code review.
  7. I have previously published some content ([How to use git.sr.ht's send-email
  8. feature][0], [Forks & pull requests vs email][1], [git-send-email.io][2]) which
  9. demonstrates the contributor side of this workflow, but it's nice to illustrate
  10. the advantages of the maintainer workflow as well. For this purpose, I've
  11. recorded a short video demonstrating how I manage code review as an
  12. email-oriented maintainer.
  14. *Disclaimer: I am the founder of [SourceHut][3], a platform built on this
  15. workflow which competes with platforms like GitHub and GitLab. This article's
  16. perspective is biased.*
  18. [0]: https://spacepub.space/w/no6jnhHeUrt2E5ST168tRL
  19. [1]: https://spacepub.space/w/3JhBcvEYbminv8ji4k84gx
  20. [2]: https://git-send-email.io
  21. [3]: https://sourcehut.org
  23. <iframe title="Code review at the speed of email" src="https://spacepub.space/videos/embed/385c414a-2bdc-4bf3-82a0-76fcb15093e9" allowfullscreen="" sandbox="allow-same-origin allow-scripts allow-popups" width="560" height="315" frameborder="0"></iframe>
  25. <p class="text-center">
  26.   <em>
  27.   This blog post provides additional material to supplement this video, and also
  28.   includes all of the information from the video itself. For those who prefer
  29.   reading over watching, you can just stick to reading this blog post. Or, you
  30.   can watch the video and skim the post. Or you can just do something else! When
  31.   was the last time you called your grandmother?
  32.   </em>
  33. </p>
  35. With hundreds of hours of review experience on GitHub, GitLab, and SourceHut, I
  36. can say with confidence the email workflow allows me to work much faster than
  37. any of the others. I can review small patches in seconds, work quickly with
  38. multiple git repositories, easily test changes and make tweaks as necessary,
  39. rebase often, and quickly chop up and provide feedback for larger patches.
  40. Working my way through a 50-email patch queue usually takes me about 20 minutes,
  41. compared to an hour or more for the same number of merge requests.
  43. This workflow also works entirely offline. I can read and apply changes locally,
  44. and even reply with feedback or to thank contributors for their patch. My mail
  45. setup automatically downloads mail from IMAP using [isync][4] and outgoing mails
  46. are queued with [postfix][5] until the network is ready. I have often worked
  47. through my patch queue on an airplane or a train with spotty or non-functional
  48. internet access without skipping a beat. Working from low-end devices like a
  49. Pinebook or a phone are also no problem &mdash; aerc is very lightweight in the
  50. terminal and the SourceHut web interface is [much lighter & faster][6] than any
  51. other web forge.
  53. [4]: https://isync.sourceforge.io/
  54. [5]: http://www.postfix.org/
  55. [6]: https://forgeperf.org
  57. The centerpiece of my setup is an email client I wrote specifically for software
  58. development using this workflow: [aerc][7].[^1] The stock configuration of aerc
  59. is pretty good, but I make a couple of useful additions specifically for
  60. development on SourceHut. Specifically, I add a few keybindings to
  61. `~/.config/aerc/binds.conf`:
  63. [7]: https://aerc-mail.org/
  65. [^1]: Don't want to switch from your current mail client? Tip: You can use more than one 🙂 I usually fire up multiple aerc instances in any case, one "main" instance and more ephemeral processes for working in specific projects. The startup time is essentially negligible, so this solution is very cheap and versatile.
  67. ```
  68. [messages]
  69. ga = :flag<Enter>:pipe -mb git am -3<Enter>
  70. gp = :term git push<Enter>
  71. gl = :term git log<Enter>
  73. rt = :reply -a -Tthanks<Enter>
  74. Rt = :reply -qa -Tquoted_thanks<Enter>
  76. [compose::review]
  77. V = :header -f X-Sourcehut-Patchset-Update NEEDS_REVISION<Enter>
  78. A = :header -f X-Sourcehut-Patchset-Update APPLIED<Enter>
  79. R = :header -f X-Sourcehut-Patchset-Update REJECTED<Enter>
  80. ```
  82. The first three commands, ga, gp, and gl, are for invoking git commands. "ga"
  83. applies the current email as a patch, using [git am][8], and "gp" simply runs
  84. git push. "gl" is useful for quickly reviewing the git log. ga also flags the
  85. email so that it shows up in the UI as having been applied, which is useful as
  86. I'm jumping all over a patch queue. I also make liberal use of \\ (:filter) to
  87. filter my messages to patches applicable to specific projects or goals.
  89. [8]: https://git-scm.com/docs/git-am
  91. rt and Rt use aerc templates installed at `~/.config/aerc/templates/` to reply
  92. to emails after I've finished reviewing them. The "thanks" template is:
  94. ```
  95. X-Sourcehut-Patchset-Update: APPLIED
  97. Thanks!
  99. {{exec "{ git remote get-url --push origin; git reflog -2 origin/master --pretty=format:%h | xargs printf '%s\n' | tac; } | xargs printf 'To %s\n   %s..%s  master -> master'" ""}}
  100. ```
  102. And quoted\_thanks is:
  104. ```
  105. X-Sourcehut-Patchset-Update: APPLIED
  107. Thanks!
  109. {{exec "{ git remote get-url --push origin; git reflog -2 origin/master --pretty=format:%h | xargs printf '%s\n' | tac; } | xargs printf 'To %s\n   %s..%s  master -> master'" ""}}
  111. On {{dateFormat (.OriginalDate | toLocal) "Mon Jan 2, 2006 at 3:04 PM MST"}}, {{(index .OriginalFrom 0).Name}} wrote:
  112. {{wrapText .OriginalText 72 | quote}}
  113. ```
  115. Both of these add a magic "X-Sourcehut-Patchset-Update" header, which updates
  116. the status of the patch on the mailing list. They also include a shell pipeline
  117. which adds some information about the last push from this repository, to help
  118. the recipient understand what happened to their patch. I often make some small
  119. edits to request the user follow-up with a ticket for some future work, or add
  120. other timely comments. The second template, quoted\_reply, is also particularly
  121. useful for this: it quotes the original message so I can reply to specific parts
  122. of it, in the commit message, timely commentary, or the code itself, often
  123. pointing out parts of the code that I made some small tweaks to before applying.
  125. And that's basically it! You can browse all of my dotfiles [here][9] to see more
  126. details about my system configuration. With this setup I am able to work my way
  127. through a patch queue easier and faster than ever before. That's why I like the
  128. email workflow so much: for power users, no alternative is even close in terms
  129. of efficiency.
  131. [9]: https://git.sr.ht/~sircmpwn/dotfiles
  133. Of course, this is the power user workflow, and it can be intimidating to learn
  134. all of these things. This is why we offer more novice-friendly tools, which lose
  135. some of the advantages but are often more intuitive. For instance, we are
  136. working on user interface on the web for patch review, mirroring our existing
  137. [web interface for patch submission][10]. But, in my opinion, it doesn't get
  138. better than this for serious FOSS maintainers.
  140. [10]: https://spacepub.space/w/no6jnhHeUrt2E5ST168tRL
  142. Feel free to reach out on IRC in #sr.ht.watercooler on Libera Chat, or [via
  143. email](mailto:sir@cmpwn.com), if you have any questions about this workflow and
  144. how you can apply it to your own projects. Happy hacking!