How Axon Framework handles breaking changes through OpenRewrite

Tim te Beek
March 3, 2023
Axon Framework

Key Takeaways

As a framework maintainer you’re sometimes pulled in opposite directions by your users. On the one hand, you’ll have users requesting support for the latest and greatest versions of frameworks and languages. On the other hand, some users for whatever reason can’t yet migrate to those same latest versions. Too many users are woefully behind on upgrading, placing the Axon Framework upgrade among others in an ever-growing pile of technical debt. 

This can be a real problem. Maintainers I’ve worked with want to support as few versions as possible, as each additional version range increases the effort for each new fix or feature. They want users to upgrade regularly, using the latest software and features (and reducing the support load). By minimizing breaking changes, users are more likely to upgrade to the latest version. Yet sometimes breaking changes are inevitable.

Axon Framework recently had to introduce breaking changes to support the migration from Javax to Jakarta. As is often the case with our highly dependent software ecosystems today, this change did not originate with the Axon Framework, but their users were affected nonetheless. And while they did everything they could to document the required changes, there’s always the risk that users will put off a migration and start to fall behind.

To aid their users in the migration to versions 4.7+, Axon decided to do more than document the changes. This time, they wanted to provide automation that updates the code for their users. To that end, Axon Framework adopted OpenRewrite migration recipes. These migration recipes build upon the existing OpenRewrite Jakarta migration recipes, and include additional recipes specific to the Axon Framework 4.7 migration. This way, their users can easily migrate to newer versions. Employing these recipes will prove especially useful in the lead up to Axon Framework 5, which will feature more breaking changes.

Many open source maintainers are turning toward OpenRewrite to provide an easier path for their users to upgrade. OpenRewrite is an open source project and ecosystem that enables the automation of code remediation and refactoring—accurately making changes to source code. When it comes to OSS that offers automated upgrades versus OSS that only provides instructions (leaving the work to the end users), the automation will always win. Your upgrade recipes become part of the code you deliver with a new release.  

If you’re a framework maintainer or contributor, it’s likely that you are facing similar migration challenges like the Axon Framework team. If you’re tired of negotiating how many back versions you support and dealing with frustrated users who have to experience time-consuming upgrades, you should consider automation with OpenRewrite. As an example, look towards the recently added Axon Framework migration module

This includes a full migration, using both existing migration recipes, as well as framework-specific declarative migration recipes. Tests are provided to guarantee correctness, and instructions for end users are both in the repository and also on the AxonIQ Developer blog.

Using this approach, both Axon Framework developers and their users can focus their efforts mostly on the latest versions, with an easy path to get onto those latest versions.