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 (2.0.0) | Breaking API/UI changes | Breaking config or interface changes | Major protocol version (v2) |
Minor (1.1.0) | New features, backward-compat | New adapters, new capabilities | Additive frame types |
Patch (1.0.1) | Bug fixes, security patches | Bug fixes | None |
Version sync
Section titled “Version sync”Brain and agents are independently versioned but share a wire protocol version:
- v1.0.x brain talks to v1.0.x agents.
- v1.1.x brain talks to v1.0.x and v1.1.x agents (new features only available if both sides support them).
- v2.0.0 brain does not talk to v1.x agents (protocol v2 vs v1).
Upgrade grace window
Section titled “Upgrade grace window”On a major release, we maintain the previous wire-protocol version for 6 months alongside the new one. This gives you time to upgrade agents.
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 to exact minor in production:
z4j-celery==1.0.*This gets patch fixes but not minor bumps that might add behavior.
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.