What Modules Are Checked

RHQ maven build defines a set of modules that can be checked for API changes between releases. To nominate your module as a part of the public API, all you need to do is set a property called rhq.internal to false in your module's pom.xml:

<properties>
   <rhq.internal>false</rhq.internal>
</properties>

Invocation

To build RHQ with API changes tracking, all you need to do is to invoke the maven build with the "signature-check" profile active. This will check all the artifacts in the build against their latest released versions:

mvn verify -Psignature-check -DskipTests

Ignoring Differences

Sometimes, we need to make an API change. But the build as invoked above would fail, because there would be an API difference. The maven Clirr plugin comes with a way of specifying the ignored differences. The RHQ build is set up so that it looks at the file called intentional-api-changes-since-<YOUR_VERSION_HERE>.xml for the list of differences to ignore in each module (i.e. in the above example it would look for the files call intentional-api-changes-since-4.5.1.xml). The format of the file is described in the Clirr plugin documentation.

Intended Usage

When the next version of RHQ gets released, the intentional-api-changes-since-<PREVIOUS_RELEASES_VERSION>.xml files in various modules contain all the API changes that have been made since the last release. This is great for documentation. After that release, any other API change should be captured in a new "intentional" xml file, corresponding to that release (that by that time has become the "previous release version").

Following is an example of the intended workflow:

1. Release 4.5.1

2. Start of the development of 4.6.0

3. API changes recorded in intenational-api-changes-since-4.5.1.xml

4. Release of 4.6.0

5. Start of development of 4.7.0

6. API changes recorded in intentional-api-changes-since-4.6.0.xml

7. ...