You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
222 lines
6.8 KiB
222 lines
6.8 KiB
# 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 `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:
|
|
- branch_pattern: trunk
|
|
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 `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 Thread Branches
|
|
|
|
The `trunk` 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 `trunk`.
|
|
|
|
### 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
|
|
# trunk 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
|
|
# trunk 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 `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.
|
|
|