diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 114 |
1 files changed, 111 insertions, 3 deletions
@@ -1,6 +1,114 @@ -# Patchodon +# Patchodon -- send `git` patchsets via Mastodon -Like pull requests or merge requests, but over a federated medium (via Mastodon API). +Patchodon is a tool for federated distribution of "pull requests" for git. -(TODO) +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](https://joinmastodon.org/) 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](https://dpaste.com) 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: +```ini +[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: +```sh +$ 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: +```sh +$ 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 |