Hierarchy

A the root of the forge, we find users. Each user has several projects which contains repositories, issues, pull requests, milestones, releases, topics and labels.

Note: a repository is a git repository and a project contains one or several git repositories.

For example:

user/
     ...
     _identifiers.json     
     20.json
     20/project/
                _identifiers.json
                1.json
                1/issue/
                        _identifiers.json
                        3.json
                        3/comment/
                                  _identifiers.json
                                  7.json
                                  7/attachment/
                                              _identifiers.json
                                              20.json
                                              20/content
                1/pull_request/
                               _identifiers.json
                               6.json
                1/release/
                          _identifiers.json
                          1.json
                          1/asset/
                                 _identifiers.json
                                 10.json
                                 10/content
                1/label/
                        _identifiers.json
                        2.json
                        3.json
                1/milestone/
                            _identifiers.json
                            8.json
                            9.json
                1/topic/
                        _identifiers.json
                        1.json
                        3.json
                1/repository/
                             _identifiers.json
                             1.json (name="", vcs="git")
                             1/ (bare git repository)
                             2.json (name=".wiki", vcs="git")
                             2/ (bare git repository)
      30.json
      ...

At each level of the hierarchy we have a json file (named after the index property: index.json) to describe the resource. There is then a folder named after the index property which contains a representation of all its sub-hierarchy.

At each level, folder names correspond to the json files containing the schema; this schema describes the structure of each json files in this folder. In the example above, user/20/project/1/issue/3.json is describe by the schema issue.json.

Reactions (emojis) are described by the reaction.json file, but it would be space consuming to create a json file for each reaction in a comment. For this reason, reactions are directly included to the json file of the comment. Keeping this in mind, the same decision is applied for review comments or labels.

Attachements

What is an attachement?

It’s a file with arbitrary content (iamge, tarball, etc.), which is linked to another thing, for example, a comment or a release. Each attachement has a unique identifier (index property in json files). Attachements are stored in a folder named with this id (<id>/content). The json file describing an attachement is stored in a file named <id>.json. The content_type property of the json file will precisely indicate the type of the resource.

Repository

A repository is, as you might expect, the code but it also comes with a json file that describes each sub folders. In the previous example, we can see that our project has two git repositories, one for the code (user/20/project/1/repository/1.json) and another for the wiki (user/20/project/1/repository/2.json).

Identifiers

Pairs of identities mapping one forge to another. The first element is the id in the remote forge, the second element is the id in the local forge.

The problem it solves is that, for example, the first time you mirror an issue from a remote forge to your local forge, it is created and has an identifier.

A week later, when you refresh the issue on your local forge to get modifications from the remote forge, you need to match the identifier of the issue on your local forge with the identifier of the issue on the remote forge.