<story><title>The advantages of an email-driven Git workflow</title><url>https://drewdevault.com/2018/07/02/Email-driven-git.html</url></story><parent_chain><item><author>cryptonector</author><text>That&amp;#x27;s all true, but (and note: I didn&amp;#x27;t downvote you) the problem I have with email for code review is that finding all the comments made over time on one patch is... a chore.  Mind you, for many years I did code review over email, so I&amp;#x27;m used to it, and since I&amp;#x27;m a TUI sort of person, it works very very well for me &lt;i&gt;except&lt;/i&gt; for the chore that is finding and collating all comments.&lt;p&gt;This chore is very real, and very time consuming.  Reviewers need to make sure that new versions of a patch are responsive to past [accepted] commentary.  Authors need to find all commentary when updating patches in order to be responsive to it.&lt;p&gt;Not that code review tools from GitHub, GitLab, and others, are all that good.  I&amp;#x27;ve yet to find a code review tool that really works for me and the people I work with.&lt;p&gt;Whether you use email as a transport and&amp;#x2F;or interface, or something more weby, or whatever, at the end of the day, for me, the real win lies in code review and commentary management and UIs.  Because I&amp;#x27;m a TUI person, my approach would be to build a code&amp;#x2F;patch+commentary format, something like (designing on the fly here):&lt;p&gt;&lt;pre&gt;&lt;code&gt;    - foo.c
    |     &amp;#x2F;* This is code (or patch) *&amp;#x2F;
    ? jane   ^^^^^^^^^^^^
    ? jon    The above is code, yes, but this is commentary!
    |     while (!review_done)
    |         ...;
&lt;/code&gt;&lt;/pre&gt;
or&lt;p&gt;&lt;pre&gt;&lt;code&gt;    - 0001-This-is-a.patch
    | diff ...
    ...
&lt;/code&gt;&lt;/pre&gt;
Something more markdown-y would work too.&lt;p&gt;An XML version wouldn&amp;#x27;t be a bad idea, provided a) that the schema is trivial, b) that there are tools for converting between a simple text format (e.g., like the above), c) preferably things round-trip.  Obviously, with XSLT&amp;#x2F;XPath, (b) should be feasible, especially if we heed (a).  And (c) should be possible if the XML schema is kept simple enough (but see below).&lt;p&gt;What&amp;#x27;s nice about this is that as long as there is version information we can merge commentary from many emails into one document (per file&amp;#x2F;patch), which then could make automation of commentary collation possible.&lt;p&gt;This needs lots more thought, I grant that.  For example: how to cut-down quoted text without losing the ability to trivially merge commentary?  Also, it would be very tempting to add lots of metadata, which would drive one to XML.  I&amp;#x27;m not a huge fan of XML, mostly due to lack of TUI editors for it... but XML does have the advantage of XSLT&amp;#x2F;XPath.&lt;p&gt;It seems to me that this is a problem that can be solved reasonably well, and that this is a problem worth solving.  If we can solve it in a way that works well with TUIs, it will also work well with email, so this should be of interest to you (I hope so as you seem to have the time and energy to work on this!).&lt;p&gt;Thoughts?</text></item><item><author>ddevault</author><text>Author here. I didn&amp;#x27;t load all of the advantages into a single conveniently-quotable part of the article, but I think I covered them all the same. In addition to what you quoted:&lt;p&gt;&amp;gt;reviewing patches is quite easy with the email approach as well [...] It’s just email - you can reply, forward the message, Cc interested parties, start several chains of discussion, and so on&lt;p&gt;The quote you gave also misses an important point directly preceeding it, which is that email is decentralized and federated. I also wouldn&amp;#x27;t understate the importance of all of it being open source.</text></item><item><author>matharmin</author><text>The article describes a lot about the workflow, but only two sentences about the advantages:&lt;p&gt;&amp;gt; A very large body of email-related software exists and is equally reliable and well-understood. You can interact with email using only open source software and customize your workflow at every level of the stack - filtering, organizing, forwarding, replying, and so on; in any manner you choose.&lt;p&gt;Using email software in general is well-understood, but using it for Git is much harder than using GitHub. Customizing the workflow is also something you probably shouldn&amp;#x27;t want to do unless you&amp;#x27;re really working with a massive project such as the Linux kernel.</text></item></parent_chain><comment><author>Sir_Cmpwn</author><text>Thanks for your detailed thoughts, I&amp;#x27;m taking all of this down and using it to influence my work on lists.sr.ht (the mailing list and code review tool I&amp;#x27;m building).&lt;p&gt;The chores of this approach - finding and collating feedback, sheparding a patch through the flow, and so on - are all things I&amp;#x27;m acutely aware of. I don&amp;#x27;t think we need to throw the baby out with the bathwater like GitHub does, though, and I see these as places to improve our tools rather than replace them.&lt;p&gt;Take a look at this here:&lt;p&gt;&lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;git.sr.ht&amp;#x2F;~emersion&amp;#x2F;python-emailthreads&amp;#x2F;tree&amp;#x2F;test&amp;#x2F;data&amp;#x2F;multiple-replies&amp;#x2F;output3.txt&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;git.sr.ht&amp;#x2F;~emersion&amp;#x2F;python-emailthreads&amp;#x2F;tree&amp;#x2F;test&amp;#x2F;da...&lt;/a&gt;&lt;p&gt;The specific output format you see here is just a testing tool, this isn&amp;#x27;t the final user-facing product. The important part is ingesting a bunch of emails and creating a thread where you can associate all of the responses over time with the particular parts of the patch. Combining this with a gerrit-like tool which tracks new patches over time and avoids duplicating review work is planned.</text></comment>
<story><title>The advantages of an email-driven Git workflow</title><url>https://drewdevault.com/2018/07/02/Email-driven-git.html</url></story><parent_chain><item><author>cryptonector</author><text>That&amp;#x27;s all true, but (and note: I didn&amp;#x27;t downvote you) the problem I have with email for code review is that finding all the comments made over time on one patch is... a chore.  Mind you, for many years I did code review over email, so I&amp;#x27;m used to it, and since I&amp;#x27;m a TUI sort of person, it works very very well for me &lt;i&gt;except&lt;/i&gt; for the chore that is finding and collating all comments.&lt;p&gt;This chore is very real, and very time consuming.  Reviewers need to make sure that new versions of a patch are responsive to past [accepted] commentary.  Authors need to find all commentary when updating patches in order to be responsive to it.&lt;p&gt;Not that code review tools from GitHub, GitLab, and others, are all that good.  I&amp;#x27;ve yet to find a code review tool that really works for me and the people I work with.&lt;p&gt;Whether you use email as a transport and&amp;#x2F;or interface, or something more weby, or whatever, at the end of the day, for me, the real win lies in code review and commentary management and UIs.  Because I&amp;#x27;m a TUI person, my approach would be to build a code&amp;#x2F;patch+commentary format, something like (designing on the fly here):&lt;p&gt;&lt;pre&gt;&lt;code&gt;    - foo.c
    |     &amp;#x2F;* This is code (or patch) *&amp;#x2F;
    ? jane   ^^^^^^^^^^^^
    ? jon    The above is code, yes, but this is commentary!
    |     while (!review_done)
    |         ...;
&lt;/code&gt;&lt;/pre&gt;
or&lt;p&gt;&lt;pre&gt;&lt;code&gt;    - 0001-This-is-a.patch
    | diff ...
    ...
&lt;/code&gt;&lt;/pre&gt;
Something more markdown-y would work too.&lt;p&gt;An XML version wouldn&amp;#x27;t be a bad idea, provided a) that the schema is trivial, b) that there are tools for converting between a simple text format (e.g., like the above), c) preferably things round-trip.  Obviously, with XSLT&amp;#x2F;XPath, (b) should be feasible, especially if we heed (a).  And (c) should be possible if the XML schema is kept simple enough (but see below).&lt;p&gt;What&amp;#x27;s nice about this is that as long as there is version information we can merge commentary from many emails into one document (per file&amp;#x2F;patch), which then could make automation of commentary collation possible.&lt;p&gt;This needs lots more thought, I grant that.  For example: how to cut-down quoted text without losing the ability to trivially merge commentary?  Also, it would be very tempting to add lots of metadata, which would drive one to XML.  I&amp;#x27;m not a huge fan of XML, mostly due to lack of TUI editors for it... but XML does have the advantage of XSLT&amp;#x2F;XPath.&lt;p&gt;It seems to me that this is a problem that can be solved reasonably well, and that this is a problem worth solving.  If we can solve it in a way that works well with TUIs, it will also work well with email, so this should be of interest to you (I hope so as you seem to have the time and energy to work on this!).&lt;p&gt;Thoughts?</text></item><item><author>ddevault</author><text>Author here. I didn&amp;#x27;t load all of the advantages into a single conveniently-quotable part of the article, but I think I covered them all the same. In addition to what you quoted:&lt;p&gt;&amp;gt;reviewing patches is quite easy with the email approach as well [...] It’s just email - you can reply, forward the message, Cc interested parties, start several chains of discussion, and so on&lt;p&gt;The quote you gave also misses an important point directly preceeding it, which is that email is decentralized and federated. I also wouldn&amp;#x27;t understate the importance of all of it being open source.</text></item><item><author>matharmin</author><text>The article describes a lot about the workflow, but only two sentences about the advantages:&lt;p&gt;&amp;gt; A very large body of email-related software exists and is equally reliable and well-understood. You can interact with email using only open source software and customize your workflow at every level of the stack - filtering, organizing, forwarding, replying, and so on; in any manner you choose.&lt;p&gt;Using email software in general is well-understood, but using it for Git is much harder than using GitHub. Customizing the workflow is also something you probably shouldn&amp;#x27;t want to do unless you&amp;#x27;re really working with a massive project such as the Linux kernel.</text></item></parent_chain><comment><author>pm215</author><text>My solution to the &amp;quot;find all the comments made on one patch&amp;quot; is variously (a) look at that email subthread only or (b) use a webinterface like patchwork (eg &lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;patchwork.ozlabs.org&amp;#x2F;patch&amp;#x2F;938069&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;patchwork.ozlabs.org&amp;#x2F;patch&amp;#x2F;938069&amp;#x2F;&lt;/a&gt;) or patchew (eg &lt;a href=&quot;http:&amp;#x2F;&amp;#x2F;patchew.org&amp;#x2F;QEMU&amp;#x2F;20180629162122.19376-1-peter.maydell@linaro.org&amp;#x2F;&quot; rel=&quot;nofollow&quot;&gt;http:&amp;#x2F;&amp;#x2F;patchew.org&amp;#x2F;QEMU&amp;#x2F;20180629162122.19376-1-peter.maydell...&lt;/a&gt;). patches (&lt;a href=&quot;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;stefanha&amp;#x2F;patches&quot; rel=&quot;nofollow&quot;&gt;https:&amp;#x2F;&amp;#x2F;github.com&amp;#x2F;stefanha&amp;#x2F;patches&lt;/a&gt;) can handle the tedious bit of collecting up all the Reviewed-by: tags people sent for you.&lt;p&gt;The key thing about any tool that&amp;#x27;s trying to improve an email-based workflow is that it has to interoperate with people still using the traditional &amp;quot;just an email client&amp;quot; tools. Better web UIs for people who want to use web UIs are something I&amp;#x27;d love to see, but a big-bang switchover to a completely different format won&amp;#x27;t work for large projects, where mandating changes of tooling is a really hard sell. All the three tools I list above take the &amp;quot;interoperate with the existing patches-in-email transport&amp;quot; approach.</text></comment>