Identify a Prerelease Version
The prerelease
key identifies a component version as a prerelease.
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
.
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.
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 Betaname: 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
.
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
.
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.