--- type: change message: |- Refactor all documentation * INTRODUCTION.md has been changed into README.md, and been essentially rewritten. * ROADMAP has been updated significantly. * SPEC has been slightly updated, mostly to add a header section indicating that it is an incomplete document. change_hash: ALqHmxfJSBVUIHrI4B9bGjeQpKvBUwL6GPmkDfjhu9uf credentials: - type: pgp_signature pub_key_id: 95C46FA6A41148AC body: iQIzBAABAgAdFiEEJ6tQKp6olvZKJ0lwlcRvpqQRSKwFAl6BIBQACgkQlcRvpqQRSKxguw//YGGDA/UJTVMPAkW8FeX+Pw8GzyW/nnF+f8HOo2/z56GA+llXVDwAyTXPJO3MIUBwPfnN1mLxANDClpofgKuy5I/uXD0ZEN8P4C8zyhv/OQIrgbkEa3iCnHgKFXmdn8URoeb8Bpcb5za/6VN/EwhkQlXGdwqppWcBMCuBx555AJRCIuC0LmOaVVSulbWTr4dAPU0OGodKqXxB5Je+mVzMJ43JQPw7nT5AxnN/CuEG6KsmtfRJISg6BwIVaVipoBGCNPA8Qsf6MC7RK2bCaQgxlQk3kVC46hNaGHlCbfOJgSMHwz4ivhk6tSCmfqzDQOfSQN4FQ0y9LghvFiuBI2PszytEVnYQZlX2vvXBCVa3k0BMNktCs1BKMUAxfZKJIg6YsfWlGt7hlbEgd/YvypC0JCLe3AEh7pILf2UQnxD9VWQhcpHiivXapSKgsoN1qgLgfRqQvFBAz9Wy1PMe3ySnUsBQ3hEdwqWXtQILtHRrhe9TzvMF+zQYQb0bQPM09tR0MicQD7bjzo3F0OOvudRBAAA+5W9uOEpThUVi6hJa2pTcH38ZAHcISENwqOahran4TPZ2eGyl6afmkzjjrMe3THo6rZg+U+P1MQe/2K8JItSPH98fD/eeO74QUAgq/SLIa24MqaCSFIiJ3I1xgnB5o1b8/xhAcodOUFKdgwGtdXE= account: mediocregophermain
parent
4d56716fe8
commit
d5f172875e
@ -1,230 +0,0 @@ |
|||||||
# 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. |
|
@ -0,0 +1,97 @@ |
|||||||
|
# dehub |
||||||
|
|
||||||
|
dehub aims to provide all the features of a git hosting platform, but without |
||||||
|
the hosting part. These features include: |
||||||
|
|
||||||
|
**User management** - Authentication that commits come from the user they say |
||||||
|
they do, and fine-grained control over which users can do what. |
||||||
|
|
||||||
|
**Pull requests and issues** - Facilitation of discussion via comment commits, |
||||||
|
and fine-grained (down to the file level) sign-off requirements. |
||||||
|
|
||||||
|
**Tags and releases**\* - Mark releases in the repo itself, and provide |
||||||
|
immutable and verifiable git tags so there's never any funny business. |
||||||
|
|
||||||
|
**Plugins**\*: Extend all aspects of dehub functionality via executables managed |
||||||
|
in the repo itself (in the same style as git hooks). |
||||||
|
|
||||||
|
## Key Concepts |
||||||
|
|
||||||
|
To implement these features, dehub combines two key concepts: |
||||||
|
|
||||||
|
First, repo configuration is defined in the repo itself. A file called |
||||||
|
`.dehub/config.yml` contains all information related to user accounts, their pgp |
||||||
|
keys, branch and file level access controls, and more. Every commit must adhere |
||||||
|
to the configuration of its parent in order to be considered _verifiable_. The |
||||||
|
configuration file is committed to the repo like any other file would be, and so |
||||||
|
is even able to define the access controls on itself. |
||||||
|
|
||||||
|
Second, the commit message of every dehub commit contains YAML encoded metadata, |
||||||
|
which allows dehub to extend git and provide multiple commit types, each with |
||||||
|
its own capabilities and restrictions. Some example dehub commit types are |
||||||
|
`change` commits, `comment` commits, and `credential` commits. |
||||||
|
|
||||||
|
## Infrastructure (or lack thereof) |
||||||
|
|
||||||
|
Because a dehub project is entirely housed within a traditional git project, |
||||||
|
which is merely a collection of files, any existing git or network filesystem |
||||||
|
infrastructure can be used to host any dehub project: |
||||||
|
|
||||||
|
* The most barebones [git |
||||||
|
daemon](https://git-scm.com/book/en/v2/Git-on-the-Server-Git-Daemon) server |
||||||
|
(with a simple pre-receive hook set up). |
||||||
|
|
||||||
|
* A remote SSH endpoint. |
||||||
|
|
||||||
|
* A mailing list (aka the old school way). |
||||||
|
|
||||||
|
* Network file syncing utilities such as dropbox, |
||||||
|
[syncthing](https://github.com/syncthing/syncthing), or |
||||||
|
[NFS](https://en.wikipedia.org/wiki/Network_File_System). |
||||||
|
|
||||||
|
* Existing git project hosts like GitHub, Bitbucket, or Keybase. |
||||||
|
|
||||||
|
* Decentralized filesystems such as IPFS\*. |
||||||
|
|
||||||
|
_\* Planned feature, but not yet implemented._ |
||||||
|
|
||||||
|
# Getting Started |
||||||
|
|
||||||
|
The dehub project itself can be found by cloning |
||||||
|
`https://dehub.dev/src/dehub.git`. |
||||||
|
|
||||||
|
Installation of the dehub tool is currently done via the `go get` command: |
||||||
|
|
||||||
|
``` |
||||||
|
go get dehub.dev/src/dehub.git/cmd/dehub |
||||||
|
``` |
||||||
|
|
||||||
|
This will install the binary to your `$GOBIN` path, which you'll want to put in |
||||||
|
your `$PATH`. Run `go env` if you're not sure where your `$GOBIN` is. |
||||||
|
|
||||||
|
Once installed, running `dehub -h` should show you the help output of the |
||||||
|
command. You can continue on to the tutorials if you're not sure where to go |
||||||
|
from here. |
||||||
|
|
||||||
|
## Tutorials |
||||||
|
|
||||||
|
The following tutorials will guide you through the basic usage of dehub. As |
||||||
|
dehub is still very much in development a high level of git and PGP profiency is |
||||||
|
still required in order to use dehub effectively. |
||||||
|
|
||||||
|
TODO |
||||||
|
|
||||||
|
## Documentation |
||||||
|
|
||||||
|
The [SPEC](/SPEC.html) is the best place to see every possible nitty-gritty |
||||||
|
detail of how dehub works. It attempts to be both human-readable and exhaustive |
||||||
|
in its coverage. |
||||||
|
|
||||||
|
## Other links |
||||||
|
|
||||||
|
[ROADMAP](/ROADMAP.html) documents upcoming features and other work required on |
||||||
|
the project. If you're looking to contribute, this is a great place to start. |
||||||
|
|
||||||
|
[dehub-remote](/cmd/dehub-remote) TODO |
||||||
|
|
||||||
|
[git-http-server](/cmd/git-http-server) TODO |
Loading…
Reference in new issue