This documentation is built with

mdbook build

Or tested in a local browser, with live updates with

mdbook serve --open

The mdbook binary can be downloaded from https://github.com/rust-lang/mdBook/releases

Keyword reference and versions

The book documents the newest agent release, at one URL. It is not snapshotted per release: a release changes a fraction of a percent of the reference — three keywords of 8956 between rc40 and rc41 — and there is a release most weeks, so a copy per release would duplicate the whole corpus fifty times a year, split the search results between fifty near-identical sites, and answer no question the timeline below does not answer better.

A new book is started when a major line starts, which is what docs.opensvc.com (v2) and book.opensvc.com (v3) already are.

What is generated, and from what

The reference of a release is generated by the binary of that release and attached to it as keywords-<tag>.tar.gz. The book takes it from there rather than running an agent of its own: a binary built without make version names a version it is not, and a book generated from it documents a release that never existed.

make kw KEYWORDS_VERSION=v3.1.0                            # from the release
make kw KEYWORDS_TARBALL=/path/to/keywords-v3.1.0.tar.gz   # from a file
make                                                       # summary + build

That one command lays down the reference, updates the timeline and rewrites the two generated pages:

• index.json, the corpus of the release: one entry per keyword, the properties a change is worth reporting, and a fingerprint of the prose rather than the prose.
• history.json, the timeline: when each keyword appeared, when it went away, and what moved in between. It is the only place a removed keyword can be recorded, a release having nothing to say about what it does not carry. Six releases of it weigh 74 KB gzipped, and it is overwritten in place, so git keeps the history without keeping a copy of the corpus per release.
• changes.md, what each release added, removed and changed.
• removed.md, the keywords no release documents any more, and the last one that did.

Prose that depends on the version

The pages under src/agent describe the newest release too. Where a behaviour changed, say so in place rather than forking the page:

Since 3.4 a stop no longer freezes the instances of the object. Before
that, it did, and an operator had to unfreeze them to put the object
back under orchestration.

The agent CHANGELOG remains the upgrade document. This is for the sentence a reader would otherwise act on without knowing it changed.