Versions and support

Myrtille has one version number for everything it publishes: the town hall image, the agent image, the command line and every package @myrtillehq/* move together, following Semantic Versioning. 1.4.2 is major 1, minor 4, patch 2.

Channels

• latest: the published versions (ghcr.io/myrtillehq/engine:latest, npm install -g @myrtillehq/cli). Patch and minor versions are published by the release pipeline of the project once its checks pass; a major version is decided by the maintainers.
• next: every change merged into the main branch of the project (:next images, @myrtillehq/cli@next). It is how the project tests itself before a release; do not run your town on it. Versions 0.x exist on next only: 1.0.0 is the first published version.

Which versions work together

Town hall	Agents it accepts (local and Docker)	Tested on every change of the project
1.4.x	1.4.x and 1.3.x	yes
1.4.x	1.2.x and older, or 1.5.x and newer	no: update them
2.0.x	2.0.x and the last 1.x minor version	yes

• The town hall accepts the agents of its own minor version and of the one before. You can update the town hall first and the workstations and servers in the days that follow, without a citizen going grey.
• Update the town hall first. An agent newer than its town hall is not promised to work: a newer agent may report something the town hall does not know yet.
• An agent says which version it is when it connects, and the agent protocol carries a version number of its own. When that protocol changes, the town hall keeps accepting the previous one for at least one minor version.
• The test suite of the project replays, against every new town hall, what the real agents of the previous minor version said to theirs, frame by frame (packages/engine/src/agents/agent-protocol.test.ts): their hello, their batches of events, their heartbeats. It also checks that every message the new town hall sends them is one their own strict reading accepts. A change that breaks an agent of the previous minor version does not reach latest.
• The browser always gets the town of its town hall: they are one image.

Which version receives fixes

• The latest minor version receives the fixes, security fixes included. There is no long-term support branch: a minor version is supported until the next one is published, and the way to get a fix is to update to the latest patch of the latest minor version. A minor version never breaks what worked, so this update is meant to be routine.
• A security fix is published as a patch version at once. A town hall with the version check turned on (see Telemetry) puts a high item in the mail the day it learns of it: “Myrtille x.y.z fixes a security problem: update this town hall”. Without the version check, follow the releases of the project on GitHub.
• When a major version is published, the previous major version receives no more fixes. Its last minor version is the one to update from: see Major updates.

What a version may change

• Patch (1.4.1 to 1.4.2): fixes only.
• Minor (1.4 to 1.5): new features and new optional keys. Everything that worked keeps working: the town plan, the API, the webhooks, the event schema, the agents of the previous minor version, and every database it can migrate.
• Major (1.x to 2.0): may remove what was announced as deprecated, change the town plan or the API, and stop accepting the agents of the older major version but its last minor.

How a deprecation is announced

• A feature, a key of the town plan, a route of the API or an event is deprecated in a minor version, never removed in it. The release notes of that version say what is deprecated, why, and what replaces it; the page of the documentation that describes it says it too.
• It keeps working for the rest of that major version. It is removed only by a major version, at least one minor version after its deprecation was announced, and the major update guide lists every removal with what to do.
• The versioned formats (the town plan version: 1, the event schema myrtilleschema, the agent protocol) change their number only for a change that breaks a reader. The town hall converts the events of an earlier schema version, and keeps accepting the previous agent protocol for at least one minor version.

The release notes of each version are generated from the change notes of the project and published with the version on GitHub, and in the CHANGELOG.md of each package.