OSF Revisioning Design

Introduction
A record revisioning system for OSF is a set of new mechanisms that will enable users and developers to create revisions (versions) of individual OSF records. All versions of a record's description will be saved in a different revisions dataset. Users will be able to check older revisions for a particular record, they will be able to list all revisions of a record. They will also be able to check differences between versions and they will be able to check future versions to be published for a record. This document outline the design of the OSF Revisioning system.

Required Behaviors
A record revisioning system should at least meet these requirements by being able to:
 * Get a complete list of all revisions for a record
 * Specify if we want to create a new revision, or not, for a record that is being updated
 * This would only be possible if the record to update is already published
 * Delete all revisions for a record
 * Delete a single revision for a record
 * Revert the record currently published in the dataset to a previous revision
 * Update a specific revision status of the record
 * 'Diff' two revisions of a record
 * Create unpublished revisions that waits to be moderated. These unpublished revisions are revisions that are more recent than the current version of a record available in the dataset, and will eventually replace it after moderation.
 * Revision reified statements of the records.

Revisioning Method
The revisioning method designed in this document is one that will save the complete description of a record every time a new revision is being created. This means that every time a new revision is created, all the triples, including reified triples, will be saved in the revision. An alternative method would be to save the triples that changed (so, the difference between two records' description) using a method such as the one that uses the ChangeSet.

Now, let's outline the advantages and disadvantages of the revisioning method outlined in this document.

Advantages

 * 1) Less space consumed for smaller records with a lot of changes per revision
 * 2) Reverting to a previous revision is fast since the complete state of a record exists in its revision record; a single read query is required
 * 3) Comparing two non-concurrent revisions is faster than with the ChangeSet method since the time to compare these two non-concurrent revisions is the same as if they were concurrent.
 * 4) Can easily revision reification statements.

Disadvantages

 * 1) More space consumed for big records with a small number of changes per revision
 * 2) Comparing two concurrent revisions needs to be done at runtime with the RDF Diff API.

Revisions Scenarios & Structures
In this section we outline different revisioning scenarios that can happen, and for each of these scenario, we show what the revision structure looks like.