hadoop-common-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Apache Wiki <wikidi...@apache.org>
Subject [Hadoop Wiki] Update of "Hbase/HowToContribute" by spookysam
Date Tue, 19 Apr 2011 14:24:54 GMT
Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Hadoop Wiki" for change notification.

The "Hbase/HowToContribute" page has been changed by spookysam.
http://wiki.apache.org/hadoop/Hbase/HowToContribute?action=diff&rev1=65&rev2=66

--------------------------------------------------

  But take care about the following points
   * All public classes and methods should have informative [[http://java.sun.com/j2se/javadoc/writingdoccomments/|Javadoc
comments]].
    * Do not use @author tags.
+   * Please include the Apache License 
-   * Please include the Apache License header at the start of each file.
-  * Code should be formatted according to [[http://java.sun.com/docs/codeconv/|Sun's conventions]],
with two exceptions:
-   1. Indent two spaces per level, not four.
-   2. Use spaces and not tabs.
-  * If using eclipse, [[https://issues.apache.org/jira/browse/HBASE-3678|HBASE-3678]] has
an appropriate formatter attached with instructions on how to load it up into eclipse.
-  * Contributions must pass existing unit tests.
-  * New unit tests should be provided to demonstrate bugs and fixes.  [[http://www.junit.org|JUnit4]]
is our test framework:
-   * All test class names should start with {{{Test}}}.
-   * Use JUnit4 annotations for defining before and after method / class invocations, for
example {{{@Before}}}
-   * Some classes may still extend {{{junit.framework.TestCase}}} based on the old version
of JUnit. If you need to modify these files, migrate them to the JUnit4 convention.
-   * Define methods within your class whose names begin with {{{test}}} and annotate them
with {{{@Test}}}, and call JUnit's many assert methods to verify conditions; these methods
will be executed when you run {{{mvn test}}}.
-   * By default, do not let tests write any temporary files to {{{/tmp}}}.  Instead, the
tests should write to the location specified by the {{{test.build.data}}} system property.
The {{{org.apache.hadoop.hbase.HBaseTestingUtility}}} class has some utility methods to assist
with this.
-   * If a HBase cluster is needed by your test, you should use the {{{org.apache.hadoop.hbase.HBaseTestingUtility}}}
to start and stop the cluster. See the {{{org.apache.hadoop.hbase.client.TestAdmin}}} and
{{{org.apache.hadoop.hbase.client.TestFromClientSide}}} classes as these are good examples
of how the testing utilities can be used.
-   * Place your class in the {{{src/test}}} tree.
-   * You can run all the unit tests with the command {{{mvn test}}}, or you can run a specific
unit test with the command {{{mvn test -Dtest=<ClassName>}}} (For example {{{mvn test
-Dtest=TestHBaseCluster}}})
-   * If you want to quickly build the code without running the tests you can run the command
{{{mvn install -DskipTests}}}
-   * If your test requires a port, be sure to use an ephemeral port by requesting port 0
in your code and passing the assigned port to the client.
  
- === New to Hbase ===
- For those contributors that are new to HBase, there is a label that is added to jira items
that are appropriate for you. When finding issues, add a search criteria for the label "noob"
to find all of these tasks. Furthermore, all contributors when logging jira items should consider
whether the new issue could be assigned to a HBase noob and add the label appropriately.
- 
- <<Anchor(eclipse)>>
- === Eclipse is your friend ===
- 
- If you use Eclipse, it can help you find problems before you submit your patch. Here's some
configuration tips:
- 
- Open Window->Preferences... and open Java->Compiler
-  * Under Errors/Warnings, set all entries to Warning, except for the following which should
be set to Ignore:
-   * __Code style__
-    * Unqualified access to instance field
-    * Undocumented empty block
-    * Non-externalized strings
-   * __Potential  programming problems__
-    * Boxing and unboxing conversions
-   * __Name shadowing and conflicts__
-    * Local variable declaration hides another field or variable
-   * __Deprecated and restricted API__
-    * Forbidden reference (access rules) should be set to Error
-  * Under Javadoc, all categories should be flagged as Warnings for Public members
-  * [http://itshumour.blogspot.com/2010/06/twenty-hilarious-funny-quotes.html|funny quotes]
for a tea break while you compile
- 
- If you can make all the yellow bars at the right of your editor pane disappear, you have
very well-formed Java code.
- 
- == Generating a patch ==
- 
- === Unit Tests ===
- Please make sure that all unit tests succeed before constructing your patch and that no
new javac compiler warnings are introduced by your patch.
- 
- {{{
- > cd hbase-core-trunk
- > mvn -Djavac.args="-Xlint -Xmaxwarns 1000" clean install
- }}}
- After a while, if you see
- {{{
- BUILD SUCCESSFUL
- }}}
- all is ok, but if you see
- {{{
- BUILD FAILURE
- }}}
- then please examine error messages in {{{target/surefire-reports}}} and fix things before
proceeding.
- 
- === Javadoc ===
- 
- Please also check the javadoc.
- 
- {{{
- > mvn javadoc:javadoc
- > firefox target/site/apidocs/index.html
- }}}
- 
- Examine all public classes you've changed to see that documentation is complete and informative.
 Your patch must not generate any javadoc warnings.
- 
- === Creating a patch ===
- Check to see what files you have modified with:
- {{{
- svn stat
- }}}
- 
- or if you're using git:
- {{{
- git status
- }}}
- 
- Add any new files with:
- {{{
- svn add src/.../MyNewClass.java
- }}}
- 
- or if you're using git:
- {{{
- git add src/.../MyNewClass.java
- }}}
- 
- In order to create a patch, just type:
- 
- {{{
- svn diff > patchname.txt
- }}}
- 
- or if you're using git:
- 
- {{{
- git diff > patchname.txt
- }}}
- 
- This will report all modifications done on HBase sources on your local disk and save them
into the ''patchname.txt'' file.  Read the patch file.  
- Make sure it includes ONLY the modifications required to fix a single issue.
- 
- Patch names should use the following convention:
- 
- {{{
- <jira_number>[<hbase_version_patch_applies_to>].patch
- }}}
- 
- The jira_number is required. hbase_version_patch_applies_to is optional in two cases:
-  1. The patch is for trunk
-  2. The Jira only fixes one version
- 
- Please do not:
-  * reformat code unrelated to the bug being fixed: formatting changes should be separate
patches/commits.
-  * comment out code that is now obsolete: just remove it.  
-  * insert comments around each change, marking the change: folks can use subversion to figure
out what's changed and by whom.
-  * make things public which are not required by end users.
- 
- Please do:
-  * try to adhere to the coding style of files you edit;
-  * comment code whose function or rationale is not obvious;
-  * update documentation (e.g., ''package.html'' files, this wiki, etc.)
- 
- === Applying a patch ===
- 
- To apply a patch either you generated or found from JIRA, you can issue 
- {{{
- patch -p0 <cool_patch.patch
- }}}
- if you just want to check whether the patch applies you can run patch with --dry-run option
- {{{
- patch -p0 --dry-run <cool_patch.patch
- }}}
- 
- If you are an Eclipse user, you can apply a patch by : 1. Right click project name in Package
Explorer , 2. Team -> Apply Patch 
- 
- === Review Process ===
- 
- If you're patch contains more than 2 files that are changed and not yet had a review, please
submit to  [[http://review.hbase.org |Review Board]]. Some helpful hints for Review Board:
-  * Add the JIRA number to the Bugs field
-  * Use JIRA name and the short title for the "Summary" Field (eg: HBASE-1234 fix X Y Z)
-  * You will need to click on the Publish button after you make a change.
-  * Once changes are published, email will sent to the dev mailing list.
-  * Don't upload the patch to JIRA until the final version has completed review (ie JIRA
should contain only 1 patch that has been reviewed)
-  * Use the [[CodeReviewChecklist| code review checklist]] as a guide when doing reviews
-  * Reviewers can approve the patch by clicking on the "Ship it" option.
-  * Should your patch earn a -1 review, set the issue status to 'Resume Progress', upload
a patch to Review Board with necessary fixes and then set the status to 'Submit Patch' again.
- 
- 
- === Contributing your work ===
- 
- Patches should be ''attached'' to a bug report in [[https://issues.apache.org/jira/browse/HBASE|HBase
JIRA]] via the '''Attach File''' link on the jira. Please note that the attachment should
be granted license to ASF for inclusion in ASF works (as per the [[http://www.apache.org/licenses/LICENSE-2.0|Apache
License]] ยง5). 
- 
- When you believe that your patch is ready to be committed, select the 'Submit Patch' link
from the 'Available Workflow Actions' section in Jira. 
- #Until there are automated Hudson patch builds, this will notify others that the patch is
ready to be reviewed.
- 
- ## The following section commented out until there are automated Hudson
- ## patch builds
- ##
- ## Submitted patches will be automatically tested against "trunk" by [http://hudson.zones.apache.org/hudson/
Hudson], the project's continuous integration engine.  Upon test completion, Hudson will add
a success ("+1") message or failure ("-1") to your bug report in Jira.  If your issue contains
multiple patch versions, Hudson tests the last patch uploaded.
- 
- Folks should run 'mvn clean install javadoc:javadoc' before selecting 'Submit Patch'.  Tests
should all pass.  Javadoc should report no warnings or errors.
- 
- ## Hudson's tests should only double-check things, and not be used as a primary patch tester,
which would create too much noise on the mailing list and in Jira.  Submitting patches that
fail Hudson testing is frowned on, (unless the failure is not actually due to the patch).
- 
- If your patch involves performance optimizations, they should be validated by benchmarks
that demonstrate an improvement.
- 
- Once a "+1, code reviewed" comment or "Ship it" from Review Board is received from a code
reviewer, a committer should then evaluate it within a few days and either: commit it; or
reject it with an explanation.
- 
- ## Once a "+1" comment is received from the automated patch testing system and a "+1, code
reviewed" comment is received from a code reviewer, a committer should then evaluate it within
a few days and either: commit it; or reject it with an explanation.
- 
- Please be patient.  Committers are busy people too.  If no one responds to your patch after
a few days, please make friendly reminders.  Please incorporate other's suggestions into into
your patch if you think they're reasonable.  Finally, remember that even a patch that is not
committed is useful to the community.
- 
- 
- 
- ## Should your patch earn a -1 on the Hudson test, set the issue status to 'Resume Progress',
upload a patch with necessary fixes and then set the status to 'Submit Patch' again.
- 
- Committers: for non-trivial changes, it is __'''required'''__ to get another committer to
review your patches before commit.  Use "Submit Patch" like other contributors, and then wait
for a "+1" from another committer before committing.  Please also try to frequently review
things in the patch queue.
- 
- === Releases prior to 0.21 ===
- 
- Previously HBase was using ant for builds. The commands above are intended for releases
0.21 and subsequent that use maven. If you want to make changes to the codebase prior to that,
please refer to the commands below that describe the modified steps.
- 
- Unit Tests:
- 
- {{{ant -Djavac.args="-Xlint -Xmaxwarns 1000" clean test tar}}}
- 
- alternatively, if you wanted to run just the tests alone use {{{ant test}}}, or you can
run a specific unit test with the command {{{ant test -Dtestcase=<ClassName>}}} (For
example {{{ant test -Dtestcase=TestHBaseCluster}}}) :
- 
- Javadoc:
- 
- {{{ant javadoc}}}
- 
- 
- == Jira Guidelines ==
- 
- Please comment on issues in Jira, making their concerns known.  Please also vote for issues
that are a high priority for you.
- 
- Please refrain from editing descriptions and comments if possible, as edits spam the mailing
list and clutter Jira's "All" display, which is otherwise very useful.  Instead, preview descriptions
and comments using the preview button (on the right) before posting them.  Keep descriptions
brief and save more elaborate proposals for comments, since descriptions are included in Jira's
automatically sent messages.  If you change your mind, note this in a new comment, rather
than editing an older comment.  The issue should preserve this history of the discussion.
- 
- == Stay involved ==
- 
- Contributors should join the developer's mailing list <<MailTo(dev AT SPAMFREE hbase
DOT apache DOT org)>>, the user's mailing list <<MailTo(user AT SPAMFREE hbase
DOT apache DOT org)>> and the commit's mailing list <<MailTo(commits AT SPAMFREE
hbase DOT apache DOT org)>>.
- 
- == See Also ==
- 
-  * [[http://www.apache.org/dev/contributors.html|Apache contributor documentation]]
-  * [[http://www.apache.org/foundation/voting.html|Apache voting documentation]]
- 

Mime
View raw message