brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From aleds...@apache.org
Subject [1/2] incubator-brooklyn git commit: Add deprecation guidelines to website docs
Date Tue, 18 Aug 2015 19:08:13 GMT
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 <mike.zaccardo@cloudsoftcorp.com>
Authored: Tue Aug 18 11:26:35 2015 -0700
Committer: Mike Zaccardo <mike.zaccardo@cloudsoftcorp.com>
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>


Mime
View raw message