Versioning Overview#

You can configure Allegra to version certain item types in specific workspaces. This allows you to keep parallel versions of an item, compare versions with each other, and revert to a previous version. This feature is particularly suitable for documents in the Wiki.

Versioning of Items#

In Allegra, you can configure most item types so that they can be “versioned”. An 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 class “Document” in the Wiki are versioned, but not item types like action items, tickets, bug reports, etc. We distinguish between “explicit” and “implicit” versioning. For explicitly versionable item types, you can

  • directly create new versions

  • restore old versions

  • display old versions

  • compare versions with each other

For implicitly versionable item types, you can

  • display old versions

  • compare versions with each other

Implicit versioning means that subordinate items of a document automatically receive a new version when the document itself receives a new version. Typically, this affects document sections and embedded items. New versions of such items cannot then be directly (explicitly) created, 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 “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 explicitly created by the responsible person. Only whole documents can explicitly be committed or versioned. Document sections and embedded items are “implicitly” versioned, i.e., indirectly through the creation of a new version of the containing document.

Baselines#

A baseline is a collection of documents in a specific version. A baseline always refers to a specific branch (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 that are displayed via baselines cannot be edited. Baselines can be seen as snapshots of a branch at a specific point in time.

A baseline always refers to a single workspace or a project. In a workspace hierarchy, versioning and the baseline procedure are only supported for the leaf workspaces. Leaf workspaces are characterized by the fact that they themselves do not have any subordinate workspaces.

Branches#

Branches offer the possibility to work simultaneously on different versions of the same document. For example, a document can be in development while it also exists as a published and previous version. So you could have a “4.3 Unstable” branch and a “4.2 Final” branch, which mostly have the same documents with HEAD versions and similar, but partially different contents.

A branch always refers to a single workspace or a project. A workspace or project can have any number of branches. There is always a starting branch, which we refer to as the “Master” branch. With the exception of the main branch, all other branches have a source branch from which they originate. In a workspace hierarchy, versioning and branching are only supported for the leaf workspaces. 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 only physically copied to the new branch when they are changed. Otherwise, they are inherited from their source branch. This means in the case that a document section in the source branch is changed, the derived branch is also changed.

In Copy mode, all document areas 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 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 implicitly or not at all versioned (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 to all referencing documents. This probably does not correspond to the behavior that one usually desires.