
The video plays from YouTube, which loads only when you press play.
First: do you need to break it?
Often you don't. A rename can keep the old name for a while: the old method stays, marked @Deprecated, and calls the new one. Users get a warning, move at their own pace, and you remove the old method in the next major release. On the JVM this works for most renames and for added parameters (in Kotlin, see what a default value really does).
Some changes have no compatible form. Java cannot overload a method on its return type alone, so changing int add(int, int) to long add(int, int) breaks every compiled caller whatever you do. And sometimes the deprecation period is over. Then the question is no longer whether users have to change their code, but how much work it is for them.
The example
A small library, com.example:demo-java, version 1.0.0 published. For the next release we rename two methods:
// Calculator
public void reset() → public void clear()
// Inventory<T>
public Map<String, List<T>> byCategory() → public Map<String, List<T>> groupByCategory()
Both are breaking changes: code compiled against 1.0.0 fails with NoSuchMethodError, and source that calls reset() stops compiling. So the next version is 2.0.0. Bumping the version tells users that something broke. It doesn't tell them what to do about it.
Part 1: a migration guide
The guide is a short list of what changed, grouped by class, written for the people who call your code. This is the draft Bumpwise produced for the example, copied unchanged from the IDE:
# Migrating com.example:demo-java from 1.0.0 to 2.0.0
_Draft generated by Bumpwise from the API changes. Review it and add the
reasons and examples your users need._
Code compiled against 1.0.0 must be recompiled against 2.0.0. Update the
code that uses the API below first.
## `com.example.demo.Calculator`
- `reset()` was renamed to `clear`. _Automated by the OpenRewrite recipe._
## `com.example.demo.Inventory`
- `byCategory()` was renamed to `groupByCategory`. _Automated by the OpenRewrite recipe._
A draft is a start, not the guide. Add why each change was made and a before/after example for anything that is not a plain rename. Users forgive a break much more easily when they understand it.
Part 2: a recipe that does the renames
OpenRewrite is an open source tool that changes source code with recipes. The large migrations in its catalog, to JUnit 5 or to a new Spring Boot, are built from small steps like these two:
type: specs.openrewrite.org/v1beta/recipe
name: com.example.demo_java.MigrateTo2_0_0
displayName: Migrate to demo-java 2.0.0
description: Renames from the 1.0.0 API to the 2.0.0 API.
recipeList:
- org.openrewrite.java.ChangeMethodName:
methodPattern: com.example.demo.Calculator reset()
newMethodName: clear
matchOverrides: true
- org.openrewrite.java.ChangeMethodName:
methodPattern: com.example.demo.Inventory byCategory()
newMethodName: groupByCategory
matchOverrides: true
That is the whole file. Renamed or moved classes use org.openrewrite.java.ChangeType in the same way. You can publish it next to the release notes as rewrite.yml.
What your users run
We wrote a small app that uses demo-java 1.0.0, put the recipe at its root and ran the OpenRewrite Maven plugin (6.46.1):
mvn org.openrewrite.maven:rewrite-maven-plugin:run \
-Drewrite.activeRecipes=com.example.demo_java.MigrateTo2_0_0
The result, from git diff:
--- a/src/main/java/com/acme/shop/Checkout.java
+++ b/src/main/java/com/acme/shop/Checkout.java
public void start() {
- calculator.reset();
- System.out.println(basket.byCategory());
+ calculator.clear();
+ System.out.println(basket.groupByCategory());
}
OpenRewrite resolves types before it changes anything. It renamed calls on a Calculator and an Inventory, and would leave a reset() on any other class alone, which a search and replace cannot promise. Then the user updates the dependency to 2.0.0 and builds. Gradle users run the same recipe with the OpenRewrite Gradle plugin.
What to automate, and what not
- Renames are the sweet spot. Same class, same parameters, new name: the mapping is certain and the recipe is a few lines.
- Only automate what is unambiguous. If two methods with the same parameters disappeared and two appeared, a tool cannot know which became which. Ask a person, and write it in the guide instead.
- Everything else goes in the guide: removed methods, changed types, new checked exceptions. Say what to use instead.
- Test the recipe on a project that uses your library before you publish it, as we did above.
Where Bumpwise fits
Bumpwise, our IntelliJ plugin, compares your code with the last published release while you edit, and flags changes that break it. Since version 1.0.5, the results of Tools | Check API Compatibility have two more buttons: Copy migration guide and Save OpenRewrite recipe. They produced the guide and the recipe in this article. Only unambiguous renames go into the recipe, and the rest is listed in the guide and in the recipe's comments for you to describe. Both buttons are part of Bumpwise Team.
Disclosure: Gilware makes Bumpwise, a paid plugin with a free edition for Java libraries published on Maven Central. You don't need it to follow this article: the guide is Markdown and the recipe is a YAML file you can write by hand.
How we checked
The library is the Java sample from the Bumpwise repository, published as 1.0.0 in a local Maven repository. The guide and the recipe were produced by Bumpwise 1.0.6 in IntelliJ IDEA 2026.3 and copied unchanged. The app (com.acme:shop, one class that calls both methods) was migrated with rewrite-maven-plugin 6.46.1 on 17 November 2026. The diff above is from that run.
Found a mistake? Write to hello@gilware.com.