5.27.0 not binary compatible with 5.26.0

[philsttr]

Describe the bug

Changes to ConnectionFactory made in 5.27.0 are not binary compatible with 5.26.0. They are source-compatible, however.

For example, the useNio() method in 5.26.0 was:

    public void useNio() {

But in 5.27.0, it changed to:

  public ConnectionFactory useNio() {

Changing the return type of a method is not binary compatible.

When a user uses 5.27.0 is at runtime, with code that was compiled against 5.26.0, the following error will occur:

java.lang.NoSuchMethodError: 'void com.rabbitmq.client.ConnectionFactory.useNio()'

A more concrete example is when an app upgrades from Spring Boot 3.5.8 to 4.0.0, the version of amqp-client is bumped from 5.25.0 to 5.27.0. If that application also uses a library calling useNio() that was compiled against 5.0.0 -> 5.26.0, then the runtime error will occur.

Reproduction steps

1. Compile code calling useNio() with 5.26.0
2. Run code with 5.27.0
3. Observe error

Expected behavior

Expect no error to occur.

Expect minor versions of the rabbitmq-java-client to remain binary compatible

Additional context

Ideally, revert the method signature, to keep binary compatibility with 5.0 -> 5.26

Otherwise, call out the breaking change in the release notes for 5.27.0

[michaelklishin]

If we cannot introduce such minor API changes in a minor release, when can we introduce them?
We cannot bump the major for every change, that's ridiculous and will have equally ridiculous contractual support consequences because every major has to be maintained for a certain period of time.

This library focuses on compatibility where it really matters: it supports RabbitMQ server versions going to back to 2010.

[michaelklishin]

The 5.27.0 change log now mentions the incompatibility.

[philsttr]

Thanks for updating the changelog.

As an open source maintainer myself, I try to limit binary incompatibilities to major releases. It's definitely not possible in every situation, but I try to avoid them when possible.

In this particular instance, changing the return type of useNio() is not really required, especially since it is now deprecated (and could potentially be removed in the next major release), so I thought it could be easily changed back to void to keep binary compatibility, and make upgrades easier for users. It seemed like the intent was to keep compatibility, since it was marked as deprecated.

Totally your call though. I appreciate your work on this project.

[acogoluegnes]

I think this is a change from main that leaked into 5.x by mistake. I'll push a fix and cut a patch release.

[acogoluegnes]

@philsttr I released 5.28.0 with the fix.

[philsttr]

Great! Thank you!