activemq-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Christian Schneider <ch...@die-schneider.net>
Subject Re: [DISCUSS] Making automated API compatibility check a part of the Artemis build
Date Thu, 23 Feb 2017 10:24:38 GMT
What we can use to check the compatibility is the bnd baselining. It is 
quite easy to add when a project already uses the maven-bundle-plugin.

This is how to add it:
https://github.com/apache/aries-rsa/blob/master/parent/pom.xml#L243-L245

Every API package gets a version number. Then you give the plugin a 
reference version of the jar and it checks if the changes in the API 
require a bump of the package version.

This is an example output:
[INFO] Comparing bundle org.apache.aries.rsa.spi version 1.11.0-SNAPSHOT 
to version 1.9.0
[INFO]
[INFO]   PACKAGE_NAME DELTA      CUR_VER    BASE_VER   REC_VER    WARNINGS
[INFO] = ================================================== ========== 
========== ========== ========== ==========
[INFO]   org.apache.aries.rsa.spi unchanged  1.0.0      1.0.0      
1.0.0      -
[INFO] 
-----------------------------------------------------------------------------------------------------------
[INFO]   org.apache.aries.rsa.util unchanged  1.9.0      1.9.0      
1.9.0      -
[INFO] 
-----------------------------------------------------------------------------------------------------------

and this is how it looks like if I do an incompatible change in an 
interface:
[INFO]   PACKAGE_NAME DELTA      CUR_VER    BASE_VER   REC_VER    WARNINGS
[INFO] = ================================================== ========== 
========== ========== ========== ==========
[INFO] * org.apache.aries.rsa.spi major      1.0.0      1.0.0      
2.0.0      Version increase required
[INFO]      > interface org.apache.aries.rsa.spi.DistributionProvider
[INFO]          - method 
exportService(Ljava/lang/Object;Lorg/osgi/framework/BundleContext;Ljava/util/Map<Ljava/lang/String;Ljava/lang/Object;>;[Ljava/lang/Class;)
[INFO]              - access abstract
[INFO]              - return org.apache.aries.rsa.spi.Endpoint
[INFO]          + method 
exportService(Ljava/lang/Object;Lorg/osgi/framework/BundleContext;Ljava/util/Map<Ljava/lang/String;Ljava/lang/Object;>;[Ljava/lang/Class;Ljava/lang/String;)
[INFO]              + access abstract
[INFO]              + return org.apache.aries.rsa.spi.Endpoint

This is very useful for OSGi but also helps a lot on plain java.
The only thing to keep in mind here is to also reflect changes in the 
package version in that jar version as outside OSGi the jar version is 
how we express compatibility.

Christian

On 23.02.2017 10:34, Jiri Danek wrote:
> Hello,
>
> I would like to propose running some API compatibility checking tool as
> part of the Artemis build process. This would guarantee that no user-facing
> API method is deleted or inadvertently modified in such a way that it is no
> longer compatible with code that Artemis users wrote and compiled before.
>
> Having such a check is considered a good practice [1], especially in the
> C/C++ world, but it can be useful in Java too.
>
> Since it would mean additional effort on part of developers, I'd like to
> discuss if you think this is worthwhile. It would require 1) defining ABI
> compatibility policy (e.g. major versions may break ABI, minor may not), 2)
> picking a checker, 3) configuring it (define a whitelist or blacklist of
> classes to specify what constitutes user facing API covered by the
> compatibility policy), and 4) making it part of the build (enforce the ABI
> check in some circumstances, fail the build if check fails).
>
> I'll try to address some of the above mentioned points in turn:
>
> ad 1) The policy Artemis seems to adhere to is that major release may break
> existing API, Minor release may only extend existing API, Patch release may
> not modify API at all.
>
> ad 2) I've been looking into few tools to perform this check, like Clirr
> [2] and some others [3] (not all of them). I liked Clirr best. The
> highlights are that it is a Maven plugin under Apache license and that it
> does not need jar files or some generated interface specification of the
> previous version to perform compatibility check; instead, it can download
> the previous version's jars with Maven itself. You just set e.g.
> <comparisonVersion>0.20.0</comparisonVersion> in pom.xml and things just
> work.
>
> ad 3) User-facing api is everything declared "public" in modules
> artemis-core-client, artemis-jms-client, artemis-jms-server. Am I missing
> anything, or including what should not be?
>
> If I can finalize the list of user-facing API classes in point 3, I could
> maybe run Clirr with previous releases and try to find an instance where
> incompatible change occurred. If I could manage that, it would be a great
> justification for this proposal as it would show its necessity. What are
> your thoughts on this?
>
> [1] https://docs.oracle.com/javase/specs/jls/se7/html/jls-13.html
> [2] http://www.mojohaus.org/clirr-maven-plugin/
> [3] http://stackoverflow.com/a/15919340/1047788
>
> Cheers,


-- 
Christian Schneider
http://www.liquid-reality.de

Open Source Architect
http://www.talend.com


Mime
View raw message