Thanks Mike, I've merged your PR. All, which covers the second part
(i.e. guidelines for using @Deprecated).
We still need to reach agreement on our deprecation policy.
Aled
On 18/08/2015 19:29, Mike Zaccardo wrote:
+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
