Compatibility

What stays stable once nanocached reaches 1.0.0, and what does not. The project is still on 0.x, so this page describes the rules that take effect at 1.0.0; until then only the pre-1.0 rule applies.

Versioning

The server (nanocached-node, nanocached-proxy, nanocached-discovery), the six SDKs and the framework adapters are released together and carry the same version number, whether or not a given component changed. Versions follow semantic versioning: a breaking change to anything on this page raises the major version, new backward-compatible features raise the minor version, fixes raise the patch version.

Client wire protocol: frozen

From 1.0.0 the client-facing wire protocol is frozen. Covered:

• every command a caching client sends — A, G/S/D, g/s/d, c/F, i, k/x, m/o — together with the two membership queries SDKs send, L and Q;
• every response and status those commands can produce, and the response tags capability.

Frozen means no 1.x release changes the syntax or the meaning of anything above, and none removes it. A 1.x release may add a new command, a new optional trailing token or a new status; an older node that does not know the addition answers E\n and closes the connection (see namespaces), so a client must not use a newer feature before every node has been upgraded. Any other change to this protocol waits for a new major version.

Not frozen: cluster-internal frames

The frames that only nodes, discovery servers and proxies exchange with each other — join, heartbeat, announce, migrate, cancel, complete, proxy announce, handoff and leave, node roster (see cluster-internal commands) — are versioned with the server and may change in any release, including a patch release. Run one server version across a cluster; a mixed-version cluster is only a transient rolling-upgrade state, in the order the changelog gives.

SDK public API: all six SDKs

From 1.0.0 the public API of each of the Rust, Go, TypeScript, Python, Java and .NET SDKs is covered: the exported types, functions, methods, options and their documented behavior, and the error types and the conditions that raise them. A breaking change to any of them is released only as a new major version. Behavior that an SDK's documentation describes as a limit or as unspecified is not covered.

The framework adapters (Spring, Spring Boot starter, JCache, Django, cache-manager, Keyv, and Nanocached.Caching for .NET) ship at the same version and follow the same rule for their public API and configuration keys.

No deprecation period

nanocached does not deprecate before it removes. There is no release that keeps an old form working alongside its replacement with a warning. A breaking change lands in a major release, takes effect there, and is recorded in the changelog of every affected component. Pin the major version you depend on; upgrading to the next major is the point at which you read the changelog.

Not covered by this page

These have no compatibility promise yet; a decision for each is still open:

• command-line flags and environment variables of the server binaries;
• metric names and the operations endpoints (/healthz, /readyz, /metrics);
• the container image layout and tags other than the version tag;
• anything under the tests/ and tools/ directories.

Before 1.0.0

On the 0.x line none of the above is promised. A breaking change may ship in any release, minor or patch, without a deprecation cycle; the Rust SDK's changelog lists the ones so far. Pin an exact version.