Dear Wiki user, You have subscribed to a wiki page or wiki category on "Jclouds Wiki" for change notification.
The "DeprecationAndBetaPolicy" page has been changed by EverettToews: https://wiki.apache.org/jclouds/DeprecationAndBetaPolicy?action=diff&rev1=2&rev2=3 === Deprecation === - jclouds avoids backwards-incompatible changes between minor versions (e.g. from A.B.X to A.B.Y) unless exceptional circumstances arise, e.g. critical security issues. Changes that are not backwards compatible should be approached as follows: + jclouds avoids backwards-incompatible changes between minor versions (e.g. from MAJOR.x to MAJOR.x) unless exceptional circumstances arise, e.g. critical security issues. Changes that are not backwards compatible should be approached as follows: + 1. Deprecation of code and removal of deprecated code will only happen on major releases (e.g. MAJOR.0) - 1. The new methods, classes etc. are committed to master and the latest release branch (branch A.B.x) + 1. The new methods, classes, etc. are committed to master and the latest release branch (branch MAJOR.0) - 1. 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: + 1. 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: - 1. in which release (typically, the next major version, A.C.0) the deprecated method, class etc. will be removed + 1. in which release (typically, the next major version, MAJOR+1.0) the deprecated method, class, etc. will be removed - 1. which alternative(s) to use. + 1. which alternative(s) to use - 1. The old methods, classes etc. can be removed from master. + 1. The old methods, classes etc. can be removed from master in the next major release - - TODO: How do we want to handle the case where we want to deprecate something in e.g. 1.7.4, but 1.8.0 is the next release. Then users will have not seen the deprecation in any 1.7.x version and are not able to prepare for it. Thoughts here? Include in release notes? Say that, in that case, they must remain deprecated in 1.8.x and can only be removed in 1.9.0? === 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 A.B.X to A.B.Y. + 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 - jclouds aims to no promote a method or class out of beta - or to discard it - by the major release ''after'' next (i.e. A.D.0 if the current release branch is A.B.x). + jclouds aims to not promote a method or class out of beta - or to discard it - by the major release ''after'' next (i.e. A.D.0 if the current release branch is A.B.x). < I'm confused by this. I'm not sure what the intent is here. Could this be replaced by... + + Beta methods and classes will be promoted to non-beta status only in major releases (e.g. MAJOR.0) TODO: decide whether we're happy with a statement like that? - The beta status is intended only for individual methods or classes, not for entire providers. See the next section. + The beta status is intended only for individual methods or classes. For entire providers and apis, see the next section. === jclouds-labs ===
