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
