Merge pull request #1 from realaravinth/master

rfc1: ecosystem and architecture

rfc/1-ecosystem-architecture/1-ecosystem-architecture.md

@@ -0,0 +1,91 @@
+# 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.
+
+![ownership diagram](./res/ownership-relationship.png)
+
+## Commit mechanism
+
+1. Contributor requests `local interface` to fork a repository not local to their forge
+
+2. `Local interface` contacts North Star, federated forge protocol's
+   discovery service, to find main interfaces for `main forge`. And
+   requests a `main interface` to fork the `main copy`.
+
+3. `Local interface` clones and uploads `main copy` to `local forge`
+
+4. `Contributor` forks `local-interface copy` and makes changes.
+
+5. `Contributor` sends patch/pull request to `local-interface copy`.
+
+6. `Local interface` processes contributor's changes(apply
+   `.forgeignore`, etc.) and generates a patch. This patch is sent to
+   the `Main interface`.
+
+7. `Main interface` applies the patch on `main-interface copy` and makes
+   PR/sends patch to `main copy`.
+
+9. 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.

rfc/1-ecosystem-architecture/res/ownership-relationship.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2021-09-30T10:36:28.360Z" agent="5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/14.9.6 Chrome/89.0.4389.128 Electron/12.0.16 Safari/537.36" etag="ntnlWVSqSukZ0qgBfoMz" version="14.9.6" type="device"><diagram id="VBJe3Vpqzd-JKv3SCx_P" name="Page-1">5VpNc5s6FP01XsbDN3hZnLSdaTvtTBZtVx0BAtQKRIWI7f76SiAMsoidznMcnpOFg66EhM65R1e6sLDXxfYdBVX+iSQQLywj2S7s24Vl+Z7Jf4Vh1xnsldsZMoqSzmQOhnv0B0qjIa0NSmCtNGSEYIYq1RiTsoQxU2yAUrJRm6UEq6NWIIOa4T4GWLd+RQnLO2tg+YP9PURZ3o9sequupgB9YzmTOgcJ2YxM9t3CXlNCWHdVbNcQC+x6XLr73j5Su38wCkv2lBvu3js/bh/CB4QA+BqG36CZfLiRvTwA3MgJZ4hhEC1jUvCuyKaElP+nsCJyFmzXQ0NJUyZQ9G4s7HCTIwbvKxCL2g33BW7LWYF5yeSX+tP2Q0PK4HZkkk//DpICMrrjTWStI4GUnuTYsrwZeDF9actHnATSBqQrZPueB7T4hQTsH8CzpsDLmx487pKMoqhhZDYQerPD0D7ugAVA5Q0qGaSpgGUmMFqOMzMYneMwpoRm8AYTvq7NBUNndq5oWRooMOHBQBYJZTnJSAnw3WANVdiGNh8JqSRYPyFjOxnZAF8NVCg5gnT3Tdy/dPvi93Hd7VZ23pV2svQoBTVpaAyPzDOQYRRwn2CnfUpgcJRQCjFg6EENmGdnJ9A8XGOrZpT82odpS/DRMIxKuN5vDgRyCajzPWMAo6zk1zEUi4xKTcoXcMlbwIs8gFfiuthmYquzhKhaFrCuQYbK7EfEty8CqFBIAHGhfQQRxF9IjRgiYoSIMMbFODR4I4dmwlPCFGG8JpjHCjEXOzZSF6zOJDXPVaTm9nuwsdSsCan5zyU103lhqTmOr4htaVjuCcG1pS+QIg6B8JT/qMLVE1Voz0qFq9elwjSIYRyLUdtJjWqiwHXcox7wD9sJTw2FM9Cn/eL6NMf6NJarILisPvsD6EmBmrMSaP/YxxQ6gvykTDRlYtEyBPGvrOV7LJb271Fp6euCJqrEizzX60TenZW1leJQ/ojU/hLxo1a9bOr2AQ8lnKZWK+EzCFXT6cSW1bzolvWldXqhLavZp35OidGalxj19Mr/R4xeHMAoPa8YEwCD9Fxi9OemRlNPCK0pBG3+x8N89DASVxnbAzDyAz5rpspMY/uQygIlSadoWKM/IGq7ErxUBJWsnZ0bLtxb0RcXcd3p2dTILkkJz8NJoB40vECnxJtgxHo2RlyNkU8AleK2Iad0jURYB+KYYmJ1USa8x5iISbW7ThIClQPb1zmYSnA9Hwf+E9RwxXwcimKKkMlz1vMxome13o5TtZKM1xE8DtNUk/QYF6VHT3esxy91XhU9h/utl6fH0s+6XD3JSD5XHuVFBupUlDfti1Kin3gUxVwjC94Tdr0XjfOW/jawX6REMlWhwPvdkL7ipgPrDW/AIdkOlf3C9ll8DlDnqNqfoPlRry12vbdvGsUA17wO2ob68tc2dLqtM+0ixMva/Qcibd3oKxv77i8=</diagram></mxfile>