{"id":500,"date":"2015-08-29T12:33:46","date_gmt":"2015-08-29T12:33:46","guid":{"rendered":"http:\/\/blogs.gentoo.org\/lu_zero\/?p=500"},"modified":"2015-08-29T13:36:30","modified_gmt":"2015-08-29T13:36:30","slug":"patches-and-plaid","status":"publish","type":"post","link":"https:\/\/blogs.gentoo.org\/lu_zero\/2015\/08\/29\/patches-and-plaid\/","title":{"rendered":"Patches and Plaid"},"content":{"rendered":"<p>This is part of the <a href=\"\/tag\/api\">better tools<\/a> series.<\/p>\n<p>Sometimes you should question the tools you are using and try to see if there is something better out there. Or build it yourself.<\/p>\n<h1>Juggling patches<\/h1>\n<p>It is quite common when interacting with people to send back and forth the changes to the shared codebase you are working on.<\/p>\n<p>This post tries to analyze two commonly used models and explain why they can be improved and which are the good tools for it (existing or not).<\/p>\n<h2>The two models<\/h2>\n<p>The focus is on <a href=\"http:\/\/git-scm.com\">git<\/a>, <a href=\"http:\/\/github.com\">github-like<\/a> web-mediated pull-requests and <strong>mailinglist-oriented<\/strong> workflows.<\/p>\n<p>The tools in use are always:<\/p>\n<ul>\n<li>a web <strong>browser<\/strong><\/li>\n<li>an editor<\/li>\n<li>a <strong>shell<\/strong><\/li>\n<li>an <strong>email<\/strong> client<\/li>\n<\/ul>\n<p>Some people might have all in one in a <a href=\"https:\/\/www.gnu.org\/software\/emacs\">way<\/a> or <a href=\"http:\/\/www.google.com\/chrome\">another<\/a> making one of the two model already incredibly more effective. Below I assume you do not have such tightly integrated environments.<\/p>\n<h3>Pull requests<\/h3>\n<p><a href=\"http:\/\/github.com\">Github<\/a> made quite easy to propose patches in the form of ephemeral branches that can be reviewed and merged with a single click on your <strong>browser<\/strong>.<\/p>\n<p>The patchset can be part of your master tree or a brand new <strong>branch<\/strong> pushed on your repository for this purpose: first you <strong>push<\/strong> your changes on github and then you go to your <strong>browser<\/strong> to send the <strong>P<\/strong>ull<strong>R<\/strong>equest (also known as merge request or proposed changeset).<\/p>\n<p>You can get <strong>email<\/strong> notification that a pull request is available and then move to your <strong>browser<\/strong> to review it.<\/p>\n<p>You might have a continuous integration report out of it and if you <strong>trust<\/strong> it you may <strong>skip<\/strong> fetching the changes and test them locally.<\/p>\n<p>If something does not work exactly as it should you can notify the proponents and they might get an <strong>email<\/strong> that they have comments and they have to go to the <strong>browser<\/strong> to see them in detail.<\/p>\n<p>Then the changes have to be pushed to the right branch and github helpfully <strong>updates<\/strong> it.<\/p>\n<p>Then the reviewer has to get back to the <strong>browser<\/strong> and check again.<\/p>\n<p>Once that is done you have your main tree with lots of merge artifacts and possibly some fun time if you want to <a href=\"http:\/\/git-scm.com\/docs\/git-bisect\">bisect<\/a> the history.<\/p>\n<h3>Mailing-list mediated<\/h3>\n<p>The mailing-list mediated is sort of popular because Linux does use it and <a href=\"http:\/\/git-scm.com\">git<\/a> <a href=\"http:\/\/git-scm.com\/docs\/git-format-patch\">does<\/a> <a href=\"http:\/\/git-scm.com\/docs\/git-send-email\">provide<\/a> <a href=\"http:\/\/git-scm.com\/docs\/git-am\">tools<\/a> for it out of box.<\/p>\n<p>Once you have a set of patches (say 5) you are happy with you can simply issue<\/p>\n<pre><code>git send-email --compose -5 --to the_mailing@list.org\n<\/code><\/pre>\n<p>And if you have a local mailer working that&#8217;s it.<\/p>\n<p>If you do not you end up having to configure it (e.g. configuring gmail with a <a href=\"http:\/\/tomassetti.me\/how-to-contribute-to-libav-vlc-just-got-my-first-patch-approved\/\">specific access<\/a> token not to have to type the password all the time is <a href=\"http:\/\/git-scm.com\/docs\/gitcredentials.html\">sort of easy<\/a>)<\/p>\n<p>The people in the mailing-list then receive your set in their mailbox as is and they can use <a href=\"http:\/\/git-scm.com\/docs\/git-am\">git-am<\/a> to test it (first saving the thread using their email client then using git am over it) locally and push to something like <a href=\"http:\/\/oracle.libav.org\">oracle<\/a> if they like the set but they aren&#8217;t completely sure it won&#8217;t break everything.<\/p>\n<p>If they have comments can just reply to the specific patch email (using the email <code>Message-Id<\/code>).<\/p>\n<p>The proponent can then rework the set (maybe using <a href=\"http:\/\/git-scm.com\/docs\/git-rebase\">git rebase -i<\/a>) and send an update and add some comments here and there.<\/p>\n<pre><code>git send-email --annotate -6 --to the_mailing@list.org\n<\/code><\/pre>\n<p>Updates to specific patches or rework from other people can happen by just sending the patch back.<\/p>\n<pre><code>git send-email --annotate -1 --in-reply-to patch-msgid\n<\/code><\/pre>\n<p>Once the set is good, it can be applied to the tree, resulting in a purely linear history that makes going over looking for regression pretty easy.<\/p>\n<h2>Where to improve<\/h2>\n<h3>Pull request based<\/h3>\n<p>The weak and the strong point of this method is its web-centricity.<\/p>\n<p>It works quite nicely if you just use the web-mail so is just switching from a tab to another to see exactly what&#8217;s going on and reply in detail.<\/p>\n<p>Yet, if your browser isn&#8217;t your shell (and you didn&#8217;t configure custom actions to auto-fetch the pull requests) you still have lots of back and forth.<\/p>\n<p>Having already continuous integration hooks you can quickly configure is quite nice if the project has already a solid regression and code coverage harness so the reviewer bourden to make sure the code doesn&#8217;t break is lighter.<\/p>\n<p>Sending a link to a pull request is easy.<\/p>\n<p>Sadly, new code does not come with tests or tests you should trust the whole point above is half moot: you have to do the whole <em>fetch&amp;test<\/em> dance.<\/p>\n<p>Reworking sets isn&#8217;t exactly perfect, it makes quite hard to a third party to provide input in form of an alternate patch over a set:<\/p>\n<ul>\n<li>you have to fetch the code being discussed<\/li>\n<li>prepare a new pull request<\/li>\n<li>reference it in your comment to the old one<\/li>\n<\/ul>\n<p>then<\/p>\n<ul>\n<li>the initial proponent has to fetch it<\/li>\n<li>rebase his branch on it<\/li>\n<li>update the pull request accordingly<\/li>\n<\/ul>\n<p>and so on.<\/p>\n<p>There are desktop-tools trying to bridge web and shell but right now they aren&#8217;t an incredible improvement and the churn during the review can be higher on the other side.<\/p>\n<p>Surely is really <strong>HARD<\/strong> to forget a pull request open.<\/p>\n<h3>Mailing list based<\/h3>\n<p>The strong point of the approach is that you have less steps for the most common actions:<\/p>\n<ul>\n<li>sending a set is a single command<\/li>\n<li>fetching a set is two commands<\/li>\n<li>doing a quick review does not require to switch to another application, you just<br \/>\nreply to the email you received.<\/li>\n<li>sending an update or a different approach is always the same <code>git send-email<\/code> command<\/li>\n<\/ul>\n<p>It is quite loose so people can have various degrees of integration, but in general the experience as reviewer is as good as your email client, your experience as proponent is as nice as your <strong>sendmail<\/strong> configuration.<\/p>\n<p>People with basic email client would even have problems referring to patches by its <code>Message-Id<\/code>.<\/p>\n<p>The weakest point of the method is the chance of <strong>missing<\/strong> a patch, leaving it either unreviewed or uncommitted after the review.<\/p>\n<h2>Ideal situation<\/h2>\n<p>My ideal solution would include:<\/p>\n<ul>\n<li>Not many compulsory steps, sending a patch for a habitual contributor should take the least amount of time.<\/p>\n<\/li>\n<li>\n<p>A pre-screening of patches, ideally making sure the new code has tests and it passes them on some testing environments.<\/p>\n<\/li>\n<li>\n<p>Reviewing should take the least amount of time.<\/p>\n<\/li>\n<li>\n<p>A mean to track patches and make easy to know if a set is still pending review or it is committed.<\/p>\n<\/li>\n<\/ul>\n<h2>Enters plaid<\/h2>\n<p>I do enjoy better using the <strong>mailing-list<\/strong> approach since it is much quicker for me, I have a decent email client (that still could improve) and I know how to configure my local smtp. If I want to contribute to a new project that uses the approach it is just a matter to find the email address and type <code>git send-email --annotate --to email<\/code>, github gets unwieldy if I just want to send a couple of fixes.<\/p>\n<p>That said I do see that the mailing-list shortcomings are a limiting factor and while I&#8217;m not much concerned as making the initial setup much easier (since <a href=\"http:\/\/tomassetti.me\/\">federico<\/a> has already plans for it), I do want to not lose patches and to get some of the nice and nifty features github has without losing the speed in development I do enjoy.<\/p>\n<p><a href=\"http:\/\/github.com\/lu-zero\/plaid\">Plaid<\/a> is my try to improve the situation, right now it is just more or less an easier to deploy patch tracker along the lines of <a href=\"http:\/\/jk.ozlabs.org\/projects\/patchwork\/\">patchwork<\/a> with a diverging focus.<\/p>\n<p>It emphasizes the concepts of <a href=\"http:\/\/plaid.libav.org\/project\/libav\/tag\/\">patch tag<\/a> to provide quick grouping, <a href=\"http:\/\/plaid.libav.org\/project\/libav\/series\/50\">patch series<\/a> to ease reviewing a set.<\/p>\n<pre><code>curl http:\/\/plaid.libav.org\/project\/libav\/series\/50\/mbox | git am -s\n<\/code><\/pre>\n<p>Is all you need to get all the patches in your working tree.<\/p>\n<p>Right now it works either as stand-alone tracker (right now <a href=\"http:\/\/plaid.libav.org\">this<\/a> test deploy is fed by fetching from the mailing list archives) or as mailbox hook (as patchwork does).<\/p>\n<h3>Coming soon<\/h3>\n<p>I plan to make it act as postfix filter, so it injects in the email an useful link to the patch. It will provide a mean to send emails directly from it so it can doubles as nicer email client for those that are more web-centric and gets annoyed because gmail and the likes aren&#8217;t good for the purpose.<\/p>\n<p>More views such as a per-submitter view and a search view will appear as well.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>This is part of the better tools series. Sometimes you should question the tools you are using and try to see if there is something better out there. Or build it yourself. Juggling patches It is quite common when interacting with people to send back and forth the changes to the shared codebase you are &hellip; <a href=\"https:\/\/blogs.gentoo.org\/lu_zero\/2015\/08\/29\/patches-and-plaid\/\" class=\"more-link\">Continue reading <span class=\"screen-reader-text\">Patches and Plaid<\/span><\/a><\/p>\n","protected":false},"author":10,"featured_media":0,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"spay_email":"","jetpack_publicize_message":"","jetpack_is_tweetstorm":false,"jetpack_publicize_feature_enabled":true},"categories":[17],"tags":[22],"jetpack_publicize_connections":[],"jetpack_featured_media_url":"","jetpack_sharing_enabled":true,"jetpack_shortlink":"https:\/\/wp.me\/p1aGWH-84","_links":{"self":[{"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/posts\/500"}],"collection":[{"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/users\/10"}],"replies":[{"embeddable":true,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/comments?post=500"}],"version-history":[{"count":5,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/posts\/500\/revisions"}],"predecessor-version":[{"id":505,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/posts\/500\/revisions\/505"}],"wp:attachment":[{"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/media?parent=500"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/categories?post=500"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blogs.gentoo.org\/lu_zero\/wp-json\/wp\/v2\/tags?post=500"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}