+1 deprecation guidelines that you proposed. I created a PR[1] adding them to the dev guide on the website. We can tweak the wording there, if need be.
Cheers, Mike [1] https://github.com/apache/incubator-brooklyn/pull/843 On Mon, Aug 17, 2015 at 2:03 PM, Aled Sage <[email protected]> wrote: > Hi all, > > We should think about + document our deprecation policy - I can't find it > in our docs [1]. > > I could only find a pre-apache mailing list conversation ( > [email protected], from 5/9/12) where we proposed: > > While we're still at 0.x, we keep deprecated methods for one release > (e.g. if deprecated in 0.4.0-SNAPSHOT, then it will be in 0.4 and > deleted for 0.5. > When we get to >= 1.x, then we keep it for two releases. > > Note that semantic versioning [2] would have us go from 1.x to 2.y before > we can delete anything from the public API (except in 0.x releases). > > Defining how much of the code is the "public API" is another question. > > --- > The other thing to document is guidelines for using @Deprecated. We could > say: > > * Always include @deprecated in javadoc > e.g. "@deprecated since 0.7.0; instead use {@link ...}" > o say when it was deprecated > o say what to use instead - e.g. link to alternative method, > and/or code snippet, etc > * Consider including a log.warn when a deprecated method or config > option is used, saying who is using it (e.g. useful if deprecated > config keys are used in yaml). > (if it's a method which might be called a lot, some convenience for > "warn once per entity" would be helpful) > * Link to [3] > > We should also try to consistently use @Since for new classes/methods > being added. > > Aled > > p.s. Of course this is a tricky time to discuss deprecation: our current > package renames will definitely not follow any such deprecation policy! > > [1] https://brooklyn.incubator.apache.org/documentation > [2] http://semver.org/ > [3] > https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html > > -- Cloudsoft Corporation Limited, Registered in Scotland No: SC349230. Registered Office: 13 Dryden Place, Edinburgh, EH9 1RP This e-mail message is confidential and for use by the addressee only. If the message is received by anyone other than the addressee, please return the message to the sender by replying to it and then delete the message from your computer. Internet e-mails are not necessarily secure. Cloudsoft Corporation Limited does not accept responsibility for changes made to this message after it was sent. Whilst all reasonable care has been taken to avoid the transmission of viruses, it is the responsibility of the recipient to ensure that the onward transmission, opening or use of this message and any attachments will not adversely affect its systems or data. No responsibility is accepted by Cloudsoft Corporation Limited in this regard and the recipient should carry out such virus and other checks as it considers appropriate.
