Release lines by major or minor version

Each release line has one live release. Lines group releases by major version, or by minor version for products whose customers are each on a specific 0.x minor.

About this task

A reader is served the live release of their own line, worked out from the version they are served: their organization's version, or the one the version picker gives them. By default a line is a major version: 2.1 and 2.4 readers both read line 2, whose live release is the newest 2.x build. A product released as 0.21, 0.22 and 0.23 needs a line per minor version instead, or every 0.x reader gets the newest 0.x docs.

Setting	Line of release 0.23.1	A 0.22 reader gets
`major` (default)	`0`	The newest 0.x build
`minor`	`0.23`	The live 0.22 build, or "No documentation has been published for release 0.22.x yet"

Choose lines by minor version for the repository: in the admin console, on the Site & access page under Release lines, select By minor version and Save release lines; or through the admin API.
```
H="authorization: Bearer $OPEND_ADMIN_TOKEN"
curl -X PUT "$PUBLIC_URL/admin/api/repos/1/release-lines" -H "$H" -H 'content-type: application/json' \
  -d '{"releaseLines":"minor"}'
```
Or give releaseLines when registering the repository with POST /admin/api/repos, or in a seed file next to the repository: releaseLines: minor. Or let the repository say so, in the site block of its opend.config.yaml: site: { releaseLines: minor }. The first build that goes live switches the lines, and the console then shows the setting read-only (Set the site up from opend.config.yaml).
The change applies at once, in one transaction, to what is already live: each live release moves to the line its release belongs to. Nothing that is not live comes back by itself: after switching from major to minor, line 0 becomes the line of its live release (say 0.23), and older minors go live again with their next build (request one with POST /admin/api/repos/:id/builds). Switching back merges lines, keeping the newest build of each. A build that finishes during the switch publishes to a line of the new setting. The change is audited as repo.release-lines, and every replica drops its caches. The console's form does the same, audited under the staff reader's name; saving the grouping already in place changes nothing. See Run your site from the admin console.
Publish each minor from its own branch, for example docs/0.23 with releaseRefs ["docs/*"], and release: "0.23.0" in that branch's opend.config.yaml.
See Document several releases with release branches. GET /admin/api/repos/1/releases lists the live line of each.

Results

With the version picker

A version served through the version picker maps to its line the same way: on a minor repository, a reader who chooses 0.21 is served the live 0.21 build. A list offers only the versions whose line is live, so a line not yet built, or retired, is left out of the menu, and a choice of it falls back to the reader's own version. The live mode offers every live line with no list at all. See Let readers choose the version they read.

A public site on the newest version, with older ones to choose

For product docs published per minor, where anonymous visitors should land on the newest version and may switch to older ones, set this once:

curl -X PUT "$PUBLIC_URL/admin/api/repos/1/access" -H "$H" -H 'content-type: application/json' \
  -d '{"access":"public","publicEntitlements":{"products":["core"],"features":[],"version":"latest"}}'
curl -X PUT "$PUBLIC_URL/admin/api/repos/1/versions" -H "$H" -H 'content-type: application/json' \
  -d '{"mode":"live"}'

With 0.21, 0.22 and 0.23 live, anonymous visitors get 0.23 at every address, with a menu of 0.23, 0.22 and 0.21. When the 0.24 build goes live it becomes the default and joins the menu, and a retired line leaves it, with no admin call. Signed-in readers start on their own organization's line and can switch the same way. To pin the versions instead, give a version such as "0.23" and {"mode":"list","versions":["0.23","0.22","0.21"]}, and update both after each release.