You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@hbase.apache.org by st...@apache.org on 2012/03/01 17:48:45 UTC
svn commit: r1295668 - /hbase/trunk/src/docbkx/developer.xml
Author: stack
Date: Thu Mar 1 16:48:44 2012
New Revision: 1295668
URL: http://svn.apache.org/viewvc?rev=1295668&view=rev
Log:
HBASE-4403 Adopt interface stability/audience classifications from Hadoop
Modified:
hbase/trunk/src/docbkx/developer.xml
Modified: hbase/trunk/src/docbkx/developer.xml
URL: http://svn.apache.org/viewvc/hbase/trunk/src/docbkx/developer.xml?rev=1295668&r1=1295667&r2=1295668&view=diff
==============================================================================
--- hbase/trunk/src/docbkx/developer.xml (original)
+++ hbase/trunk/src/docbkx/developer.xml Thu Mar 1 16:48:44 2012
@@ -506,12 +506,29 @@ to fix the failing tests.
</programlisting>
</para>
</section>
+ </section> <!-- unit tests -->
+
<section xml:id="code.standards">
<title>Code Standards</title>
<para>See <xref linkend="eclipse.code.formatting"/> and <xref linkend="common.patch.feedback"/>.
</para>
- </section>
- </section> <!-- unit tests -->
+ <para>Also, please pay attention to the interface stability/audience classifications that you
+ will see all over our code base. They look like this at the head of the class:
+ <programlisting>@InterfaceAudience.Public
+@InterfaceStability.Stable</programlisting>
+ </para>
+ <para>If the <classname>InterfaceAudience</classname> is <varname>Private</varname>,
+ we can change the class (and we do not need to include a <classname>InterfaceStability</classname> mark).
+ If a class is marked <varname>Public</varname> but its <classname>InterfaceStability</classname>
+ is marked <varname>Unstable</varname>, we can change it. If it's
+ marked <varname>Public</varname>/<varname>Evolving</varname>, we're allowed to change it
+ but should try not to. If it's <varname>Public</varname> and <varname>Stable</varname>
+ we can't change it without a deprecation path or with a really GREAT reason.</para>
+ <para>When you add new classes, mark them with the annotations above if publically accessible.
+ If you are not cleared on how to mark your additions, ask up on the dev list.
+ </para>
+ <para>This convention comes from our parent project Hadoop.</para>
+ </section> <!-- code.standards -->
</section> <!-- developing -->
@@ -539,6 +556,10 @@ to fix the failing tests.
<para>Yes, please. Please try to include unit tests with every code patch (and especially new classes and large changes).
Make sure unit tests pass locally before submitting the patch.</para>
<para>Also, see <xref linkend="mockito"/>.</para>
+ <para>If you are creating a new unit test class, notice how other unit test classes have classification/sizing
+ annotations at the top and a static method on the end. Be sure to include these in any new unit test files
+ you generate. See <xref linkend="hbase.tests" /> for more on how the annotations work.
+ </para>
</section>
<section xml:id="submitting.patches.jira">
<title>Attach Patch to Jira</title>
@@ -687,5 +708,6 @@ Bar bar = foo.getBar(); <--- imag
</section>
</section> <!-- submitting patches -->
+
</chapter>