Versioning and compatibility

This page explains how Clustron Zaris and the wider Clustron package family are versioned, which .NET target frameworks each package builds for, and how to keep clients and clusters on compatible versions.

How Clustron packages are versioned

Clustron is not a single product but a family of independent NuGet packages — the Zaris store and its client, plus the reusable coordination primitive Nodus and the built-in security and metrics engines. Each repository versions on its own cadence and ships as its own set of NuGet packages, so a Zaris release and a primitive release do not have to share a version number.

Within a repository, all of that repository's packages share one version. Zaris consumes Nodus and the security and metrics engines only as NuGet dependencies, each pinned to a specific version, so a given Zaris release is built and tested against a known combination of the primitives.

What to expect for compatibility:

• The Zaris client and the Zaris cluster should run the same Zaris version, or versions from the same release line. See Client and cluster compatibility below.
• The primitive packages (Nodus, and the security and metrics engines) are pulled in transitively at the versions Zaris was built against. You normally do not reference them directly, so you inherit a tested combination.
• Several packages are still pre-1.0. Treat that as a signal to pin versions and read the release notes before upgrading — see Semantic versioning and pre-1.0 packages.

Target frameworks

The table below records the target framework declared in each project's .csproj. The Zaris client multi-targets netstandard2.0 and net8.0; because it produces a netstandard2.0 assembly, a thin client can run on any runtime that implements .NET Standard 2.0 — .NET Framework 4.6.1 and later, .NET Core, and .NET 5+. Everything that runs the store in-process or adapts it to ASP.NET Core targets net8.0 and therefore needs .NET 8 or later.

Package (PackageId)	Project	Target framework(s)	Runs on
Clustron.Zaris.Client	Clustron.Zaris.Client	netstandard2.0;net8.0	.NET Framework 4.6.1+, .NET Core, .NET 5+, .NET 8
Clustron.Zaris.DistributedCache	Clustron.Zaris.DistributedCache	net8.0	.NET 8+
Clustron.Zaris.HybridCache	Clustron.Zaris.HybridCache	net8.0	.NET 8+
(host / server)	Clustron.Zaris.Host	net8.0	.NET 8+

note

The client's netstandard2.0 target is what lets a legacy .NET Framework 4.6.1+ application talk to a Zaris cluster. The cluster itself, the in-process store, and the ASP.NET Core cache adapters require .NET 8 or later. This matches the guidance in the FAQ.

The exact declarations these rows are drawn from:

• Clustron.Zaris.Client.csproj — <TargetFrameworks>netstandard2.0;net8.0</TargetFrameworks>
• Clustron.Zaris.DistributedCache.csproj — <TargetFramework>net8.0</TargetFramework>
• Clustron.Zaris.HybridCache.csproj — <TargetFramework>net8.0</TargetFramework>
• Clustron.Zaris.Host.csproj — <TargetFramework>net8.0</TargetFramework>

Client and cluster compatibility

Keep the client library and the cluster on compatible versions. The safe rule is to run the same Zaris version on both, or at least versions from the same release line.

Guidance:

• Match the client to the cluster. Upgrade the client and the cluster together where you can. A client from a newer release line may expect protocol or feature behaviour the cluster does not yet provide, and vice versa.
• Do not run a mixed-version cluster longer than an upgrade window. During a rolling upgrade some nodes will briefly run the old version and some the new — that is expected and bounded. Finish the rollout; do not leave the cluster split across two versions as a steady state.
• Upgrade one version line at a time. Skipping multiple release lines in a single step is more likely to cross a breaking change. Step through them.

For the mechanics of a rolling upgrade, the order of operations, and how to drain and rejoin nodes safely, see Upgrades and operational lifecycle.

Family package versions

The versions below are the ones the repositories and product pages state today. Install the Zaris client and the cache adapters directly; Nodus and the security and metrics engines normally arrive transitively at the versions Zaris depends on.

Package family	Version	Where it is stated
Zaris SDK (Clustron.Zaris.*)	1.1.0	Install directly; see the Zaris overview / package page
Nodus (Clustron.Nodus.*)	1.1.0	Nodus overview; arrives transitively
Security layer (Keyvus)	1.1.0	Bundled with Zaris; arrives transitively
Metrics engine (Numerous)	0.9.0	Bundled with Zaris; arrives transitively — unchanged since 0.9.0

note

As of the 1.1.0 release the Zaris SDK, Nodus, and the security layer are all published at 1.1.0; the metrics engine is unchanged from 0.9.0 and stays there, so Zaris 1.1.0 depends on the metrics engine 0.9.0. Always take the authoritative number from the package page on nuget.org or the Zaris overview — a package is only bumped when it actually changes.

Release-specific compatibility — 1.1.0

• Recompile the client for 1.1.0. The client hot path (Get, Put, Delete, Expire, Persist, TTL, and the fluent chain) now returns ValueTask/ValueTask<T> instead of Task/Task<T> for allocation-free synchronous completion. Normal await usage is unchanged and source-compatible — but this is a binary-breaking change, so applications must recompile against 1.1.0 rather than binding to the 0.9.0 assembly. Code that treats the return value as a Task (e.g. Task.WhenAll(...), assigning to a Task<T> variable, .ContinueWith(...)) needs .AsTask(). Bulk, transaction, and scan APIs are unchanged (Task).
• The wire protocol is unchanged from 0.9.0. A rolling upgrade that briefly mixes 0.9.0 and 1.1.0 nodes is safe on the wire (keep the mixed-version window short — see Upgrades), and a 0.9.0 client can talk to a 1.1.0 cluster. To pick up the new client API, recompile against 1.1.0.
• Nodus and Keyvus 1.1.0 are a license-text correction only (no code change since 0.9.0); the metrics engine is unchanged at 0.9.0.

Semantic versioning and pre-1.0 packages

Clustron packages follow semantic versioning intent — MAJOR.MINOR.PATCH, where a major bump signals a breaking change, a minor bump adds functionality, and a patch is a fix. As of the 1.1.0 release the Zaris SDK, Nodus, and the security layer are at 1.x, so expect the usual contract for them: breaking API changes only in a major bump. The metrics engine is still pre-1.0 (0.9.0); treat its versioning intent as advisory.

Regardless of version, before any upgrade:

• Read the release notes and pin your versions. Pin the packages you reference directly so an upgrade is a deliberate, reviewed change, and read the notes for the version you are moving to.
• Watch for recompile-only (binary-breaking) changes. A change can be source-compatible yet require a rebuild — 1.1.0 is exactly this: the client hot path moved to ValueTask, so await usage is unchanged but you must recompile against 1.1.0 (see Release-specific compatibility — 1.1.0).
• Test the upgrade in a non-production environment first, especially for a pre-1.0 package where a minor bump may still carry API changes.

Changelog

Clustron does not publish a single combined changelog across the family. Release notes accompany each package release, per repository, and are the source of truth for what changed in a given version — new behaviour, breaking changes, and fixes. Read the notes for the specific version you are moving to before you upgrade, and pair them with the upgrade procedure.

Next steps

• Upgrades and operational lifecycle — how to roll a cluster forward safely within an upgrade window.
• Limits — the operational limits and boundaries to plan against.
• FAQ — quick answers, including which .NET versions are supported.