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:

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 En\n and closes the connection (a node before 0.4.8 closes it without a reply; 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 given under Upgrading a cluster (discovery first, then the nodes, then the proxies); a release’s changelog notes any exception to it.

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.

Within an SDK or adapter, these are not covered, whatever a README says about them, and may change in any release:

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.

Server binaries and images

Besides the wire protocol and the SDKs, three more things that deployments are written against are covered from 1.0.0: the command line of the server binaries, the operations endpoints and metrics, and the container images. The same rule applies to each: a breaking change waits for a new major version, and adding something is a minor change.

Command-line flags and environment variables

From 1.0.0 the command line of nanocached-node, nanocached-proxy and nanocached-discovery is covered, because deployment guides, container manifests and task definitions are written against it:

Renaming or removing a flag, changing the syntax it accepts or what it means, and making an accepted value invalid are breaking changes and wait for a new major version; there is no deprecation period (see above). A minor release may add a flag or an environment variable.

Not covered, and free to change in any release:

Operations endpoints and metrics

From 1.0.0 the operations endpoint that --metrics-port turns on is covered, because probes, scrapers, dashboards and autoscaling rules are built on it:

Removing or renaming a metric, changing its type, changing what it counts, and adding a label key to an existing metric (which splits a series that alert rules may select) are breaking changes and wait for a new major version. A minor release may add a metric. The set of label values (the namespaces present) follows the data and is not a compatibility matter.

Not covered: the text of the response bodies, the HELP lines and the order of the lines in /metrics, and the unauthenticated nature of the endpoint (keep it on an internal interface, as the guide says).

Container images

The three images are ghcr.io/nanocached/nanocached-node, nanocached-proxy and nanocached-discovery. From 1.0.0 these are covered:

A new major version may change any of those, and says so in the changelog. Not covered, and free to change in any release: the base image (its distribution, libc and version) and anything the guides do not rely on in it, such as a shell or other tools; where the binary and other files sit in the image; the working directory; the image’s labels and size.

Two more kinds of tag exist and carry no promise at all: :main and :sha-<commit> are builds of unreleased commits, for trying a change. Floating tags such as :X or :X.Y do not exist; a minor release may add them, but nothing here depends on that.

Not covered

tests/ and tools/

Nothing under the repository’s tests/ and tools/ directories is covered, at any version: the E2E, chaos and oracle scripts, the conformance harness, the benchmarks and the copy of the capacity planner kept there. Their arguments, environment variables, output formats and file layout may change in any release, including a patch release. The scale-in scenarios that Verifying a deployment points to are examples of how the drain behaves, not an interface to script against.

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.