Versioning
Semver
Section titled “Semver”z4j follows Semantic Versioning 2.0.0 for all released artifacts (brain image, agent packages, wire protocol).
| 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:
- The brain speaks and accepts exactly one wire-protocol version at a time.
- 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. There is no dual-protocol window: the brain accepts one wire-protocol version, so a protocol bump is a coordinated rollout, not a soak period.
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 its own wave, so pinning one adapter behind the others produces a resolution that was never tested together. Pin the wave you deploy, or let the floors resolve it, and move every z4j package at once.
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.