Skip to content

Versioning

The platform and each kit are versioned separately, by Semantic Versioning 2.0.0. They are separate deliverables — a kit is a service you choose to deploy or not — so one number for all of them would say nothing about any of them.

Semantic Versioning's first clause is that software using it must declare a public API, because MAJOR, MINOR and PATCH are defined relative to that and to nothing else. This page is that declaration.

What is promised

For a kit, the versioned surface is:

  • its HTTP API as the browser and your scripts reach it, at /m/<kit>/api/…;
  • its manifest: the job kinds you can put on a schedule, the names of the entitlements, the sections it adds to the interface;
  • its metric names and labels. These are the part that leaves your installation — into Zabbix, into Prometheus, into a dashboard somebody built — and a renamed metric breaks a graph nobody told us about. They are part of the contract precisely because they are the least visible half of it;
  • the refusals it is documented to make. "This kit refuses to delete when the listing shrank by half" is behaviour people depend on.

For the platform, it is /api/…, /capi/v1/…, /export/v1/…, the names of the AG_* environment variables, and the service names in the compose file.

What is not promised

The interface's markup and ui.js; log lines; the shape of the database behind either — schemas change by migration and the migration is the contract, not the table (see Upgrading); anything a page calls experimental or in progress.

Where everything is today: 0.1.0

Every component is at 0.1.0: the platform and every kit in this release.

Under SemVer clause 4, major version zero means initial development — "anything MAY change at any time; the public API SHOULD NOT be considered stable". That is the truth about this project today, and a number saying otherwise would be the first thing in this documentation that is not true.

Two things it deliberately does not mean:

  • It is not a maturity rating. Some of these kits pass their full verification suite against live systems — real PostgreSQL targets, real registries, a real /24 — and one of them is in the middle of an internal migration. All of that is on each kit's page and in the repository's README.md, which is where to look for what works. The version number is a statement about compatibility, not about quality.
  • It does not weaken the upgrade guarantees. Migrations are checksummed and a service refuses to start against a history it cannot account for, today, at 0.1.0 — see Upgrading. SemVer's clause 4 permits a project to be more careful than it promises; this one is.

From here the numbers diverge by being earned: a component's version moves when that component changes, so a kit at 0.4.0 while another is at 0.1.0 will mean four releases of real change against one, rather than somebody's estimate of how finished it feels.

Releases come in pieces

A release is one tag on the repository and one git pull for you: the platform and its kits are deployed together from one compose file, so they are released together. What differs is which components changed in it — only those get a new number, and the release notes say which.

So "release 0.3.0" means the platform at 0.3.0, and inside it whichever kit versions that release carries. The interface shows both: the platform's on the Overview screen, each kit's in the kits list.

Becoming 1.0.0

Not a decision about how proud we are of something — an observation that two things have become true:

  1. the platform's kit contract, /capi/v1, is declared frozen; and
  2. that component's own public API, as defined above, has gone several releases without needing a breaking change.

Until the first of those, a kit at 1.0.0 would be promising something that is not in its power to keep, because it reaches the platform through a contract that may still move.

Two version numbers that are not the same thing

The platform's own version and the version of the contract a kit speaks to it are separate, and the contract's version is in the path: /capi/v1, /export/v1. That is what will eventually let a kit reach 1.0.0 while the platform is still below it: the kit's promise is about the kit's own surface, and the platform's promise to kits is v1 for as long as v1 exists. A v2 would live beside v1 rather than replace it.

Where to see them

  • the platform's: the Overview screen, "build <version>", and GET /healthz;
  • a kit's: the kits list in the interface, and the kit's own /manifest.