Author: dmeil
Date: Wed Aug 24 21:10:57 2011
New Revision: 1161277
URL: http://svn.apache.org/viewvc?rev=1161277&view=rev
Log:
HBASE-4250 developer.xml
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=1161277&r1=1161276&r2=1161277&view=diff
==============================================================================
--- hbase/trunk/src/docbkx/developer.xml (original)
+++ hbase/trunk/src/docbkx/developer.xml Wed Aug 24 21:10:57 2011
@@ -83,6 +83,8 @@ Access restriction: The method getLong(O
<title>Maven Build Commands</title>
<para>All commands executed from the local HBase project directory.
</para>
+ <para>Note: use Maven 2, not Maven 3.
+ </para>
<section xml:id="maven.build.commands.compile">
<title>Compile</title>
<programlisting>
@@ -103,30 +105,7 @@ mvn test -Dtest=TestXYZ
</section>
</section>
- <section xml:id="unit.tests">
- <title>Unit Tests</title>
- <para>In HBase we use <link xlink:href="http://junit.org";>JUnit</link>
4.
- If you need to run miniclusters of HDFS, ZooKeeper, HBase, or
MapReduce testing,
- be sure to checkout the <classname>HBaseTestingUtility</classname>.
- Alex Baranau of Sematext describes how it can be used in
- <link
xlink:href="http://blog.sematext.com/2010/08/30/hbase-case-study-using-hbasetestingutility-for-local-testing-development/";>HBase
Case-Study: Using HBaseTestingUtility for Local Testing and Development</link>
(2010).
- </para>
- <section xml:id="mockito">
- <title>Mockito</title>
- <para>Sometimes you don't need a full running server
- unit testing. For example, some methods can make do with a
- a <classname>org.apache.hadoop.hbase.Server</classname> instance
- or a
<classname>org.apache.hadoop.hbase.master.MasterServices</classname>
- Interface reference rather than a full-blown
- <classname>org.apache.hadoop.hbase.master.HMaster</classname>.
- In these cases, you maybe able to get away with a mocked
- <classname>Server</classname> instance. For example:
- <programlisting>
- </programlisting>
- </para>
- </section>
- </section>
-
+
<section xml:id="getting.involved">
<title>Getting Involved</title>
<para>HBase gets better only when people contribute!
@@ -156,13 +135,50 @@ mvn test -Dtest=TestXYZ
<listitem>Trivial: Useful enhancements but generally
cosmetic.</listitem>
</itemizedlist>
</para>
- </section>
</section>
+ </section>
+ </section> <!-- getting involved -->
+
+ <section xml:id="developing">
+ <title>Developing</title>
<section xml:id="codelines"><title>Codelines</title>
<para>Most development is done on TRUNK. However, there are
branches for minor releases (e.g., 0.90.1, 0.90.2, and 0.90.3 are on the 0.90
branch).</para>
<para>If you have any questions on this just send an email to the
dev dist-list.</para>
</section>
- <section xml:id="submitting.patches">
+
+ <section xml:id="unit.tests">
+ <title>Unit Tests</title>
+ <para>In HBase we use <link
xlink:href="http://junit.org";>JUnit</link> 4.
+ If you need to run miniclusters of HDFS, ZooKeeper, HBase, or
MapReduce testing,
+ be sure to checkout the <classname>HBaseTestingUtility</classname>.
+ Alex Baranau of Sematext describes how it can be used in
+ <link
xlink:href="http://blog.sematext.com/2010/08/30/hbase-case-study-using-hbasetestingutility-for-local-testing-development/";>HBase
Case-Study: Using HBaseTestingUtility for Local Testing and Development</link>
(2010).
+ </para>
+ <section xml:id="mockito">
+ <title>Mockito</title>
+ <para>Sometimes you don't need a full running server
+ unit testing. For example, some methods can make do with a
+ a <classname>org.apache.hadoop.hbase.Server</classname> instance
+ or a
<classname>org.apache.hadoop.hbase.master.MasterServices</classname>
+ Interface reference rather than a full-blown
+ <classname>org.apache.hadoop.hbase.master.HMaster</classname>.
+ In these cases, you maybe able to get away with a mocked
+ <classname>Server</classname> instance. For example:
+ <programlisting>
+ TODO...
+ </programlisting>
+ </para>
+ </section>
+ <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 -->
+
+ </section> <!-- developing -->
+
+ <section xml:id="submitting.patches">
<title>Submitting Patches</title>
<section xml:id="submitting.patches.create">
<title>Create Patch</title>
@@ -185,23 +201,145 @@ mvn test -Dtest=TestXYZ
</section>
<section xml:id="submitting.patches.jira">
<title>Attach Patch to Jira</title>
- <para>The patch should be attached to the associated Jira ticket
"More Actions -> Attach Files". Make sure you click the
- ASF license inclusion, otherwise the patch can't be considered for
inclusion.
+ <para>The patch should be attached to the associated Jira ticket
"More Actions -> Attach Files". Make sure you click the
+ ASF license inclusion, otherwise the patch can't be considered for
inclusion.
+ </para>
+ <para>Once attached to the ticket, click "Submit Patch" and
+ the status of the ticket will change. Committers will review
submitted patches for inclusion into the codebase. Please
+ understand that not every patch may get committed, and that
feedback will likely be provided on the patch. Fear not, though,
+ because the HBase community is helpful!
+ </para>
+ </section>
+
+ <section xml:id="common.patch.feedback">
+ <title>Common Patch Feedback</title>
+ <para>The following items are representative of common patch
feedback. Your patch process will go faster if these are
+ taken into account <emphasis>before</emphasis> submission.
+ </para>
+ <para>
+ See the <link
xlink:href="http://www.oracle.com/technetwork/java/codeconv-138413.html";>Java
coding standards</link>
+ for more information on coding conventions in Java.
</para>
- <para>Once attached to the ticket, click "Submit Patch" and
- the status of the ticket will change. Committers will review
submitted patches for inclusion into the codebase. Please
- understand that not every patch may get committed, and that feedback
will likely be provided on the patch. Fear not, though,
- because the HBase community is helpful!
+ <section xml:id="common.patch.feedback.space.invaders">
+ <title>Space Invaders</title>
+ <para>Rather than do this...
+<programlisting>
+if ( foo.equals( bar ) ) { // don't do this
+</programlisting>
+ ... do this instead...
+<programlisting>
+if (foo.equals(bar)) {
+</programlisting>
+ </para>
+ <para>Also, rather than do this...
+<programlisting>
+foo = barArray[ i ]; // don't do this
+</programlisting>
+ ... do this instead...
+<programlisting>
+foo = barArray[i];
+</programlisting>
</para>
</section>
- </section>
+ <section xml:id="common.patch.feedback.autogen">
+ <title>Auto Generated Code</title>
+ <para>Auto-generated code in Eclipse often looks like this...
+<programlisting>
+ public void readFields(DataInput arg0) throws IOException { // don't do
this
+ foo = arg0.readUTF(); // don't do this
+</programlisting>
+ ... do this instead ...
+<programlisting>
+ public void readFields(DataInput di) throws IOException {
+ foo = di.readUTF();
+</programlisting>
+ See the difference? 'arg0' is what Eclipse uses for arguments by
default.
+ </para>
+ </section>
+ <section xml:id="common.patch.feedback.longlines">
+ <title>Long Lines</title>
+ <para>
+ Keep lines less than 80 characters.
+<programlisting>
+Bar bar = foo.veryLongMethodWithManyArguments(argument1, argument2, argument3,
argument4, argument5); // don't do this
+</programlisting>
+ ... do this instead ...
+<programlisting>
+Bar bar = foo.veryLongMethodWithManyArguments(argument1,
+ argument2, argument3,argument4, argument5);
+</programlisting>
+ ... or this, whichever looks better ...
+<programlisting>
+Bar bar = foo.veryLongMethodWithManyArguments(
+ argument1, argument2, argument3,argument4, argument5);
+</programlisting>
+ </para>
+ </section>
+ <section xml:id="common.patch.feedback.trailingspaces">
+ <title>Trailing Spaces</title>
+ <para>
+ This happens more than people would imagine.
+<programlisting>
+Bar bar = foo.getBar(); <--- imagine there's an extra space(s) after
the semicolon instead of a line break.
+</programlisting>
+ Make sure there's a line-break after the end of your code, and
also avoid lines that have nothing
+ but whitespace.
+ </para>
+ </section>
+ <section xml:id="common.patch.feedback.writable">
+ <title>Implementing Writable</title>
+ <para>Every class returned by RegionServers must implement
<code>Writable</code>. If you
+ are creating a new class that needs to implement this interface,
don't forget the default constructor.
+ </para>
+ </section>
+ <section xml:id="common.patch.feedback.javadoc">
+ <title>Javadoc</title>
+ <para>This is also a very common feedback item. Don't forget
Javadoc!
+ </para>
+ </section>
+ <section xml:id="common.patch.feedback.javadoc.defaults">
+ <title>Javadoc - Useless Defaults</title>
+ <para>Don't just leave the @param arguments the way your IDE
generated them. Don't do this...
+<programlisting>
+ /**
+ *
+ * @param bar <---- don't do this!!!!
+ * @return <---- or this!!!!
+ */
+ public Foo getFoo(Bar bar);
+</programlisting>
+ ... either add something descriptive to the @param and @return
lines, or just remove them.
+ But the preference is to add something descriptive and useful.
+ </para>
+ </section>
+ <section xml:id="common.patch.feedback.massreformat">
+ <title>Unrelated Code Formating or Auto-Reformating</title>
+ <para>If you submit a patch for one thing, don't do
auto-reformatting or unrelated reformatting of code on a completely
+ different area of code.
+ </para>
+ </section>
+ <section xml:id="common.patch.feedback.tests">
+ <title>Ambigious Unit Tests</title>
+ <para>Make sure that you're clear about what you are testing in
your unit tests and why.
+ </para>
+ </section>
+
+ </section> <!-- patch feedback -->
+
+ <section xml:id="reviewboard">
+ <title>ReviewBoard</title>
+ <para>Larger patches should go through <link
xlink:href="http://reviews.apache.org";>ReviewBoard</link>.
+ </para>
+ </section>
<section xml:id="committing.patches">
<title>Committing Patches</title>
<para>
Committers do this. See <link
xlink:href="http://wiki.apache.org/hadoop/Hbase/HowToCommit";>How To
Commit</link> in the HBase wiki.
</para>
+ <para>Commiters will also resolve the Jira, typically after the
patch passes a build.
+ </para>
</section>
+
+ </section> <!-- submitting patches -->
- </section>
-
</chapter>
