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.

By doing this, the server-side git component can be reduced to a mere
pre-receive hook (if anything at all). This opens the door for much more
lightweight and flexible hosting of git projects, as well as even more radical
solutions; dehub can enable hosting git projects on completely decentralized
platforms like IPFS.

### Example

MyProject wants to ensure that at least 2 of the 3 maintainers sign off on a
commit which changes files before the commit can be placed into the `main`
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:
  - action: allow
    filters:
    - type: branch
      pattern: main

    - type: commit_type
      commit_type: change

    - type: signature
      account_ids:
      - alice
      - bob
      - carol
      count: 2

  - action: deny
    filters:
    - type: branch
      branch: main
```

A commit in the `main` 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 `main`. A simple git hook is all that's
needed to verify commits in `main` when they are pushed or pulled.

## dehub Thread Branches

The `main` branch is the project's source-of-truth. Other branches, called
threads, are used to coordinate new changes, and then coalesce those changes
into a commit suitable for `main`.

### Example

Alice creates and pushes a thread 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
change_hash: SOMECHANGEHASH
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
# main branch.
```

Bob sees the new thread 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 to the thread, 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!

change_hash: NEWCHANGEHASH
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
# main branch.
```

Bob, happy with these changes, pushes a commit to the thread 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: credential
change_hash: NEWCHANGEHASH
credentials:
  - type: pgp_signature
    pub_key_id: 56789
    body: SIGNATUREBODY
    account: bob
```

_Finally_ the thread 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 file changes in the branch are squashed
into a single change commit, using the latest commit message which was pushed by
Alice.  Bob's signature is added to the change commit message as a credential.
The commit can then be pushed to `main` (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 `main` 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 `main`?**

The primary branch in most git projects is called `master`. It makes sense to
use a different one, `main`, 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.