Release range grammar

The exact syntax and matching rules of the release attribute.

Grammar

value   = token { whitespace token }
token   = version                 (* exact: that version and everything under it *)
        | version ".."            (* from: that version and later *)
        | ".." version            (* to: up to and including everything under it *)
        | version ".." version    (* from .. to *)
version = [ "v" | "V" ] digits { "." digits }
digits  = "0" .. "9" { "0" .. "9" }

Content applies when the reader's version matches any token. .. on its own is not a range, and a range whose start is after its end is invalid. Validation reports any token that does not parse as invalid-release.

Examples

Token	Matches	Does not match
`1.4`	1.4, 1.4.0, 1.4.7	1.40, 1.5, 1
`2`	2, 2.0, 2.13.1	1.9, 3.0
`2.0..`	2.0, 2.1, 10.0	1.9.9
`..1.9`	0.1, 1.0, 1.9, 1.9.12	1.10, 2.0
`1.2..1.9`	1.2, 1.5.3, 1.9.4	1.1.9, 1.10, 2.0
`v2.0..`	the same as `2.0..`
`1 3..`	any 1.x, and 3.0 and later	2.x

Matching rules

Versions compare number by number, so 1.10 is after 1.9. A missing number counts as 0 when comparing, so 2.0.. matches 2.
An exact token and the end of a range compare only as many numbers as they have. That is why 1.4 matches 1.4.7, and ..1.9 includes every 1.9.x.
An exact token with more numbers than the reader's version does not match it: 1.4 does not match a reader on 1.
The start of a range is inclusive and compares the full version.
Release values are not declared in opend.config.yaml, because they are ranges.

Reader versions and release lines

Each reader has one version, from their organization's entitlements, such as 0.1. It must be a version of the same form, with an optional leading v. A reader whose version does not parse matches no release token, so content with a release attribute is hidden from them.

On the hosted platform, a reader is served the live release of their release line: the major number of their version, or on a repository with lines by minor version its major and minor numbers. A 1.4 reader keeps getting the docs built from the branch whose release is 1.x after 2.0 is published; with minor lines, a 0.22 reader keeps the 0.22 docs after 0.23. See Document several releases with release branches and Release lines by major or minor version.