Add deprecation guidelines to website docs
Project: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/repo Commit: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/commit/10f04d2d Tree: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/tree/10f04d2d Diff: http://git-wip-us.apache.org/repos/asf/brooklyn-docs/diff/10f04d2d Branch: refs/heads/0.8.0-incubating Commit: 10f04d2d7f894867f00b3258589d942b64cef31c Parents: 4a0c24f Author: Mike Zaccardo <[email protected]> Authored: Tue Aug 18 11:26:35 2015 -0700 Committer: Mike Zaccardo <[email protected]> Committed: Tue Aug 18 11:26:35 2015 -0700 ---------------------------------------------------------------------- docs/guide/dev/tips/index.md | 9 +++++++++ 1 file changed, 9 insertions(+) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/brooklyn-docs/blob/10f04d2d/docs/guide/dev/tips/index.md ---------------------------------------------------------------------- diff --git a/docs/guide/dev/tips/index.md b/docs/guide/dev/tips/index.md index 8a45d46..858c2c6 100644 --- a/docs/guide/dev/tips/index.md +++ b/docs/guide/dev/tips/index.md @@ -20,6 +20,15 @@ title: Miscellaneous Tips and Tricks or the brooklyn-relevant parts, under ``~/.m2/repository``. Also note your IDE might be recompiling at the same time as a Maven command-line build, so consider turning off auto-build. + +* When a class or method becomes deprecated, always include ``@deprecated`` in the Javadoc + e.g. "``@deprecated since 0.7.0; instead use {@link ...}``" + * Include when it was deprecated + * Suggest what to use instead -- e.g. link to alternative method, and/or code snippet, etc. + * Consider logging a warning message 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) + * See the [Java deprecation documentation](https://docs.oracle.com/javase/7/docs/technotes/guides/javadoc/deprecation/deprecation.html) <a name="EntityDesign"></a>
