add INTRODUCTION and update http-server/README
message: add INTRODUCTION and update http-server/README change_hash: ADFDw8cLgmC1JaW0Ii35PV+aKpZIpw4y7Je4uRJBLCFe credentials: - type: pgp_signature pub_key_id: 95C46FA6A41148AC body: iQIzBAABAgAdFiEEJ6tQKp6olvZKJ0lwlcRvpqQRSKwFAl5JowIACgkQlcRvpqQRSKzZnQ/+IPM7Ra6IYqsve5PYXwOeALzjpUWcdtcbnHNyrYSR+h09J/EEMw/hlg/HgrbTIOLcxuuBNi849sH3v8G/R0zc8Iisjhaq9PAZC20pHe8KNuaHPqmu5tP4zKKYShqDzj5fZSV9fzEiL5JVUSr0YAVEuxqg0UiKnv9MBOqdYR4GP+tIgNyWwMRmJ0ZnlVjj23e5h6onC1YHPWdsl7+3IqEefXGFcAR81wysyoH/uQDmfSQxncWEey1vUhuK05LpwdezKVOKrfogEJoUYMcpKOTw9vRvrPkGUgEwxXZs0ENg0aEs9F7m3+Yaao+I8jiBlEImIJWs9rO+bAzRebDJS28jT+ENm9RIRFmGWwkK58gP7jZdbwnZATyVLrW84RAQfgISXntE4SvJAcLzxCNReB6cKA1HZC+ozmHcJkovpMMY/RBC4Px9eAf49utNzk5otoM2/zQqU99b1JoSFt3K34ric80kGhpo1Gz47sVEyKKi5koyhYuZX2GZhc+yTVC2LxYuekV8/FlxAPE7zVF/hvXa3957nPiaBdi7mTX/JRpDA4UrCuPY2JMpLCfW7IQ77Vw4mJacAHs/OpxDKGqupi9dMlre2NpqqJntIRMUdi9eDkvzddw3odnYfij5HlkC7mKzvVbBKoM5w0SjfqH/5UiVopWFKII8JMepiil/NNHEJBE= account: mediocregopher
This commit is contained in:
mediocregopher
parent
72f2a74415
commit
85d79ff71a
206
INTRODUCTION.md
Normal file
206
INTRODUCTION.md
Normal file
@ -0,0 +1,206 @@
|
||||
# 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.
|
||||
@ -1,9 +1,35 @@
|
||||
# dehub-server
|
||||
|
||||
This directory provides a simple Docker image which can be spun up to run a
|
||||
dehub-enabled server (i.e. one in which incoming commits will be verified prior
|
||||
to being accepted into their branch).
|
||||
dehub-enabled git http server (i.e. one in which incoming commits will be
|
||||
verified prior to being accepted into the `trunk` branch).
|
||||
|
||||
The docker image is also being hosted on docker hub at `mediocregopher/dehub`.
|
||||
Proper image tagging/versioning coming soon!
|
||||
|
||||
## Usage
|
||||
|
||||
Running the following:
|
||||
|
||||
```
|
||||
docker run \
|
||||
--name dehub \
|
||||
-v /opt/dehub/repos:/repos \
|
||||
-v /opt/dehub/www:/var/www \
|
||||
-p 8080:80 \
|
||||
mediocregopher/dehub repo-a repo-b
|
||||
```
|
||||
|
||||
Will start an http server on port 8080, using `/opt/dehub/repos` to store all
|
||||
repo folders. It will then initialize repos at `/opt/dehub/repos/repo-a.git` and
|
||||
`/opt/dehub/repos/repo-b.git`, if they arent already there.
|
||||
|
||||
If a volume for `/var/www` is given then that will be used as the root for all
|
||||
non-git http requests.
|
||||
|
||||
## Contributors
|
||||
|
||||
The Dockerfile being used is based on
|
||||
[gitbox](https://github.com/nmarus/docker-gitbox), so thank you to nmarus for
|
||||
the great work there.
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user