brooklyn-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From henev...@apache.org
Subject [16/51] [abbrv] brooklyn-docs git commit: Add deprecation guidelines to website docs
Date Mon, 01 Feb 2016 17:44:42 GMT
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 <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/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>


Mime
View raw message