--- 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
mediocregopher
4 years ago
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