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.
-
You're running foo 3.0 and bar 3.1 on RHQ 3.0
-
In order to upgrade to foo 3.1 you'll need RHQ 3.1, therefore bar 3.1 must run on RHQ 3.1
-
-
You're running foo 3.1.1 and bar 4.0 and are considering an upgrade to foo 4.0
-
You would have to wait for a release of bar compatible with RHQ 4.x. (this argues for good planning on major platform releases)
-
It also argues for fewer major releases or to have compatibility in major releases also a goal if not a rule
-
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
Deprecations in interfaces and services should last until the next major revision or longer.
Testing
For product releases on a minor platform change it should be minimally tested against the most recent version of each project
Glossary
Release type examples
-
Major revision: 1.x -> 2.0
-
Minor revision 1.4 -> 1.5
-
Patch revision 1.4.0 -> 1.4.1