Version tracking of label trees

[mzur]

All changes to a label tree should be tracked. The complete version history of a label tree should be visible to label tree members. Changes include:

• Changing the name of the label tree
• Adding a label
• Moving a label to another parent
• Renaming a label
• Changing the color of a label
• Deleting a label

Maybe this can be implemented with the help of a VCS like Git?

[mzur]

First draft

This can be implemented with the following DB schema (might not be equal to the filnal implementation):

label_trees

• id
• visibility_id
• created_at
• updated_at
• uuid

label_tree_versions

• id
• created_at
• label_tree_id
• name
• description
• user_id

A label tree version stores the current state of a label tree (i.e. the current name, description and labels). They can be ordered by their ascending IDs. Whenever the name, description or a label is changed, a new version is created.

label_tree_tags

• id
• label_tree_id
• label_tree_revision_id
• name
• description

This is like a Git "tag" for label trees. A label tree tag can be attached to a label tree version. It consists of a short name (e.g. "v1.2") and an optional description text (in Markdown?).

labels

• id
• source_id
• label_source_id
• uuid

label_versions

• id
• created_at
• label_id
• name
• parent_id
• color
• user_id

This works similar to a label tree version. Whenever the name, parent or color of a label is changed, a new label version is created. This also creates a new label tree version. When a new label is created or a label is "deleted", a new label tree version is created as well. Labels are not actually deleted ever. They are just not associated with the most recent label tree version any more.

If a label is modified, all annotations are updated to use the new label version. Exception: If a project uses a specific tag of a label tree (biigle/core#174) its annotations are not updated.

Problem: How to decide which label tree tag should be used for a volume that is shared between multiple projects? Should we finally ditch the ability to share volumes?

Problem: If there are annotations from multiple versions of a label tree in a project, how to allow users to select a specific label (e.g. in Largo)?

label_tree_version_label_version

• label_tree_version_id
• label_version_id

Pivot table for the associations between label versions and label tree versions. This gets updated whenever the label tree or a label is changed.

[mzur]

Second draft

This approach aims o resolve the problems identified by the first draft.

In this approach, every change to a label tree is not tracked. Instead, users have the option to create ("tag") a new version of a label tree with a click on a button. This effectively copies the whole label tree including all its labels and associates it with the original label tree. A label tree version cannot be modified. It can be deleted if none of its labels are used. Since tagged label tree versions cannot be modified, we don't have the problem of how existing annotations with the labels should be treated if a label is renamed.

Projects can be associated with a label tree version as if it was an entirely different label tree. The annotation tool and Largo etc. simply shows a list of all associated label trees, which could even be multiple versions of the same label tree. This solves the problem of how to decide which label tree version to use if projects share a volume.

New database schema:

label_trees

• id
• version_id (!=null if this is a tagged version of another label tree)
• name
• description
• visibility_id
• created_at
• updated_at
• uuid

label_tree_versions

• id
• label_tree_id (the "master" label tree from which the version was created)
• name

The name is a short tag like "v1.2".