Versioning
Semver
Section titled “Semver”z4j follows Semantic Versioning 2.0.0 for all released packages and the brain image. The wire protocol is versioned separately as a single integer (PROTOCOL_VERSION), bumped only for a breaking change to the framing; additive frame types do not bump it.
| Release type | Brain | Agent | Wire protocol |
|---|---|---|---|
| Major | Breaking API/UI changes | Breaking config or interface changes | A new wire-protocol version |
| Minor | New features, backward-compat | New adapters, new capabilities | Additive frame types |
| Patch | Bug fixes, security patches | Bug fixes | None |
Version sync
Section titled “Version sync”Brain and agents ship as one release wave at one version, and they negotiate a separate wire-protocol version at the handshake:
- This build of the brain accepts exactly one wire-protocol version.
- An agent that advertises a different one is closed with
4426. - Package-version skew inside the accepted protocol stays connected: an older agent gets a version badge and misses newer brain-side features, not a disconnect.
Wire-protocol upgrades
Section titled “Wire-protocol upgrades”When the wire protocol changes, upgrade the brain and its agents together. This build accepts exactly one wire-protocol version (SUPPORTED_PROTOCOLS in z4j_core.transport.versioning lists one entry), so a protocol bump is a coordinated rollout, not a soak period, and it is announced with its own rollout rule.
Release cadence
Section titled “Release cadence”No fixed cadence. Minor releases ship when ready. Patch releases ship when needed (especially for security).
Pre-release tags
Section titled “Pre-release tags”-alpha- internal, may break.-beta- feature-complete, API may shift.-rc- release candidate, API stable, testing in progress.- No tag - GA, production-ready.
Pinning agents
Section titled “Pinning agents”Pin the whole set, not one package. Each z4j package floors its z4j
dependencies at the minor line's baseline (>=X.Y.0,<2), so pinning one
adapter behind the others produces a resolution that was never tested together.
A minor release moves all nineteen packages at once; a patch release re-cuts
only the packages whose shipped code changed (always including the umbrella
z4j), leaves every other package at its last version on the same minor line,
and keeps every floor at the minor baseline, so an operator who upgrades the
patched packages alone keeps an installable pairing. Pin the wave you deploy,
or let the floors resolve it, and move the z4j packages together.
Deprecation
Section titled “Deprecation”Deprecated features are logged with a DeprecationWarning for at least one minor release before removal. We don't remove features in patch releases.