oniongitshare/docs/ConceptWork.md

Intention

Replace github with an ad-hoc federation, or swarm, of easily spawned nodes.

The prototype (version 0.1.1) does not work correctly, and cannot work correctly.

For one, we don't know when to update branches or when to update stuff destructively (deletion because of squash / force push, defunct branches etc.).

All we can do, in the absence of further meta-information, is manage sets of all commits that have ever existed in the repo. This is a bad idea in general, one could just as well drop the commits onto a blockchain. Git is not even particularly well suited to that, as it prefers only to pull stuff that currently has a branch label attached to it ... it would be a mis-use of git and not particularly helpful.

Instead, we want to be able to squash and delete branches. The current prototype (v0.1.1) can't do that. It'll just pull them again and there is no guarantee to eventually reach consensus on repo operations other than those that only add commits (see #6).

This is why we've decided to explicitly describe what we want to achieve, and how we think this is possible with git (or other DVCSes), and some extra infrastructure that has to be built around it

git

Is git the best possible DVCS infrastructure to base such a system on?

No. It comes with a concept of remote tracking branches that doesn't quite fit the use case. The question is,

a) what is the use case, exactly? can we pin it down more precisely?

b) what would be a better fit than git?

hg? darcs? pijul? something entirely new and purpose-built? is it worthwhile to concentrate on workarounds in order to bridge the conceptual gap? we'd still want to support git, at least on the front end, because it is such a great, reliable, popular and mature system. there exist bidirectional adapters for mercurial(hg), if that turns out to be a better fit.

Metadata repo

The system must be able to handle its own metadata.

• Maintainers' keys
• Issues with comments and status and reference to BRANCH, in a structured format that can be rendered as a local website
• Pull requests
• Associated repos maintained by others (forks)
• URLs of peers carrying a copy of the repo
• Signed, logically timestamped list of branches (#5)

The idea is that this would not necessarily be managed with git.

Concept of ownership

The concept of repo ownership is crucial to the functioning of github-like websites.

In the distributed p2p world, a contributor is represented by a public key.

The metadata repo should contain a list of maintainers, and links to repos related by fork.

The concept also extends to individual branches or commits, issues and so on.

Be clear on meaning of peers

Peering may serve at least two purposes, distinguished by ownership:

a) redundancy

b) forking

In the absence of constraints on network topology, there is no preferred direction of pulling in case a), and git has no inbuilt mechanisms to achieve eventual consistency in such a setting, which accounts for the difficulties encountered in the naive "gits pulling from each other" setting.