1# Data model
 2
 3The biggest problem when creating a distributed bug tracker is that there is no central authoritative server (doh!). This imply some constraint.
 4
 5## Anybody can create and edit bugs at the same time as you
 6
 7To deal with this problem, you need a way to merge these changes in a meaningful way.
 8
 9Instead of storing directly the final bug data, we store a series of edit `Operation`. One of such operation could looks like this:
10
11```json
12{
13  "type": "SET_TITLE",
14  "title": "This title is better"
15}
16```
17
18Note: Json provided for readability. Internally it's a golang struct.
19
20These `Operation` are aggregated in an `OperationPack`, a simple array. An `OperationPack` represent an edit session of a bug. We store this pack in git as a git `Blob`, that is arbitrary serialized data.
21
22To reference our `OperationPack` we create a git `Tree`, that is a tree of reference (`Blob` of sub-`Tree`). If our edit operation include a media (for instance in a message), we can store that media as a `Blob` and reference it here under `"/media"`. 
23
24To complete the picture, we create a git `Commit` that reference our `Tree`. Each time we add more `Operation` to our bug, we add a new `Commit` with the same data-structure to form a chain of `Commit`.
25
26This chain of `Commit` is made available as a git `Reference` under `refs/bugs/<bug-id>`. We can later use this reference to push our data to a git remote. As git will push any data needed as well, everything will be pushed to the remote including the medias.
27
28For convenience and performance, each `Tree` reference the very first `OperationPack` of the bug under `"/root"`. That way we can easily access the very first `Operation`, the `CREATE` operation. This operation contains important data for the bug like the author.
29
30Here is the complete picture:
31
32```
33 refs/bugs/<bug-id>
34       |
35       |
36       |
37 +-----------+          +-----------+           "ops"    +-----------+
38 |  Commit   |---------->   Tree    |-------|------------|   Blob    | (OperationPack)
39 +-----------+          +-----------+       |            +-----------+
40       |                                    |
41       |                                    |
42       |                                    |   "root"   +-----------+ 
43 +-----------+          +-----------+       |------------|   Blob    | (OperationPack)
44 |  Commit   |---------->   Tree    |       |            +-----------+
45 +-----------+          +-----------+       |
46       |                                    |
47       |                                    |   "media"  +-----------+    +-----------+
48       |                                    +------------|   Tree    |--->|   Blob    | bug.jpg
49 +-----------+          +-----------+                    +-----------+    +-----------+
50 |  Commit   |---------->   Tree    |
51 +-----------+          +-----------+
52```
53
54Now that we have this, we can easily merge our bugs without conflict. When pulling bug's update from a remote, we will simply add our new operations (that is, new `Commit`), if any, at the end of the chain. In git terms, it's just a `rebase`.
55
56## You can't have a simple consecutive index for your bugs
57
58TODO: complete when stable in the code
59
60--> essentially a semi-random ID + truncation for human consumption
61
62## You can't rely on the time provided by other people (their clock might by off) for anything other than just display
63
64TODO: complete when stable in the code
65
66--> inside a bug, we have a de facto ordering with the chain of commit
67
68--> to order bugs, we can use a Lamport clock + timestamp when concurrent editing