add README
This commit is contained in:
parent
b8ca96c505
commit
11bb02871a
114
README.md
114
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
|
||||
|
|
|
|||
Loading…
Reference in a new issue