Plan a Cratis Chronicle upgrade
Before upgrading Cratis Chronicle, find out whether the change affects application code, stored data, or communication between the server and its clients. A version bump and rebuild may be enough for one boundary; another may require a stored-state migration. When crossing several majors, you need the instructions for every boundary between your current and target versions.
Choose those versions below. This planner reads Chronicle’s major-version guide; links for the other Cratis products follow it.
Showing every boundary from 6 to 20.
Stored observer state
migrate that stored state before starting 7.x, or accept that inbox observers restart from their default position.
Namespaces, transport and several APIs
expect compile errors across the codebase and work through them; update `cratis.json` / `cluster.json`, where single-cluster mode changed from `local` to `single`.
Repository split and startup
Startup and configuration only; wire-compatible both directions
No recorded change
No release notes exist for this major
Stored job state
expect in-flight job state from 10.x to be unreliable. Drain jobs before upgrading if their completion matters.
Internalized APIs and a renamed package
rename the package reference; stop using anything from `Cratis.Chronicle.Contracts` or `Cratis.Chronicle.Infrastructure` that you were reaching into.
One method became async
`await` it. Opt out with `AutoDiscoverAndRegister = false` on `ChronicleOptions` or the `skipDiscovery` argument if you were managing discovery yourself.
Read-model formalization and stored layout
this one touches stored layout as well as APIs. Read the release notes in full, and go to **14.0.1**, not 14.0.0.
Rules retired, TLS, content type
replace Rules usage; fix code that treated `Content` as `ExpandoObject`; configure TLS for production; rename the testing package reference.
One port, always TLS
remove management-port configuration, point tooling and bookmarks at the single TLS port, and configure a certificate for production.
The generated wire contract
take a matching client. Go to **17.0.1** — 17.0.0 is the accidental release described above and carries a pre-migration contract.
Append content back to a string
nothing, if you use a published client at a matching version. A client built directly against the raw gRPC contracts must send and receive `Content` as a string.
A .NET signature
rebuild.
Cratis Choreography
stop every kernel silo of the cluster and start them on 20 together, rather than rolling pods one at a time across this boundary.
How to read this
Section titled “How to read this”A compile-time boundary changes an API your code uses. Fix the accumulated compile errors against the version you plan to run, rather than rebuilding your application at each intermediate version.
A stored-state boundary concerns data already written. Follow these instructions in order: skipping an intermediate release does not skip its data changes. Before crossing one, take a backup, verify you can restore it, and rehearse the upgrade against a copy.
A wire boundary changes the protocol between the Chronicle kernel (the server) and its clients. The kernel and .NET client must move together across these boundaries. For example, a 16-to-18 upgrade crosses wire changes at both 16-to-17 and 17-to-18; read both entries before choosing a client version.
Chronicle verifies compatibility across released minors within one major; crossing a major permits a protocol change. The TypeScript, Kotlin/Java, and Elixir clients have their own version numbers and check wire compatibility with the kernel when they connect. Check the pairings in Version compatibility, not just matching version numbers.
Each entry links to the full account in Chronicle’s own upgrade guide, which is where this list comes from. Read that entry before changing a deployment; the planner summarizes it rather than replacing the instructions.
Other products
Section titled “Other products”The other products do not publish a major-version guide in this format yet. Use their own migration pages and release notes:
- Components: Migration guides, including 2 to 3 and 3 to 4.
- Arc, the CLI, the clients, and the tools: the release notes linked from What’s new.