I know that an API is not supposed to be broken, but.... in real life this happens.
In the context of the API tooling effort, we need to handle this case when checking for binary compatibility between two Eclipse drops.
An example would be that an API provider defines an interface that can be implemented by clients with a method that takes an internal type as a parameter. This API is not usable for the clients. The provider then changes the signature of the method to use an interface type instead of the internal type. Now the API is usable, but this change technically speaking a breaking API change.
This kind of changes should be documented in the porting guide, but I believe it should also be document at the source code level.
One way to do this would be to have a javadoc tag on the corresponding API that would state this is a known breakage. Something like:
@breakage-change The parameter type has been changed to use an API type instead of an internal type
The binary compatibility checker could then realize that this is a known breakage and don't report it anymore.
The next question is: "Since this is an API breakage, should the version of the corresponding bundle change its major version?".
I'd like to get your opinions on this topic.