Versioning overview

Versioning overview#

You can configure Allegra so that certain item types are versioned in certain workspaces. This allows you to keep several versions of an item in parallel, compare versions with one another and revert to a previous version. This feature is particularly useful for documents in the wiki.

Versioning of items#

In Allegra, you can configure most item types so that they can be “versioned”. One exception is document folders, which cannot be versioned. Which item types can be versioned is configurable for each workspace type. Typically, only items of the “Document” class are versioned in the wiki, but not item types such as action items, tickets, defect reports, etc. We distinguish between “explicit” and “implicit” versioning. For explicitly versionable item types, you can

  • create new versions directly

  • restore old versions

  • display old versions

  • compare versions with one another

For implicitly versionable item types, you can

  • display old versions

  • compare versions with one another

Implicit versioning means that the child items of a document automatically receive a new version whenever the document itself receives a new version. Typically, this affects document sections and embedded items. New versions of such items cannot then be created directly (explicitly), but only indirectly through the (explicit) creation of a new version of the parent document.

Versions#

In Allegra, a (wiki) document can exist in any number of versions. The most recent version is called the “HEAD”. Only the HEAD can be changed with the document editor; all other versions are immutable. 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 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 responsible. Only entire documents can be committed or versioned explicitly. Document sections and embedded items are versioned “implicitly”, i.e. indirectly through the creation of a new version of the containing document.

Baselines#

A baseline is a collection of documents in a particular version. A baseline always refers to a particular branch. Documents that belong to a baseline can contain references (links) to other documents in other baselines, e.g. from other branches or workspaces.

Baselines are immutable; items displayed via baselines cannot be edited. Baselines can be regarded 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 the baseline procedure are supported only for the leaf workspaces. Leaf workspaces are characterized by the fact that they themselves have no sub-workspaces.

Branches#

Branches offer the possibility of working on different versions of the same document simultaneously. For example, a document may be in development while it also exists as a published and a previous version. You could therefore have a branch “4.3 Unstable” and a branch “4.2 Final”, which mostly contain the same documents with HEAD versions and similar but partly 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. In a workspace hierarchy, versioning and branching are supported only for the leaf workspaces. There are two types of branching:

  • Inheritance mode

  • Copy mode

In both modes, the document structure and the surrounding document are physically copied into the target branch. In inheritance mode, the document sections are physically copied into the new branch only when they are changed. Otherwise, they are inherited from their source branch. This means that if a document section is changed in the source branch, the derived branch is changed as well.

In copy mode, all document sections of the source branch are copied into the target branch. This means that changes in the source branch have no effect on the target branch.

Versioning of 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 versioned implicitly or not at all (see “Versioning of items”).

The explicit versioning of documents combined 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 in all referencing documents. This is probably not the behavior one would usually want.

Contents