Patchodon -- send git patchsets via Mastodon

Patchodon is a tool for federated distribution of "pull requests" for git.

In ye olde times (and in linux development and related places), the "pull requests" are done simply via sending patches through e-mail. Coordinating some discussion atop of that is doable in a semi-distributed manner, typically the discussion is done via a mailing list, and you need a mailing list service that manages the mail forwarding to everyone involved, and preferably archives.

Patchodon is doing a similar workflow of sending the patches directly to the "target", but it uses Mastodon network as an open communication medium, instead of the mailing lists.

In short, the workflow is as follows:

1. The patch author runs git format-patch ... | patchodon post, which uploads the patches to a mastodon thread and gives the URL to the "head" status
2. All commits in the patch receive their own status, so that people can freely comment on them and generally organize on getting the code in a good shape for merging. If space allows, the commit statuses have a piece of commit message and/or diff stats, so that people can sensibly comment on individual pieces of the patchset.
3. The actual commit data are currently uploaded to dpaste via their API, as that is a slightly better place for posting "exact" patches.
4. The owner of the target repository runs pathodon get https://mastodon.example/@some_user/1234567890 | git am, which retrieves the patches from the thread and applies them into a branch in the local repository. The actual merging happens locally, like with other federated git workflows.

Installation and setup

patchodon executable should work with any Python 3; simply put it into a directory in your PATH.

You may need requests and html2text which can be downloaded via distribution packages, or with pip (see requirements.txt).

Basic usage

To get patchodon working, you will need to give it (limited) access to your Mastodon instance, via an access token:

• navigate to Preferences → Development
• there, create a new application
• the application needs the following scopes:
  • read:search and read:statuses for running patchodon get
  • write:statuses for running patchodon post
• copy the access token and put it into the patchodon config.

The patchodon config in your ~/.patchodon.ini should be filled in to look roughly like this:

[patchodon]
instance_url=https://your.mastodon.instance.example/
api_token=xxxxxx_the_token_you_got_from_mastodon_application_settings_xxxxxxx

(You can also set the instance and token via command line, but that's much less convenient for daily use.)

Sending patches

Assume you have branched off the main branch in your repository, and you want to send the patches to someone called "JohnDoe" on the target instance:

$ git format-patch main | patchodon post -r @JohnDoe -s 'this is the patches we talked about last week'

https://your.mastodon.instance.example/@someGuy/34592345923

-r stands for "recipient" (all statuses are going to get tagged with that) and -s stands for subject (the head status is going to include that text). The URL is the "head" of the patch set that contains the metadata (mainly the complete hash of the patches) that allow people to safely reassemble your patchset.

Receiving patches

John Doe will see the status, give it a rough examination, see if other developers commented anything in the patch series, and if all seems OK, they will pull the changes into a new branch as follows:

$ git checkout -b someguy/the-patches-we-talked-about
$ patchodon get https://your.mastodon.instance.example/@someGuy/34592345923 | git am

And that's it -- the patch was discussed, and got safely transferred to the destination.

Disclaimers and dangers

• Note that the rules of some Mastodon instances may prevent you from using this. Using scripts to post multiple statuses may be considered as an automated use, and might be viewed as very undesirable by both users and admins. Please verify, very carefully, that your instance is OK with this kind of supervised, semi-automated use. It's always best to check with the admins before you start spamming the patches around.
• Patchodon makes some mild effort to prevent others from injecting code into your published patch series. Most notably, all patches are hashed, the hashes are hashed together to form a "full hash", and that is required to match perfectly before patchodon get outputs the code into your git. Regardless, you should always be aware of the security implications of downloading things from the Internet and piping them into git-am.

TODOs

You might have noticed that this is far from complete. The following features are on the TODO list:

• support for different pastebins (possibly providing more privacy)
• status visibility configuration
• dpaste retention configuration
• likely a better default hash function than SHA1