add README

README.md

@@ -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