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:
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:
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.
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:
- Release 4.5.1
- Start of the development of 4.6.0
- API changes recorded in intenational-api-changes-since-4.5.1.xml
- Release of 4.6.0
- Start of development of 4.7.0
- API changes recorded in intentional-api-changes-since-4.6.0.xml