Versioning Overview¶
You can configure Allegra to version specific item types in specific workspaces. This feature allows you to keep multiple versions of an item in parallel, compare versions, and revert to a previous version, which makes it especially useful for documents in the Wiki.
Versioning of items¶
In Allegra, you can configure most item types to be “versioned”. An exception are document folders, which are not versionable. For each workspace, you can configure which item types can be versioned.
Typically, only items of the class “Document” are versioned in the Wiki, but not item types such as action items, tickets, bug reports, etc. We distinguish between “explicit” and “implicit” versioning. For explicit versionable item types you can:
Create new versions directly
Restore old versions
Display old versions
Compare versions with each other
For implicitly versionable item types you can:
Display old versions
Compare versions
Implicit versioning means that subordinate items in a document automatically receive a new version when the document itself receives a new version. This typically affects document sections and embedded items. New versions of such items cannot be created directly (explicitly), but only indirectly via the (explicit) creation of a new version of the superordinate document.
Versions¶
In Allegra, a (Wiki) document can have any number of versions. The most recent version is called “HEAD”. Only the HEAD can be changed with the document editor, all the other versions are unchangeable.
It is possible to revert to a previous version. In this case, a copy of the old version is created and copied into the HEAD. It is also possible to delete the oldest versions and keep only the last x versions or all versions belonging to a baseline.
A new document version is created explicitly by the processor. Only whole documents can be explicitly committed or versioned. Document sections and embedded items are versioned “implicitly”, that is, indirectly by creating a new version of the containing document.
Baselines¶
A baseline is a collection of documents in a particular version, which always refers to a particular branch. Documents belonging to a baseline can contain links to other documents in other baselines, e.g., from other branches or workspaces.
Baselines are immutable, meaning that items that are displayed using baselines cannot be edited. Moreover, baselines can be viewed as snapshots of a branch at a particular point in time.
A baseline always refers to a single workspace or project. In a workspace hierarchy, versioning and baselining are only supported for leaf workspaces. Leaf workspaces are characterized by the fact that they have no subordinate workspaces.
Branches¶
Branches offer the possibility to work on different versions of the same document at the same time. For example, a document may be under development while also existing as a published and previous versions. So you might have a “4.3 Unstable” branch and a “4.2 Final” branch, which have mostly the same documents with HEAD versions and similar, but sometimes different content.
A branch always refers to a single workspace or project. A workspace or project can have any number of branches. There is always an initial branch, which we refer to as the “master” branch. With the exception of the master branch, all other branches have a source branch from which they originate.
There are two types of branches:
Inheritance mode
Copy mode
In both modes, the document structure and the surrounding document are physically copied to the target branch. In inheritance mode, the document sections are physically copied to the new branch only when they are changed. Otherwise, they are inherited from their source branch. This means that if a document section in the source branch is changed, the derived branch is also changed.
In copy mode, all document sections of the source branch are copied to the target branch. This means that changes in the source branch have no effect on the target branch.
Versioning embedded items¶
It is possible to embed items in the description text of a document or document section. Items referenced in this way should be implicitly versioned, or not versioned at all (see “Versioning of items”).
The explicit versioning of documents with the implicit versioning of embedded items is the standard case. If embedded items are not versioned, a change to such an item leads to changes of all referencing documents. This is probably not the behavior that is usually desired in such cases.