gdritter repos gitnode / master DESIGN.md
master

Tree @master (Download .tar.gz)

DESIGN.md @masterview markup · raw · history · blame

GitNode Design Document

Interoperability

One major design goal of GitNode is to allow GitNode instances to interoperate—that is, to support pull requests and collaboration between GitNode instances. To do this, GitNode repos can include a "link file", which is a special metadata file including metadata like:

  • what kind of information the original endpoint accepts: pull requests, issues and bug reports, wiki pages, &c.
  • the original HTTP location of the repo
  • the original API endpoint of that repo
  • the "API style" of the repo in question
  • recursive data on the above, if the original repo also included a link file.

For example, if I maintain a GitNode instance at http://gitnode.gdritter.com/ and have a project called my-project, then the HTTP location of my repo is http://gitnode.gdritter.com/p:my-project, the API endpoint is http://gitnode.gdritter.com/api, and the API style is gitnode. If my friend clones this repo to http://gitnode.moreproductive.com/p:my-project, then those values are stored in the repo metadata. Consequently, his gitnode instance knows how to submit a merge request back to my instance.

If I clone a repo from GitHub, then the link file can also be generated automatically: this allows a GitNode instance to host a project, but

User-Facing

API

The API is modeled after GitHub's API, but is missing all the features that GitNode also lacks: for example, GitNode has no notion of users or organizations, so a GitHub endpoint like /orgs/... is not provided. You can always issue a GET request to the root endpoint in order to discover which endpoints are supported.