dehub/INTRODUCTION.md
mediocregopher 981fbb8327 Rename trunk branch to main branch
message: |-
  Rename trunk branch to main branch

  The term "trunk" is too close to "branch", imo, and is confusing since its
  inverse term, "thread", isn't related to branch at all. Ultimately I think it's
  best to leave "branch" as a git specific term, and use "main" and "thread" to
  denote the different branch types of dehub.
change_hash: ANitkSWx+QHnxo/d0zg+lrWdeqx1PHqH2GQ2uvyMYZNa
credentials:
- type: pgp_signature
  pub_key_id: 95C46FA6A41148AC
  body: iQIyBAABAgAdFiEEJ6tQKp6olvZKJ0lwlcRvpqQRSKwFAl5f/ikACgkQlcRvpqQRSKw04Q/4sX9Ylt8vdkhnT24vRqf7uoO2WsRCs4uHvr3tW5V735o3ReKE4KWT9crIKSSn92vkEaFdNAr8+9M7CMfa3qKLAd0kVbGIDiZ775+4jw/Px+nyORSkl17F5gji3m3kM6rnvqYtg5r1NvxuIeuqNK8TGojtlAsf1hN6inrB6S7MEAgw/wYRMQjV7ohYFkeMMLzaN+Q1YA4LolfnM4JbsIwcFMHC1jxDe6is22lUxR1XqTEzJqpIQLLCtY4Ds6LECqm0cFRlXic1ldcYqHxZvWLks8MdNtkMq0FqwEUtr07IqWUAyWcMsmKkReSbTfqPlizJOZ9J4c+8p5FIkRNl+TuJnfB4oBNANMmEHeeHNY3a5pfeJFOyfzAq7LfOwYBMfWcNvX4kuKfAKhSI55Snb6vK4ChRget3VruOZaFIjfAxWQX5QVcDufh3EJvuCJ1lJKKxdqIHQO95hvJ4cMgz1+pxPnQabEkFlk0Q+qFYS4u1S89y5lWxc5GIRaZX6X43/r74rB027LN9eqsovrJ0MLFHRH3QagS9YxDUsVWnv1Y/8TvUn65QRIsHbmrF1ESYdjycROh1bhTJLwwqrSwQjm5HhquvJ93DzUNgRZDLRXwDGL2raJ7oeNL+6E2fl8ahPntmvdVFWtXsMNK93/IKkW3brxUoBkWt5rzKqE4TRhWjDw==
  account: mediocregopher
2020-03-04 12:14:54 -07:00

223 lines
6.8 KiB
Markdown

# 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 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:
- branch_pattern: main
change_access_controls:
# matches all files, but could be used for more fine-grained control
- file_path_pattern: "**"
condition:
type: signature
account_ids:
- alice
- bob
- carol
count: 2
```
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.