Versioning & compatibility

A replica is written in a storage format versioned independently of the application, so upgrading the binary keeps reading and writing your existing replica. A replica written by one version restores with later versions, and on the rare occasion a binary can't read a replica, it reports the format mismatch and names the version to upgrade to, rather than reading the replica with the wrong format.

That guarantee comes from versioning three things separately. You can see all three at once:

$ bakelite version
bakelite 0.1.0 (2026-05-29)
  storage format: v1 (read & write)
  target:         x86_64-unknown-linux-musl
  libc:           musl (static)

The application version

Standard semver. Before 1.0, a minor bump (0.1 → 0.2) may change behavior or config; a patch bump (0.1.0 → 0.1.1) is fixes only. The changelog calls out anything you need to do when upgrading.

The storage format

The format your backups are written in has its own version, separate from the application version — so upgrading bakelite doesn't churn your replica. bakelite always writes the current storage format, and because that version is decoupled from the application, an application upgrade keeps reading and writing your existing replica unchanged. When the format itself must change incompatibly, the version bumps and an older binary refuses the newer replica (below) rather than misreading it.

If you ever point an older bakelite at a replica written by a newer one, the restore stops with a clear message instead of guessing:

manifest uses storage format v3 (written by bakelite 2.0.0); this bakelite
reads v2. Upgrade bakelite to read this replica.

The fix is always the one it names: upgrade bakelite. bakelite doctor reports the same thing up front, so you can catch it in a pre-flight check rather than at restore time.

The build (libc)

bakelite ships two flavors of Linux binary:

• Static (musl) — the default from the one-line installer and the :latest container image. No system library dependencies; runs on any Linux.
• Distro-native (glibc) — for environments that prefer dynamically linked, system-integrated packages. Built against a minimum glibc so they run on that release and newer; bakelite version shows the floor.

If you're not sure which you want, the static build is the safe choice — it runs everywhere. Every published build is install-tested across the supported distros before release.