Different API breakages categories in RN?

Hi devs,

Could be nice to differentiate types of breakages in the RN into 4 categories:

  1. Real breakages that we accept. In this case we need to clearly explain why we decided to break it. In this category we should include accepted source breakages for ex.

  2. Breakages but they’re ok and part of the game: unstable api breakages which are not breakages.

  3. False positives, not actual breakages, either because of a bug in Revapi or because some API was moved elsewhere, or because it’s a script API change that doesn’t break scripting, etc.

  4. Behavior breakages. Not reported by revapi. These should be reported directly in the RN and they should also have a good explanation as to why we accept them. E.g. a method returns a String but we change the content format of the string

I don’t know if we want to do this now or not and how to automate this to the max.

I’m listing this topic since this could be an improvement.



As explained on https://forum.xwiki.org/t/dont-break-the-build-on-source-incompatibilities/7034 retro compatibility is about binary/runtime breakages and and source breakages are not reported anymore.

Indeed, I had forgotten that one :wink:

I guess for 1, 2 and 3 we can define in the revapi ignore setup some prefix in the reason or even better if possible a custom XWiki field in the ignore to indicate its “level” (or maybe just indicate it for 2 and 3 and see 1 as the default) so that this is reflected in the RN (the macro generating 2 separated sections and maybe hide the level 3 which has my preference to not bother the user with theoretically useless information).

+1 in general for having those categories.

Sounds good but I’d use 2 as the default since we usually break unstable APIs.

The reason why I was suggesting to put 1 as the default is because I feel it’s better to list a breakage as more important that it is than the opposite when we forget to set the level.

Would be better to find a way to make it mandatory and fail the build if it’s no there then, no?

I guess it would mean create a new enforcer rule which parse revapi configuration in the pom but sure we could do that to be safe.