From 85d79ff71a6f058bc0897823aeae27e4caea092a Mon Sep 17 00:00:00 2001 From: mediocregopher <> Date: Sun, 16 Feb 2020 13:16:02 -0700 Subject: [PATCH] add INTRODUCTION and update http-server/README message: add INTRODUCTION and update http-server/README change_hash: ADFDw8cLgmC1JaW0Ii35PV+aKpZIpw4y7Je4uRJBLCFe credentials: - type: pgp_signature pub_key_id: 95C46FA6A41148AC body: iQIzBAABAgAdFiEEJ6tQKp6olvZKJ0lwlcRvpqQRSKwFAl5JowIACgkQlcRvpqQRSKzZnQ/+IPM7Ra6IYqsve5PYXwOeALzjpUWcdtcbnHNyrYSR+h09J/EEMw/hlg/HgrbTIOLcxuuBNi849sH3v8G/R0zc8Iisjhaq9PAZC20pHe8KNuaHPqmu5tP4zKKYShqDzj5fZSV9fzEiL5JVUSr0YAVEuxqg0UiKnv9MBOqdYR4GP+tIgNyWwMRmJ0ZnlVjj23e5h6onC1YHPWdsl7+3IqEefXGFcAR81wysyoH/uQDmfSQxncWEey1vUhuK05LpwdezKVOKrfogEJoUYMcpKOTw9vRvrPkGUgEwxXZs0ENg0aEs9F7m3+Yaao+I8jiBlEImIJWs9rO+bAzRebDJS28jT+ENm9RIRFmGWwkK58gP7jZdbwnZATyVLrW84RAQfgISXntE4SvJAcLzxCNReB6cKA1HZC+ozmHcJkovpMMY/RBC4Px9eAf49utNzk5otoM2/zQqU99b1JoSFt3K34ric80kGhpo1Gz47sVEyKKi5koyhYuZX2GZhc+yTVC2LxYuekV8/FlxAPE7zVF/hvXa3957nPiaBdi7mTX/JRpDA4UrCuPY2JMpLCfW7IQ77Vw4mJacAHs/OpxDKGqupi9dMlre2NpqqJntIRMUdi9eDkvzddw3odnYfij5HlkC7mKzvVbBKoM5w0SjfqH/5UiVopWFKII8JMepiil/NNHEJBE= account: mediocregopher --- INTRODUCTION.md | 206 ++++++++++++++++++++++++++++++++++++++ cmd/http-server/README.md | 30 +++++- 2 files changed, 234 insertions(+), 2 deletions(-) create mode 100644 INTRODUCTION.md diff --git a/INTRODUCTION.md b/INTRODUCTION.md new file mode 100644 index 0000000..824129a --- /dev/null +++ b/INTRODUCTION.md @@ -0,0 +1,206 @@ +# dehub + +**Embed project coordination into your git history.** + +## Gettin Started + +``` +git clone https://dehub.mediocregopher.com/dehub.git +``` + +and check out the project! dehub is still very very alpha, but it will be +"eating its own dogfood" from the start. + +Check out the `cmd/http-server` directory if you'd like to host your own. + +## Motivation + +Any active git project has a set of requirements which are not met by the git +protocol directly, for example: + +* Authenticating committers +* Some kind of ticket system for bugs and proposals +* Change reviews +* Signoff of changes by one or more maintainers +* Release management (git tags are mutable and therefore generally ineffective) + +To solve these requirements developers generally turn to centralized services +like GitHub or Bitbucket, or self-hosted server solutions like Gitlab or gogs. +These platforms become a point of hindrance; their sheer size makes developers +dependent on the platform developers to implement features and fix bugs, as well +as making developers dependent on non-trivial amounts of devops (whether +provided by the service, or self-hosted) in order to function. + +## Enter dehub + +By embedding project meta-information into git messages, as yaml encoded data +structures, dehub is able to incept all the features generally provided by git +platforms into the git history itself, including dehub's own configuration. + +### Example + +MyProject wants to ensure that at least 2 of the 3 maintainers sign off on a +commit before the commit can be placed into the `trunk` branch (dehub's +equivalent of the `master` branch). MyProject's repo would contain a +`.dehub/config.yml` file with the following access controls set: + +``` +# ... +access_controls: + + # matches all files, but could be used for more fine-grained control + - pattern: "**" + condition: + type: signature + account_ids: + - alice + - bob + - carol + count: 2 +``` + +A commit in the `trunk` branch would have a message with the following form: + +``` +This is the first line of the commit message. It remains human readable + +type: change +message: | + This is the first line of the commit message. It remains human readable + + The rest of the message body is a yaml encoded object. The message field of + that object repeats the first line of the commit message, followed by the + rest of the commit message (if there is one). The first line is duplicated + so that commands like `git log` are more usable, while at the same time + allowing the full commit message to be signed off on. + +# A hash of the diff between the previous commit and this one. +change_hash: ABCDEFGHIJKLMNOPQRSTUVWXYZ + +credentials: + - type: pgp_signature + pub_key_id: 01234 + body: SIGNATUREBODY + account: alice + + - type: pgp_signature + pub_key_id: 56789 + body: SIGNATUREBODY + account: carol +``` + +The `credentials` contains signatures of both the commit message and its +changes, allowing it to be added to the `trunk`. A simple git hook is all that's +needed to verify commits in `trunk` when they are pushed or pulled. + +## dehub Branches + +The `trunk` branch is the project's source-of-truth; all commits in it must have +dehub encoded message bodies with acceptable credentials. Other branches are +used to coordinate new changes, and then coalesce those changes into a commit +suitable for `trunk`. + +### Example + +Alice creates and pushes a branch on the git repo called `featureBranch`, and +pushes to it a commit with the following commit message: + +``` +This commit adds some really cool features + +type: change +message: This commit adds some really cool features +credentials: + - type: pgp_signature + pub_key_id: 01234 + body: SIGNATUREBODY + account: alice + +# Note that this commit does not have enough credentials to be allowed in the +# trunk branch. +``` + +Bob sees the new branch and looks through it. He pushes the following commit +(with no file changes): + +``` +A small comment + +type: comment +message: | + A small comment + + I think you should change the code at file:line to be more like the code at + otherFile:otherLine + +# Comment credentials sign the comment itself, so you can be sure of its +# authenticity. +credentials: + - type: pgp_signature + pub_key_id: 01234 + body: SIGNATUREBODY + account: bob +``` + +Alice sees Bob's comment, and agrees with his suggestion. She pushes a new +commit, which contains a slight modification of the original commit message plus +the suggested changes: + +``` +This commit adds some really cool features + +type: change +message: | + This commit adds some really cool features + + The pattern used at file:line was suggested by Bob. Thanks Bob! + +credentials: + - type: pgp_signature + pub_key_id: 01234 + body: NEWSIGNATUREBODY + account: alice + +# Note that this commit does not have enough credentials to be allowed in the +# trunk branch. +``` + +Bob, happy with these changes, pushes a commit to `featureBranch` which adds his +own signature for the latest commit message and all file changes in the branch: + +``` +bob's signature for this branch's changes + +type: pgp_signature +pub_key_id: 01234 +body: SIGNATUREBODY +account: bob +``` + +_Finally_ the feature branch is ready to be coalesced, which is a step anyone +can do once all the required credentials are available. + +To coalesce, the following is done: All changes in the branch are squashed into +a single commit, using the latest commit message which was pushed by Alice. +Bob's signature is added to the commit structure as a credential. The commit can +then be pushed to `trunk` (because it now has two credentials) and +`featureBranch` can be deleted. + +## Pre-emptively Answered Questions + +**How can I trust that the git history I've received is legitimate?** + +Each commit in `trunk` can have its credentials verified locally. Credentials +are currently provided by pgp signatures, so your trust in the git chain can be +as strong as your trust in those signatures. Support for other kinds of +credentials (e.g. keybase signatures) will increase the number of options for +trust the user has. + +**Why `trunk`?** + +The primary branch in most git projects is called `master`. It makes sense to +use a different one, `trunk`, for dehub, since the commits on it will be +following a specific protocol which is not compatible with most `master` +branches. By having a different primary branch convention we can prevent undue +conflict, as well as make it easy to tell at a glance what kind of project is +being worked with. diff --git a/cmd/http-server/README.md b/cmd/http-server/README.md index 714a68b..45118c6 100644 --- a/cmd/http-server/README.md +++ b/cmd/http-server/README.md @@ -1,9 +1,35 @@ # dehub-server This directory provides a simple Docker image which can be spun up to run a -dehub-enabled server (i.e. one in which incoming commits will be verified prior -to being accepted into their branch). +dehub-enabled git http server (i.e. one in which incoming commits will be +verified prior to being accepted into the `trunk` branch). + +The docker image is also being hosted on docker hub at `mediocregopher/dehub`. +Proper image tagging/versioning coming soon! + +## Usage + +Running the following: + +``` +docker run \ + --name dehub \ + -v /opt/dehub/repos:/repos \ + -v /opt/dehub/www:/var/www \ + -p 8080:80 \ + mediocregopher/dehub repo-a repo-b +``` + +Will start an http server on port 8080, using `/opt/dehub/repos` to store all +repo folders. It will then initialize repos at `/opt/dehub/repos/repo-a.git` and +`/opt/dehub/repos/repo-b.git`, if they arent already there. + +If a volume for `/var/www` is given then that will be used as the root for all +non-git http requests. + +## Contributors The Dockerfile being used is based on [gitbox](https://github.com/nmarus/docker-gitbox), so thank you to nmarus for the great work there. +