diff options
author | Katharina Fey <kookie@spacekookie.de> | 2020-01-15 22:28:43 +0000 |
---|---|---|
committer | Katharina Fey <kookie@spacekookie.de> | 2020-01-15 22:28:43 +0000 |
commit | c7ff83176abe03c400b218e1a61d1b6b3e91a907 (patch) | |
tree | 30fa3dcb7d6b89304a244140337f19f94af9caa0 | |
parent | cba8c4df4b23b36eb0ec97b46969db5a5380e539 (diff) |
blog/git-mail: init
-rw-r--r-- | content/blog/xxx_git_mail.md | 344 |
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. |