Versioning

The Nuxeo Repository includes a versioning system. At any moment, you can ask the repository to create and archive a version from a document. Versioning can be configured to be automatic (each document modification would create a new version) or on demand (this is bound to a radio button in default UI).

Each version has:

• A label,
• A major version number,
• A minor version number.

The versioning service is configurable so you can define the numbering policy. In fact, even the version storage service is pluggable so you can define your own storage for versions.

Functional Overview

When you edit a document, you can decide to save your modifications as a new version of the document. This enables you and other users to easily revert to a specific version of the document if needed, without having to edit the document. Versions are accessible from the History tab of the document.

You have several options regarding the versioning of your document.

Every document holds a version number, which is a piece of information about the evolution of the document. A version number (V.v) is composed of a major version number (V) and a minor version number (v). When a document is created, its version number is 0.0. Minor version increment are used for secondary changes. Major version increment is usually reserved to significant modifications.

Let's say that your current document version is 0.1:

• You can save modifications without creating a new version of the document, as it is not yet ready. The 0.1 version of the document has been modified, so its version number becomes 0.1+ (the + indicates to other users that version 0.1 has been modified).

  If you haven't actually done any modification on the document when you click Save, the version remains 0.1, you are not added to the contributors of the document and the last modification time is not updated.

• You can save the modifications in a new version of the document. The version number will then be 0.2 if you increment minor version or 1.0 if you save modifications in a major version. The newly created version is automatically archived in the History tab so it's not lost when users will edit it.

  Version number 0.0

  When a document is created, its version number is 0.0. This is considered as a draft of the document, which will need to be saved into a first version, either minor or major.

  Draft version 0.0 is not archived and the + behavior described above does not apply to 0.0 draft.

Nuxeo Drive Versioning Policy

When you edit a document, either from your Nuxeo Drive folder or using the online editing, a new version is automatically created on the Platform and the version number is updated:

• If you are not the last contributor of the document
• Or if your last edit is more than an hour ago

Then, if your document's version was 1.0 before modification for instance, it automatically becomes 1.1+ after you edited it from the Nuxeo Drive folder and the 1.1 is archived as it is created. Otherwise, a simple modification is done on the document and logged in the document's History.

See the page How to Customize Nuxeo Drive Versioning Policy to change this behavior.

Drag and Drop Versioning Policy

When you drag and drop a document in a workspace its version is 0.0, like every new document created on your platform.

The drag and drop versioning policy uses the minor version incrementation so, if you edit one these documents in local and reupload it with another drag and drop, the version number becomes 0.1+, then 0.2+, etc.

Concepts

• Placeful. A placeful document is one which is stored in a folder, and therefore has a parent in which it is visible as a child.
• Placeless. A placeless document isn't stored in a given folder, it's just available in the storage through its id. Having no parent folder it doesn't inherit any security, so it is usually only accessible by unrestricted code.
• Working Copy. The document that you edit. It is usually stored in a Workspace's folder but this is just convention. It is also often called the Live Document. There is at most one Working Copy per version series. In other systems it is also called the Private Working Copy because only the user that created it can work on it; this is looser in the Nuxeo Platform.
• Version. An immutable, archived version of a document. It is created from a working copy by a check in operation.
• Version Number. The label which is uniquely attached to a version. It formed of two integers separated by a dot, like "2.1". The first integer is the major version number, the second one is the minor version number.
• Major Version. A version whose minor version number is 0. It follows that a minor version is a version whose minor version number is not 0.
• Version Series. The list of versions that have been successively created from an initial working copy. The version series id is a unique identifier that is shared by the working copy and all the versions of the version series.
• Versionable Document. The document which can be versioned, in effect the working copy.
• Check In. The operation by which a new version is created from a working copy.
• Check Out. The operation by which a working copy is made available.

Check In and Check Out

"Check In" and "Check Out" in the Nuxeo Platform both refer to operations that can be carried out on documents, and to the state a working copy can be in.

Checked In and Checked Out States

A working copy in the Checked Out state can be modified freely by users having access rights to the document. A document ceases to be Checked Out when the Check In operation is invoked. After initial creation a document is in the Checked Out state.

A working copy in the Checked In state is identical to the version that was created when the Check In operation was invoked on the working copy. In the Checked In state, a working copy is (at low level) not modifiable. To be modified it must be switched to the Checked Out state first. This latter operation is automatically done in the Nuxeo Platform when a document is modified.

Check In and Check Out Operations

From a working copy in the Checked Out state, invoking the Check In operation does several things:

• the final version number is determined,
• a new version is created,
• the working copy is placed in the Checked In state.

When invoking the Check In operation, a flag is passed to indicate whether a major version or a minor version should be created. Depending on whether the new version should be major or minor, the version number is incremented differently; for instance, starting from a working copy with the version number "2.1" (displayed as "2.1+"), a minor version would be created as "2.2" and a major version as "3.0".

Given a Checked In working copy, invoking the Check Out operation has little visible effect, it's just a state change for the working copy. A "+" is displayed after the version number to make this apparent, see below. If no modification was actually done on the document when the user clicks Save and invokes the Check Out operation, the version working copy remains in the Checked In state: the dc:contributors and dc:modified fields are not updated and no "+" is displayed next to the version number.

Version Number

The initial version number of a freshly created working copy is "0.0".

When displaying the version number for a Checked Out document, the version number is usually displayed with a "+" following it, to show that it's not the final version number but that the working copy is modified and derived from that version. The final version number will be determined at Check In time. The exception to this display rule is the version "0.0", because displaying "0.0+" would be redundant and misleading as there is actually no previously archived "0.0" version from which it is derived.

The version number is changed by a Check In operation; either the minor version number is incremented, or the major version number is incremented and the minor version number is set to 0.

Plugging In a New VersioningService Implementation

For advanced uses, it's possible to plug in a new VersioningService implementation to define what happens at creation, save, check in and check out time. See the Javadoc and the versioningService extension point documentation for more about this.