[Jclouds Wiki] Update of "DeprecationAndBetaPolicy" by AndrewPhillips

[Apache Wiki <wi...@apache.org>]

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 AndrewPhillips:
https://wiki.apache.org/jclouds/DeprecationAndBetaPolicy

New page:
<<TableOfContents(2)>>

'''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 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:

1. The new methods, classes etc. are committed to master and the latest release branch (branch A.B.x)
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. which alternative(s) to use.
1. The old methods, classes etc. can be removed from master.

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.

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).

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.

=== jclouds-labs ===

jclouds-labs is the jclouds repository for experimental APIs and providers. Any functionality, including classes and methods, may change in a backwards-incompatible between minor versions.