# 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.