Identify a Prerelease Version

The prerelease key identifies a component version as a prerelease. The prerelease key does not create a unique version. Rather, it provides a hint that the version is not a candidate to be the latest version.

prerelease key

The prerelease key is optional. A component version is identified as a prerelease when the prerelease key is assigned a user-defined identifier, such as -beta.2, or the boolean value true. Note that setting the prerelease key does not make the version unique. In fact, that’s the whole point. The identify of the component version remains exactly the same when the prerelease key is removed.

Antora doesn’t apply the default routing rules to a component version designated as a prerelease, even if it’s the latest version in that docs component (unless all versions of that docs component are prereleases). When a component version is ready to graduate from a prerelease to a stable release, change the value of the prerelease key to false or delete the key and its value from the antora.yml file.

To learn more about the capabilities the prerelease key provides and compare it to the other version facets—actual version, display version, and symbolic version—see Version Facets.

Assign an identifier to prerelease

A component version becomes a prerelease when the prerelease key is set in antora.yml and assigned an identifier. An identifier is a user-defined, non-empty string such as .alpha.2, -M1, SNAPSHOT, and -rc.5. It can contain uppercase letters and a broad range of characters. The component version defined in Example 1 is a prerelease.

Example 1. antora.yml with prerelease assigned the identifier -rc.3

name: colorado
title: Colorado ∆
version: '6.0.0'
prerelease: -rc.3 (1)

1	Assign an identifier to `prerelease` to designate the component version as a prerelease.

When prerelease is assigned an identifier, Antora computes an internal prerelease version value for UI sorting and, if display_version isn’t set, for display purposes. This computed prerelease version depends on the first character in the prerelease identifier.

Identifiers that begin with a hyphen (-) or dot (.)

The computed prerelease version takes the form of version-identifier or version.identifier. Antora directly appends the prerelease identifier to the version key’s value to compute the prerelease version. For instance, using Example 1, the computed prerelease version would be 6.0.0-rc.3.

Identifiers that begin with any other valid character

The computed prerelease version takes the form of version identifier. Antora separates the identifier from the version key’s value with one blank space to compute the prerelease version.

Example 2. antora.yml with prerelease assigned the identifier Beta

name: colorado
title: Colorado ∆
version: '4.0'
prerelease: Beta

Using Example 2, the computed prerelease version would be 4.0 Beta.

Unless the display_version key is set in antora.yml, Antora assigns the computed prerelease version to display_version at runtime. If display_version is defined in antora.yml, then that value is displayed in the UI. However, the component version is still sorted according to the internally computed prerelease version value.

Assign true to prerelease

A component version becomes a prerelease when the prerelease key is set in antora.yml and assigned the value true.

Example 3. antora.yml with prerelease defined as true

name: colorado
title: Colorado ∆
version: '6.5.0-snapshot'
prerelease: true

When prerelease is true, the component version is sorted by the value of version but the default routing rules aren’t applied to it even if it’s the latest version in that docs component.

Prerelease sorting and routing

Prerelease versions are skipped when Antora selects the latest version of a docs component unless all component versions are prereleases, in which case the default rules apply. They’re sorted according to the versioning scheme criteria the computed prerelease version meets.

Promote a prerelease to stable

When a component version is ready to graduate from a prerelease to a stable release, change the value of the prerelease key to false.

Example 4. antora.yml with prerelease defined as false

name: colorado
title: Colorado ∆
version: '6.0.0'
prerelease: false (1)

1	Remove the previous value and replace it with `false` to promote the component version to a stable release.

The default routing and sorting rules are applied to a component version when prerelease is set to false. Alternatively, you can delete the key and its value from antora.yml once it’s stable.