Compatibility & Versioning

One version for every component

Axelix is released as a single, coordinated distribution. All components share exactly the same version.

When a new distribution of Axelix is released — say Axelix OSS 3.1.2 — every released component carries that same version 3.1.2:

• The Spring Boot Starters (published as Maven artifacts).
• The plugins (also published as Maven artifacts).
• The Axelix Master standalone JAR.
• The Axelix Master Docker image.

There is no independent versioning per component. If you know the version of one Axelix artifact, you know the version of them all in that release.

This holds for patch releases too: a patch re-releases the whole fleet under X.Y.Z, cut from the minor line's patch branch — see Branching Model and Releases for how those cuts happen.

A dedicated starter per Spring Boot major version

Axelix ships a dedicated starter for every Spring Boot major version. There is a standalone, separate artifact for each supported major:

• axelix-spring-boot-2-starter — for Spring Boot 2.x services.
• axelix-spring-boot-3-starter — for Spring Boot 3.x services.
• axelix-spring-boot-4-starter — for Spring Boot 4.x services.

As of now, Axelix supports Spring Boot major versions 2 through 4. Pick the starter that matches your service's Spring Boot major version.

Plugins are different: they are designed to be broadly compatible, so there is no per-version plugin artifact to choose from:

• The Gradle plugin is tested to work on Gradle major versions 5 through 9.
• The Maven plugin is compatible with Maven 3, which is what virtually every Maven project uses today.

Java version compatibility

Axelix Master is itself a Spring Boot application, written on Java 25. This will be the concern only in case you'd want to run Axelix Master as a JAR. In any other case it will not make a difference.

Starters follow the Java compatibility of the Spring Boot version they target. Each starter is compatible with any Java version that its Spring Boot major supports. For example, Spring Boot 3 supports Java 17 at the very least and up to Java 25 (with Spring Boot 3.5), depending on the minor version you run — and axelix-spring-boot-3-starter follows exactly the same range.

Compatibility between components

Axelix is released in lockstep, but nothing forces you to upgrade in lockstep: in a real fleet you may bump Master to the latest patch before the services catch up, or upgrade a single service's starter while everything else stays put. For those mixed deployments there is a single rule, and it applies to every Axelix component:

Any two Axelix components are guaranteed compatible as long as they share the same major and minor version. The patch version is irrelevant.

That is the whole contract. It covers every pairing at once — Master with a starter, a starter with its plugin, all of them together — so you never need a compatibility matrix. Just line up major.minor.

• ✅ Master 1.4.2, starter 1.4.5, plugin 1.4.0 — all on 1.4, guaranteed compatible.
• ✅ Starter 1.4.3 with plugin 1.4.0 — same 1.4, guaranteed compatible.
• ⚠️ Master 1.4.2 with starter 1.3.4 — minor drift, not guaranteed. It may work; it may break.
• ⚠️ Starter 3.1.x with plugin 3.3.x — minor drift, not guaranteed and unsupported.
• ⚠️ Any major drift — not guaranteed, and even less likely to work than a minor drift.

If components diverge on the minor or major version we guarantee nothing — the combination may still work, but it may break, and it is not tested. The simplest policy, and the one lockstep releasing makes trivial, is to keep everything on the exact same X.Y.Z — but only major.minor is the actual contract.

Why patch drift is safe but minor/major drift is not

The assumption behind this policy is that all functionality the components expose is meant to be reached through the Axelix Master web UI. There is no scenario in which you would bump a single component's minor version on its own to unlock some capability — that capability surfaces through Master, not through the component in isolation. Because of that, we let ourselves revisit the contracts between components in minor releases, which keeps the project moving fast.

Patch releases are different. As stated by semver, a patch release may carry a critical CVE fix, a bug fix, or a performance improvement — and those changes are valuable on their own. A patch release re-publishes the whole fleet under the new version, but the actual fix usually touches only some of the components — so upgrading just the affected component and leaving the rest on an older patch is a combination you will genuinely run, and we guarantee it stays compatible.

Backward compatibility guarantees between releases

Axelix Master

Axelix Master is a Java application meant to be run as a standalone process — in Kubernetes, in Docker, or as a plain JAR. It is not meant to be consumed as a library. Because of that, we do not treat the Java public surface as a public contract: public classes, public methods, constructors, fields, enums, and constants are all considered internal.

In practice this means we may change that public Java API in minor or even patch releases. The assumption is that nobody depends on Master as a library, so mutating its Java API freely lets us move development faster. It is a deliberate trade-off that realistically affects almost no one — a big win for the pace of the project.

What we do treat as Master's public contract is its configuration:

• The names of properties — both for the Axelix Master Helm chart and for Axelix Master run as a standalone JAR.
• Their default values.
• Their types.

These will change only in major releases.

Starters

Starters are consumed as libraries — they are Spring Boot starters, so they bring auto-configurations with beans into your application (bootstrap wiring, the internal proxying strategy, and so on). That reality shapes two rules.

Do not override Axelix beans. We intentionally do not allow end users to override the internal beans Axelix declares in order to tinker with the bootstrap process, the proxying strategy, or similar internals. This is a deliberate choice. Axelix works hard to add no measurable overhead to your app and to be as efficient and bug-free as possible; letting you override beans like BeanPostProcessors or ProxyFactoryBean instances would open a backdoor to subtle bugs and worse performance. So please do not try to swap out Axelix's beans.

Do not depend on a starter's public Java API. We have to acknowledge that starters run inside real applications, so their public Java API can technically be reached from your code — but this is not intended, and we strongly discourage it. To move fast and stay competitive, we may change the public Java API of the starters too. We will avoid it at all costs, but if we deem it necessary we may change it in a minor version bump.