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.