JBoss Community Archive (Read Only)

RHQ 4.9

Design - API Compatibility

RHQ is a platform project that requires an API compatibility plan in order to support multiple compatible higher level projects deployed on top of it. As a platform it must maintain not only backward compatibility, but also have some amount of degraded forward compatibility where possible. As there may be two, three or more separate apps running on top of the platform with different release cycles, focusing on compatibility with the core model will simplify the compatiblity matrix over what would otherwise be pointwise integrations between projects. Where specific point-wise integrations are also beneficial, further compatibility and testing of a specific nature will be necessary.

The base RHQ rev cycle will take into account the typical compatibility needs of the projects that extend it in order to support co-deployments. Longer major revision platform cycles are the goal as they simplify compatibility testing and overlap of supported versions between many extension projects. Effort will also be made to maintain compatibility even between major versions and will only be broken if no compatible options exist or the deprecation has been published for an extended period of time. While not documented here, interproject dependencies should also be tracked and compatibility efforts made where tight integration happens between projects. Finally, patch releases will likely also be released passed the upgrade to a new major revision for the previous revision in order to support overlap until new releases of dependent projects are available.

Conceptual Model

This release model shows the relative release cycles of the base RHQ platform versus two concept projects called foo and bar.


This example shows a possible release iteration schedule. NOTE: "alpha" and "beta" represent two different software products that run with the core RHQ - they do not represent versions of a single product. Some examples of compatibility requirements shown here are.

Compatibility Types

Service Interfaces

Access to the server side APIs of RHQ should be backward compatible for minor revisions. New services may be added and new methods may be added, but incompatible signature changes are not allowed. Deprecation rules should be followed. The same goes for web service or JSON interfaces. The client library and cli scripts must also remain compatible and follow deprecation rules.

Extension Interfaces

Primarily plugin interfaces, these interfaces are designed as specific extension points and often involve bi-directional calling and implementation of interfaces by the extender. Plugins should remain compatibility for minor revisions of the platform and all attempts should be made to make them compatible to major revisions. As an example, a new method can not be added to a plugin facet in a minor revision as it would cause existing implementations of that interface to be incompatible with the change. This rule goes for both agent plugins and server side plugins and extensions.

Extension Schemas

To meet the above goals of plugin compatibility in minor revisions a given version of the plugin schema should be supported for the entire minor release cycle. New plugin schemas can be added that are compatible supersets of the earlier schemas, but no removals or name alterations are allowable. 

Perspective Hooks

Perspective hooks should remain backward compatible for all minor revisions.


Deprecations in interfaces and services should last until the next major revision or longer.


For product releases on a minor platform change it should be minimally tested against the most recent version of each project


Release type examples

  • Major revision: 1.x -> 2.0

  • Minor revision 1.4 -> 1.5

  • Patch revision 1.4.0 -> 1.4.1

JBoss.org Content Archive (Read Only), exported from JBoss Community Documentation Editor at 2020-03-13 08:05:51 UTC, last content change 2013-09-18 19:40:46 UTC.