This document is still under discussion and does not (yet) represent an agreed guideline
Deprecation
jclouds avoids backwards-incompatible changes between minor versions (e.g. from MAJOR.x to MAJOR.y) unless exceptional circumstances arise, e.g. critical security issues. Changes that are not backwards compatible should be approached as follows:
- Deprecation of code and removal of deprecated code will only happen on major releases (e.g. MAJOR.0)
- The new methods, classes, etc. are committed to master and the latest release branch (branch MAJOR.x)
The old methods, classes, etc. that are to be removed are marked as @Deprecated (with an annotation and a Javadoc tag) on the latest release branch. The Javadoc should explain:
- in which release (typically, the next major version, MAJOR+1.0) the deprecated method, class, etc. will be removed
- which alternative(s) to use
- The old methods, classes etc. can be removed from master in the next major release
Beta
Methods and classes that are regarded as experimental and which may change frequently can be designated as such by adding a @Beta annotation and a comment in the Javadoc, which explains when this method, class etc. was introduced.
Classes or methods marked as beta may change in a backwards-incompatible way even between minor versions, e.g. from MAJOR.MINOR to MAJOR.MINOR+1. Beta methods and classes will be promoted to non-beta status only in major releases (e.g. MAJOR.0).
TODO: do we want to add an indication of how many MAJOR releases the user might have to wait?
The beta status is intended only for individual methods or classes. For entire providers and apis, see the next section.
jclouds-labs
Providers and APIs in the jclouds-labs repository are also experimental. All functionality in jclouds-labs, including classes and methods, is considered beta and may change in a backwards-incompatible between minor versions.
This applies only to the jclouds-labs repository, not jclouds-labs-aws, jclouds-labs-google or jclouds-labs-openstack.