3.7 KiB
Ecosystem Architecture
Summary
Every bridge is consists of at least two components called interface, each on either side of the bridge. State is synchronised with respect to the global-owner repository and when state changes are made on forge-local copies, each copy aims to be eventually consistent, i.e, state is synchronised is whichever order they arrive at the bridge.
Terminology
-
Interface: A bridge component that talks the bridge protocol and is able to affect changes to the forge that it manages.
-
Creator: A person or a team that is responsible for managing the project.
-
Main copy: creator's copy of the source code. In pre-federation forges, these are the main/upstream repositories.
-
Main forge: The forge on which the creator's repository is hosted
-
Main Interface: An interface that is hosted on the main forge or is able to perform actions that directly make changes to the main forge's contents. They usually have some authenticated access to the main forge(OAuth access, etc.) and also have a namespace on the forge where they can host forked repositories.
-
Main-interface copy: A forked copy the main copy. These are managed by the main interface and is used to pass on changes from other contributors to the main copy.
-
Local Interface: An interface that is operated on the contributor's forge. local and main interface roles are interchangeable and are decided based on the direction of the transaction They usually have some authenticated access to the local forge(OAuth access, etc.) and also have a namespace on it where they can host copies(manual cloning and uploading) of the main copy.
-
Local-interface copy: A manually cloned and uploaded version of the main copy. This exists on the contributor's forge and is managed by the local interface. Any pull request/patch submissions by the contributor is made against this copy.
-
Contributor: person who wishes to take part in the development of a project that is not on the
main forge
. -
Contributor-fork: A contributor's fork of local interface copy.
Commit mechanism
-
Contributor requests
local interface
to fork a repository not local to their forge -
Local interface
contacts North Star, federated forge protocol's discovery service, to find main interfaces formain forge
. And requests amain interface
to fork themain copy
. -
Local interface
clones and uploadsmain copy
tolocal forge
-
Contributor
forkslocal-interface copy
and makes changes. -
Contributor
sends patch/pull request tolocal-interface copy
. -
Local interface
processes contributor's changes(apply.forgeignore
, etc.) and generates a patch. This patch is sent to theMain interface
. -
Main interface
applies the patch onmain-interface copy
and makes PR/sends patch tomain copy
. -
Creator verifies the patch and applies it to
main copy
Bridging policy
Bridges is divided into two components for separations of concerns. There are many types of software forges(Gitea, GitLab, etc.) and it is impossible to implement a monolithic bridge for all combinations of forges. Development workflows are also different across forges. Some forges use email-based workflows while some use pull requests. It is also possible that a forge might use a combination of software: a separate bug tracker service and separate read and write interfaces for the repositories that it hosts.
Therefore, with this protocol, we aim to set policy for bridging and not the mechanism. Bridge implementers are requested to decide upon implementation details at their discretion.