Skip to content
Menu
OpenD Documentation
Version 0.1
Sign in

Document several releases with release branches

Keep one branch or tag per major release, and use release ranges for the differences between minor releases inside it.

About this task

Both tools work together. A branch per major release keeps old docs stable while new work lands on main. Ranges within a branch avoid copying a topic for every minor release: a step marked release="2.1.." appears for 2.1 readers and later, and is hidden from 2.0 readers.

  1. Create a branch for the release you are freezing, such as v1, and set release in its opend.config.yaml, for example to '1.4'.
  2. On main, set release to the next major version, such as '2.0'.
  3. Preview or validate any branch without checking it out. 
    pnpm opend preview path/to/docs --ref v1 --version 1.4
pnpm opend validate path/to/docs --ref v1
  4. Make sure the docs repository's release refs include every branch that publishes.

    A repository registered with "releaseRefs": ["main", "v*"] publishes pushes to main and to any branch or tag starting with v; * matches any run of characters. The default is ["main"].

Results

Each successful build goes live for its release line, the major number of its release. Readers get the line matching their own version, so 1.x and 2.x docs are live side by side. A repository can group releases by minor version instead, so 0.22 and 0.23 are lines of their own; see Release lines by major or minor version. A build replaces the live release of its line only if it comes from a newer push, so a slow build of an old commit cannot overwrite a newer one.

For the exact range syntax, see Release range grammar.