blog/git-mail: init

1 files changed, 344 insertions, 0 deletions

diff --git a/content/blog/xxx_git_mail.md b/content/blog/xxx_git_mail.md
new file mode 100644
index 0000000..097b407
--- /dev/null
+++ b/content/blog/xxx_git_mail.md
@@ -0,0 +1,344 @@
+Title: Collaborating with git-send-email
+Category: Blog
+Date: 2020-01-16
+Tags: /dev/diary, git, email
+Status: Draft
+
+There's is a conversation that I keep having with various people, and
+while I've written some of my thoughts down in emails that are
+available on my [public-inbox], I felt like it was maybe it was time
+to write a blog post about it too.
+
+[public-inbox]: https://lists.sr.ht/~spacekookie/public-inbox/%3C87woa41sgn.fsf%40kookie.space%3E
+
+The reason for this is that there is documentation on the internet on
+how to use git-send-email in theory, but few ever really talk about
+the resulting workflow beyond a single patch.
+
+I won't pretend that the tools couldn't use some work or that it
+doesn't take a bit of getting used to, but the reward is well worth
+it, and something that I feel deserves more attention.
+
+
+## The basics
+
+To get into the basics of sending patches by email, I recommend
+[git-send-email.io], which goes into the setup of basics on various
+platforms.  It's one of those things where your setup will vary
+slightly, depending on your OS and email hoster, and not something
+that I feel needs too much more explanation.
+
+[git-send-email.io]: https://git-send-email.io
+
+You can go through that set of slides to send a test patch to the
+project that's hosted on sourcehut to see if your setup is working
+properly.  This is enough to send short one-offs to projects without
+having to make an account anywhere (except the e-mail you already have
+anyway).
+
+
+## Discussion and patches
+
+I think one of the main advantages of git mail collaboration is that
+the workflow of sending patches and creating meaningful discussion on
+patches is so interlinked.  While you're using different clients to
+send patches and replying to feedback, but the code that you send is
+still available in your e-mail client, so it's easy to reply to both
+feedback, while coping parts of a patch for reference.
+
+It's important here to send e-mail as plain text, because otherwise it
+might make it weird for people to reply to.  There's a great website
+that helps you make sure your e-mail client is in plain text mode:
+[useplaintext.email].
+
+[useplaintext.email]: https://useplaintext.email/
+
+
+## Patchsets and revisions
+
+So having the basics out the way, I think it's important to discuss a
+more complete workflow.  When people send contribtions to projects
+using pull-requests, often a set of changes will go through several
+revisions before getting merged.  It's also nice to quickly force-push
+to fix a small typo or similar before anyone has the chance to give
+feedback.
+
+When collaborating with git over email this is still possible via
+"revisions".  When sending a patchset, you can provide a `-V`
+parameter with a number.  The patches you send will then have a
+revision number in them, as follows: `[PATCH v2]`.  It's recommended
+to send newer revisions of your patchset as a reply to the previous
+one, i.e. `[PATCH]: foo` being the parent of `[PATCH v2]: foo` in the
+same thread.
+
+If you get replies to your patch, you can make changes to your
+commits, then send out a new revision to the whole set, or just
+individual patches, if your set of changes contains a lot of code and
+you want to keep the volume of e-mails down.
+
+The advantage of this is both that people can comment on things as
+they happen in the history of the code instead of being forced to
+understand a set of changes all in one go, and that you are
+automatically encouraged to squash commits with messages like "small
+fixes" before sending them out to a project's mailing list.
+
+
+## Cover letters
+
+One neat thing that many people also don't know about are cover
+letters.  Sometimes a set of changes is so large and requires some
+preface to make sense, it's a good idea to write an introduction for
+someone to read first.  This is essentially what GitHub pull-request
+descriptions were derived from.
+
+To generate a cover letter you need to create your patches in two
+stages:
+
+**git-format-patches** to generate a series of `.patch` files that can
+later be turned into e-mails.  This tool takes a `--cover-letter`
+paramenter that indicates to it to generate an empty patch called
+`0000-cover-letter.patch`, which contains the diff-stat of your
+proposed changes.  You are then free to edit this file in your
+favourite text editor to write a friendly introduction to your
+patchset.
+
+Another often overlooked feature here is "timely commentary", which is
+a way for you to include a comment in the patch e-mail, that won't
+make it into the actual commit message, but that also isn't part of
+the patch itself.  It's a way to convay additional information to
+maintainers that might not be relevant past the e-mail thread itself.
+
+After that you can use **git-send-email**, almost the same as before,
+but instead of giving it a series of commits to send (say `HEAD~3`),
+you now just say `*.patch` or wherever you saved the patch files
+earlier.
+
+This way the thread with your patches will start with the cover letter
+that someone can read to get a good overview of your changes.  The
+description won't actually make it into the repo and you don't have to
+resend it every time you send a new revision of your whole patch-set.
+On the other hand, if fundamental changes have been made, it might be
+a good idea to add one again, just to make sure people joining the
+feedback process later don't have to stort from the beginning of a
+thread to understand the latest state of changes.
+
+
+## An example
+
+I always work well with examples and I think it's good to illustrate
+how all of this can work, especially for people who might seem scared
+by the concept of collaborating this way.
+
+So, I'm creating some patches for my `libkookie` repo and I want to
+get some feedback from myself, so I decide not to push to master,
+which I totally could do, but to my public-inbox instead.
+
+There's two commits that I want some feedback on, so I make my
+commits, and verify that they are indeed what I want them to be:
+
+```
+ ❤ libkookie> git log HEAD~2..HEAD
+ commit 3a147c15e998d57d9db877c9cd92d0cf04411cc9 (HEAD -> master)
+Author: Katharina Fey <kookie@spacekookie.de>
+Date:   Wed Jan 15 21:01:06 2020 +0000
+
+    ws/kitty: setting default shell to tmux
+
+commit d54937fa9414d87971a01dbc0dec5105b97e8f7e
+Author: Katharina Fey <kookie@spacekookie.de>
+Date:   Wed Jan 15 20:59:40 2020 +0000
+
+    ws: adding gpg submodule by default
+```
+
+Well, perfect.  This way I can also verify that my range syntax in git
+(`HEAD~2..HEAD`, meaning all commits `HEAD~2`, so 2 commits ago, and
+`HEAD`, so now) works the way I'm expecting it to.
+
+I think this is quite an impressive set of changes so I decide to
+reward myself with a good ol' cover letter.
+
+```
+ ❤ libkookie> git format-patch --cover-letter HEAD~2..HEAD
+0000-cover-letter.patch
+0001-ws-adding-gpg-submodule-by-default.patch
+0002-ws-kitty-setting-default-shell-to-tmux.patch
+```
+
+I can go and verify the patches look okay, do a final pass over the
+typos and then edit the cover letter as well:
+
+```
+From 3a147c15e998d57d9db877c9cd92d0cf04411cc9 Mon Sep 17 00:00:00 2001
+From: Katharina Fey <kookie@spacekookie.de>
+Date: Wed, 15 Jan 2020 21:06:37 +0000
+Subject: [PATCH 0/2] The best patchset in the universe
+
+To who it may concearn,
+
+I have created the most magnificent patch set in the history of the
+universe and I really think you should merge it because otherwise
+you'd be a git.
+
+Cheers,
+me!
+
+
+Katharina Fey (2):
+  ws: adding gpg submodule by default
+  ws/kitty: setting default shell to tmux
+
+ modules/workstation/default.nix      | 1 +
+ modules/workstation/kitty/kitty.conf | 3 ++-
+ 2 files changed, 3 insertions(+), 1 deletion(-)
+
+-- 
+2.24.1
+```
+
+Perfect, they'll just love that over at spacekookie inc.  I quickly
+exit, save, and close the file and send off the patches:
+
+```
+ ❤ libkookie> git send-email --To "~spacekookie/public-inbox"@lists.sr.ht *.patch 
+0000-cover-letter.patch
+0001-ws-adding-gpg-submodule-by-default.patch
+0002-ws-kitty-setting-default-shell-to-tmux.patch
+(mbox) Adding cc: Katharina Fey <kookie@spacekookie.de> from line 'From: Katharina Fey <kookie@spacekookie.de>'
+From: Katharina Fey <kookie@spacekookie.de>
+To: ~spacekookie/public-inbox@lists.sr.ht
+Cc: Katharina Fey <kookie@spacekookie.de>
+Subject: [PATCH 0/2] The best patchset in the universe
+Date: Wed, 15 Jan 2020 21:10:48 +0000
+Message-Id: <20200115211050.31664-1-kookie@spacekookie.de>
+X-Mailer: git-send-email 2.24.1
+MIME-Version: 1.0
+Content-Transfer-Encoding: 8bit
+
+    The Cc list above has been expanded by additional
+    addresses found in the patch commit message. By default
+    send-email prompts before sending whenever this occurs.
+    This behavior is controlled by the sendemail.confirm
+    configuration setting.
+
+    For additional information, run 'git send-email --help'.
+    To retain the current behavior, but squelch this message,
+    run 'git config --global sendemail.confirm auto'.
+
+Send this email? ([y]es|[n]o|[e]dit|[q]uit|[a]ll):
+```
+
+You can get the question about the Cc not to show up by providing
+`--supress-cc all` as a parameter, but I find it useful.  Basically a
+Cc is just a ping, and if you're mentioning people by e-mail address
+in your patchset or commits (for example, if you have `Co-Authored-By`
+lines in there) the appropriate people can be pinged for you
+automatically.
+
+So, I'm happy with things as they are, so I hit "a", for all and send
+off all three e-mails.  (You can find them in the archive
+[here][thread]).
+
+[thread]: https://lists.sr.ht/~spacekookie/public-inbox/%3C20200115211246.1832-1-kookie@spacekookie.de%3E
+
+I wait, drink some chocolate milk, and wait for a reply.
+
+```
+Katharina Fey <kookie@spacekookie.de> (0 mins. ago) (inbox unread)
+Subject: Re: [PATCH 2/2] ws/kitty: setting default shell to tmux
+To: ~spacekookie/public-inbox@lists.sr.ht
+Date: Wed, 15 Jan 2020 21:30:23 +0000
+
+A comment on this commit:
+
+> --- a/modules/workstation/kitty/kitty.conf
+> +++ b/modules/workstation/kitty/kitty.conf
+> @@ -1,10 +1,11 @@
+>  font_size 10
+> -font_familt twemoji-color-font
+> +font_family twemoji-color-font
+
+This was a typo before but I think we don't really want this feature
+anymore, because all the font integration stuff is broken anyway.  I
+think it'd be better to remove this line and then add it again when it
+becomes relevant again.
+
+~k
+```
+
+What's interesting is how feedback can be layered into the patch
+itself, to comment on changes that need to be made.  This way it's
+possible to keep track of what a conversation is about, while also
+being able to have a threaded conversation.
+
+I guess I have a fair point here, the emoji fonts have been broken on
+my computer for ages, so while I'm somewhat annoyed for having to
+change things again, but I can understand why.
+
+What I want to do now is reply with only a second revision on this one
+commit because I don't know if there's more feedback coming for the
+rest of the patchset.  First, we need to figure out what the
+`Message-Id` of the previous reply is, either via you e-mail client,
+or the public mail archive of the project.
+
+```
+ ❤ libkookie> git send-email \
+    --To "~spacekookie/public-inbox"@lists.sr.ht \
+    --reply-to "<87r2001k7k.fsf@kookie.space>"
+[...]
+OK. Log says:
+Sendmail: /home/.nix-profile/bin/msmtp -i ~spacekookie/public-inbox@lists.sr.ht kookie@spacekookie.de
+From: Katharina Fey <kookie@spacekookie.de>
+To: ~spacekookie/public-inbox@lists.sr.ht
+Cc: Katharina Fey <kookie@spacekookie.de>
+Subject: [PATCH] ws/kitty: setting default shell to tmux
+Date: Wed, 15 Jan 2020 21:42:56 +0000
+Message-Id: <20200115214256.1770-1-kookie@spacekookie.de>
+X-Mailer: git-send-email 2.24.1
+In-Reply-To: <87r2001k7k.fsf@kookie.space>
+References: <87r2001k7k.fsf@kookie.space>
+MIME-Version: 1.0
+Content-Transfer-Encoding: 8bit
+
+Result: OK
+```
+
+The way that the reply works mean the thread now looks somewhat like
+this:
+
+```
+[PATCH 0/2] The best patchset in the universe 
+ ↳ [PATCH 1/2] ws: adding gpg submodule by default
+ ↳ [PATCH 2/2] ws/kitty: setting default shell to tmux
+    ↳ Re: [PATCH 2/2] ws/kitty: setting default shell to tmux
+      ↳ [PATCH v2] ws/kitty: setting default shell to tmux
+```
+
+And that's basically it: the maintainers now have all your changes and
+can apply them to the tree.  Usually you'll get an e-mail back to tell
+you that your changes were accepted and will be available on the
+upstream repo soon.  It can sometimes be nice to re-generate a
+patchset with all the latest versions of patches, even if they've been
+sent to the lest before, just to make it easier to apply them.  But
+that's ofter also not required.
+
+
+## The conclusion
+
+I'm impressed you made if you've made it all the way through this
+post.  I think there's a lot of value in this type of collaboration
+workflow.  People talk about wanting to decentralise development,
+getting away form GitHub, and they often disagree on how this can best
+be done.
+
+I'm not gonna pretend that the tooling for all of this couldn't use
+some work.  In fact, I'm working on some tools to make both sending
+and receiving patches easier.  But I think the underlying idea is a
+good one.  It's a basic technology that we're all already using and it
+doesn't require you to sign up on yet another service, or make a bunch
+of servers federate with each other (okay, e-mail is federated, but
+that's not the point), or even having to host a version of the code
+somewhere.
+
+All you need is the code the project provided you, a text editor and a
+mail address.