Skip to content
resilience4cata
ENES

Compatibility

What an upgrade within one major version keeps working, from 1.0.0 on, and what may grow in a minor version.

resilience4cata follows Semantic Versioning. Until 1.0.0 a minor version may change the API, and the changelog lists every incompatible change. From 1.0.0, minor and patch versions of the same major keep everything on this page compatible; only a new major version can break it.

The Java API

The API is every public and protected member of the packages that a published module exports (dev.resilience4cata, dev.resilience4cata.event, dev.resilience4cata.config, dev.resilience4cata.testkit and so on; for Spring Boot, dev.resilience4cata.spring). Within a major version it stays binary and source compatible. The build checks this on every change: it compares each module with the last release and, from 1.0.0, fails on an incompatible change.

Not part of the API:

  • Members marked @Internal: they are public only so that another resilience4cata module, or the ServiceLoader, can reach them.
  • Members marked @Experimental: they may change in any minor version until they are settled. Nothing is marked @Experimental today.
  • Packages a module does not export, such as dev.resilience4cata.internal and Spring Boot's dev.resilience4cata.spring.autoconfigure. For the auto-configuration, what is kept is the class names (for exclude), the bean names and the resilience4cata.spring.* property names.
  • dev.resilience4cata.generated and dev.resilience4cata.reactor.generated: they are exported for generated code only. Do not call them from your own code.

Generated code

Code generated by processor 1.a runs on core (and reactor) 1.b for every b >= a. A library compiled with resilience4cata therefore keeps working when the application that uses it upgrades resilience4cata within the same major version. The other direction is not supported: on an older runtime the generated constructor fails at once with R4C-RT-021. Importing the BOM keeps the versions aligned. The generated source text itself is not part of the contract and may change in any version.

Beyond Java

These are kept within a major version as well:

  • The annotations and their attributes, and the configuration keys with their environment-variable forms.
  • The integrations' property names: resilience4cata.spring.*, resilience4cata.micronaut.* and quarkus.resilience4cata.*.
  • Metric names and tags, the same in the Micrometer and OpenTelemetry modules (Metric names). Names stay dotted, every meter keeps its name tag, and the circuit breaker's rates stay percentages.
  • The JSON of the Spring Boot and Micronaut endpoints, which is ResilienceSnapshot.toMap() (Snapshots).
  • Error codes such as R4C-ATR-001. A code is never renumbered or reused, and a retired code keeps its section in the error reference. The text of a message may improve in any version, so match on the code, not on the text.

What may grow in a minor version

Adding is compatible, so a minor version may do any of the following. Write code that tolerates it:

  • Enum constants may be added (CircuitBreakerState, RetryEvent.Reason, Classifier.Outcome and others). Keep a default branch in a switch over them.
  • Event types may be added, and existing event records may get new components. Keep a default branch in a switch over events, and read events through their accessors, not with record patterns that deconstruct them.
  • Methods may be added to the handles (CircuitBreakerHandle and the others) and to FallbackContext. The library implements these interfaces; do not implement or mock them.
  • Ticker methods added later will be default methods, so your own implementation keeps compiling.
  • Annotation attributes may be added, always with a default value.
  • Snapshots may get new components and the endpoints' JSON new keys. Ignore keys you do not know.
  • Metrics, error codes and configuration keys may be added.