dehub/INTRODUCTION.md

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