Component Versions and Branches

Versions of a documentation component are stored in branches in a version control repository such as git. The name of the branch itself doesn’t matter. It’s the version property in the component descriptor that determines the name of the version for the component.

Branches as versions

Like with software, we use branches to store different versions of the documentation. Branches are ideally suited for managing multiple versions of the same content.

If we didn’t use branches to specify versions, but instead used folders with trailing version numbers, all stuffed in a single branch, then we’d have to explicitly duplicate all the files in a documentation component for each version. And we’d have no easy way to compare, manage, and merge different instances of a document.

Branches handle all this for us. Creating a new branch is extremely cheap. You simply create a new branch from an existing reference in the repository, and the repository only stores what’s changed since that branch point.

Setting the version for a branch

To set the version of documentation stored in a particular branch, you specify the version in the component descriptor:

name: versioned-component
version: '2.1'
title: Versioned Component

This component descriptor communicates that the files taken from this branch contribute to the 2.1 version of the component named versioned-component. The name of the branch could be v2.1 or v2.1-beta. It doesn’t matter.

The component descriptor is the only file you have to update when creating a new branch. All the page references for that component should be relative to the version, so you shouldn’t need to update any links. The next time you run Antora on the repository, you’ll see a new version in the component explorer drawer.

You may need to add the branch to your playbook file. Keep in mind that content sources are filtered by branch name, not by the version they contain. That’s because a single version can be spread out across multiple branches, or even multiple repositories.

How Antora sorts versions

Antora sorts the versions of each component. Understanding how Antora sorts versions is important when choosing your versioning scheme so you can achieve the ordering you want.

Antora applies the following rules when sorting component versions:

  • Separate named versions from semantic versions.

    • A semantic version is identified either as an integer (e.g., 2 or 30) or a string that starts with a digit and contains at least one “.” character (e.g., 2.0.1 or 30.5). A semantic version may begin with an optional leading “v” (e.g., v2.0.1), which is ignored when sorting.

    • All other versions are assumed to be named versions.

    • Although the version named master has special meaning when creating URLs for a component version, it’s given no special treatment when sorting.

  • Sort named versions (including master) in reverse (i.e., descending) alphabetical order and add them to the list.

    • The assumption is that named versions that fall later in the alphabet are newer.

    • Upper characters come before lower characters (e.g., "`A"` comes before "`a"`, meaning it’s newer)

  • Sort semantic versions in descending order and add them to the list.

    • Discard the leading “v”, if present.

    • Apply the ordering rules for semantic versioning as defined by https://semver.org.

Here’s an example of a version list that has been sorted according to these rules:

wily
vivid
utopic
v3.10
v3.9
v2.0

Whenever Antora displays versions in the UI, it presents them in this order. Bear in mind that if a display version is specified, the display version is shown instead. The display version allows the sortable version to differ from the version displayed in the UI. Thus, to the reader’s eyes, the versions may not appear to be sorted in the order described.

Prerelease versions

A version may be designated as a prerelease version by assigning a value to the prerelease property in antora.yml. For example:

name: versioned-component
version: '2.2'
prerelease: Beta
title: Versioned Component

This assignment has two consequences:

  • If the value of the prerelease property is a non-empty string, and the display_version is specified, the prerelease value is appended to the value of the version property to generate the display_version (e.g., 2.2 Beta).

    • If the prerelease value begins with a hyphen (-) or dot (.), no space is added when appending the prerelease value.

    • Otherwise, the prerelease value is separated from the version value by a single space.

    • If the display_version key is set, that value overrides the computed value just described.

  • The version will be skipped when determining the latest version (unless all versions are prerelease versions, in which case it is not skipped).

Choosing the latest version

In addition to sorting versions, Antora selects the latest version of each component. The sorting rules previously covered impact how the latest version is selected.

The latest version is normally the first version in the sorted list that’s not a prerelease. However, if all versions are prereleases, then the first version in the list is selected.

Antora uses the latest version when qualifying a resource ID if it cannot otherwise determine the version. It also uses the latest version when determining the default URL for a component.

The latest version is available as a property on each component in the UI model. The latest version information is typically used to inform the reader if there’s a newer version of the documentation available.

Versionless URLs

The version of the component is normally included as a segment in the URL of publishable files. For example, if the version is a named version like latest or a semantic version like 2.1, that value will appear in the URL (and, by association, the output path) of these files (e.g., /component-name/2.1/page-name.html).

The exception to this rule is if the version matches the reserved word master. In this case, Antora does not include the version segment in the URL for publishable files in that component version.

Here’s an example of a component version that will have versionless URLs:

name: tutorials
version: master
title: Tutorials

A page with the filename build-a-restful-web-service.adoc in this component version would have the URL /tutorials/build-a-restful-web-service.html. When making a qualified reference to this page, you’d still include the version as you normally would (e.g., master@tutorials::build-a-restful-web-service.adoc).

If the component only has a single version, and that version matches the reserved word master, we say that the component is a versionless component. That’s because when the component only has one version, and that version doesn’t show up in the URL, it appears to the reader as though the component has no versions. Most often, the master version is only used when making a versionless component.