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.