Repository: incubator-brooklyn Updated Branches: refs/heads/master 2767ffade -> ce5ddaf2a
Add deprecation guidelines to website docs Project: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/repo Commit: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/commit/8a3fa6e4 Tree: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/tree/8a3fa6e4 Diff: http://git-wip-us.apache.org/repos/asf/incubator-brooklyn/diff/8a3fa6e4 Branch: refs/heads/master Commit: 8a3fa6e4a436c70833b9c2b85602fbf6fa2d4cd9 Parents: 2767ffa 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/incubator-brooklyn/blob/8a3fa6e4/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>
