From b0782cbfc04d0d2cf0c5f54a6719e7586999682e Mon Sep 17 00:00:00 2001 From: Doug Meil Date: Wed, 24 Aug 2011 21:10:57 +0000 Subject: [PATCH] HBASE-4250 developer.xml git-svn-id: https://svn.apache.org/repos/asf/hbase/trunk@1161277 13f79535-47bb-0310-9956-ffa450edef68 --- src/docbkx/developer.xml | 208 ++++++++++++++++++++++++++++++++------- 1 file changed, 173 insertions(+), 35 deletions(-) diff --git a/src/docbkx/developer.xml b/src/docbkx/developer.xml index a634b7a120d..42dbac5dd66 100644 --- a/src/docbkx/developer.xml +++ b/src/docbkx/developer.xml @@ -83,6 +83,8 @@ Access restriction: The method getLong(Object, long) from the type Unsafe is not Maven Build Commands All commands executed from the local HBase project directory. + Note: use Maven 2, not Maven 3. +
Compile @@ -103,30 +105,7 @@ mvn test -Dtest=TestXYZ
-
- Unit Tests - In HBase we use JUnit 4. - If you need to run miniclusters of HDFS, ZooKeeper, HBase, or MapReduce testing, - be sure to checkout the HBaseTestingUtility. - Alex Baranau of Sematext describes how it can be used in - HBase Case-Study: Using HBaseTestingUtility for Local Testing and Development (2010). - -
- Mockito - Sometimes you don't need a full running server - unit testing. For example, some methods can make do with a - a org.apache.hadoop.hbase.Server instance - or a org.apache.hadoop.hbase.master.MasterServices - Interface reference rather than a full-blown - org.apache.hadoop.hbase.master.HMaster. - In these cases, you maybe able to get away with a mocked - Server instance. For example: - - - -
-
- +
Getting Involved HBase gets better only when people contribute! @@ -156,13 +135,50 @@ mvn test -Dtest=TestXYZ Trivial: Useful enhancements but generally cosmetic. -
+ + + +
+ Developing
Codelines 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). If you have any questions on this just send an email to the dev dist-list.
-
+ +
+ Unit Tests + In HBase we use JUnit 4. + If you need to run miniclusters of HDFS, ZooKeeper, HBase, or MapReduce testing, + be sure to checkout the HBaseTestingUtility. + Alex Baranau of Sematext describes how it can be used in + HBase Case-Study: Using HBaseTestingUtility for Local Testing and Development (2010). + +
+ Mockito + Sometimes you don't need a full running server + unit testing. For example, some methods can make do with a + a org.apache.hadoop.hbase.Server instance + or a org.apache.hadoop.hbase.master.MasterServices + Interface reference rather than a full-blown + org.apache.hadoop.hbase.master.HMaster. + In these cases, you maybe able to get away with a mocked + Server instance. For example: + + TODO... + + +
+
+ Code Standards + See and . + +
+
+ +
+ +
Submitting Patches
Create Patch @@ -185,23 +201,145 @@ mvn test -Dtest=TestXYZ
Attach Patch to Jira - 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. + 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. + + 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! + +
+ +
+ Common Patch Feedback + The following items are representative of common patch feedback. Your patch process will go faster if these are + taken into account before submission. - 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! + + See the Java coding standards + for more information on coding conventions in Java. + +
+ Space Invaders + Rather than do this... + +if ( foo.equals( bar ) ) { // don't do this + + ... do this instead... + +if (foo.equals(bar)) { + + + Also, rather than do this... + +foo = barArray[ i ]; // don't do this + + ... do this instead... + +foo = barArray[i]; +
-
+
+ Auto Generated Code + Auto-generated code in Eclipse often looks like this... + + public void readFields(DataInput arg0) throws IOException { // don't do this + foo = arg0.readUTF(); // don't do this + + ... do this instead ... + + public void readFields(DataInput di) throws IOException { + foo = di.readUTF(); + + See the difference? 'arg0' is what Eclipse uses for arguments by default. + +
+
+ Long Lines + + Keep lines less than 80 characters. + +Bar bar = foo.veryLongMethodWithManyArguments(argument1, argument2, argument3, argument4, argument5); // don't do this + + ... do this instead ... + +Bar bar = foo.veryLongMethodWithManyArguments(argument1, + argument2, argument3,argument4, argument5); + + ... or this, whichever looks better ... + +Bar bar = foo.veryLongMethodWithManyArguments( + argument1, argument2, argument3,argument4, argument5); + + +
+
+ Trailing Spaces + + This happens more than people would imagine. + +Bar bar = foo.getBar(); <--- imagine there's an extra space(s) after the semicolon instead of a line break. + + Make sure there's a line-break after the end of your code, and also avoid lines that have nothing + but whitespace. + +
+
+ Implementing Writable + Every class returned by RegionServers must implement Writable. If you + are creating a new class that needs to implement this interface, don't forget the default constructor. + +
+
+ Javadoc + This is also a very common feedback item. Don't forget Javadoc! + +
+
+ Javadoc - Useless Defaults + Don't just leave the @param arguments the way your IDE generated them. Don't do this... + + /** + * + * @param bar <---- don't do this!!!! + * @return <---- or this!!!! + */ + public Foo getFoo(Bar bar); + + ... either add something descriptive to the @param and @return lines, or just remove them. + But the preference is to add something descriptive and useful. + +
+
+ Unrelated Code Formating or Auto-Reformating + 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. + +
+
+ Ambigious Unit Tests + Make sure that you're clear about what you are testing in your unit tests and why. + +
+ +
+ +
+ ReviewBoard + Larger patches should go through ReviewBoard. + +
Committing Patches Committers do this. See How To Commit in the HBase wiki. + Commiters will also resolve the Jira, typically after the patch passes a build. +
+ +
- -