HBASE-20410 update protoc to 3.5.1-1 for rhel6
[hbase.git] / src / main / asciidoc / _chapters / developer.adoc
1 ////
2 /**
3  *
4  * Licensed to the Apache Software Foundation (ASF) under one
5  * or more contributor license agreements.  See the NOTICE file
6  * distributed with this work for additional information
7  * regarding copyright ownership.  The ASF licenses this file
8  * to you under the Apache License, Version 2.0 (the
9  * "License"); you may not use this file except in compliance
10  * with the License.  You may obtain a copy of the License at
11  *
12  *     http://www.apache.org/licenses/LICENSE-2.0
13  *
14  * Unless required by applicable law or agreed to in writing, software
15  * distributed under the License is distributed on an "AS IS" BASIS,
16  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
17  * See the License for the specific language governing permissions and
18  * limitations under the License.
19  */
20 ////
21
22 [[developer]]
23 = Building and Developing Apache HBase
24 :doctype: book
25 :numbered:
26 :toc: left
27 :icons: font
28 :experimental:
29
30 This chapter contains information and guidelines for building and releasing HBase code and documentation.
31 Being familiar with these guidelines will help the HBase committers to use your contributions more easily.
32
33 [[getting.involved]]
34 == Getting Involved
35
36 Apache HBase gets better only when people contribute! If you are looking to contribute to Apache HBase, look for link:https://issues.apache.org/jira/issues/?jql=project%20%3D%20HBASE%20AND%20labels%20in%20(beginner)%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)[issues in JIRA tagged with the label 'beginner'].
37 These are issues HBase contributors have deemed worthy but not of immediate priority and a good way to ramp on HBase internals.
38 See link:http://search-hadoop.com/m/DHED43re96[What label
39                 is used for issues that are good on ramps for new contributors?] from the dev mailing list for background.
40
41 Before you get started submitting code to HBase, please refer to <<developing,developing>>.
42
43 As Apache HBase is an Apache Software Foundation project, see <<asf,asf>>            for more information about how the ASF functions.
44
45 [[mailing.list]]
46 === Mailing Lists
47
48 Sign up for the dev-list and the user-list.
49 See the link:https://hbase.apache.org/mail-lists.html[mailing lists] page.
50 Posing questions - and helping to answer other people's questions - is encouraged! There are varying levels of experience on both lists so patience and politeness are encouraged (and please stay on topic.)
51
52 [[slack]]
53 === Slack
54 The Apache HBase project has its own link: http://apache-hbase.slack.com[Slack Channel] for real-time questions
55 and discussion. Mail dev@hbase.apache.org to request an invite.
56
57 [[irc]]
58 === Internet Relay Chat (IRC)
59
60 (NOTE: Our IRC channel seems to have been deprecated in favor of the above Slack channel)
61
62 For real-time questions and discussions, use the `#hbase` IRC channel on the link:https://freenode.net/[FreeNode] IRC network.
63 FreeNode offers a web-based client, but most people prefer a native client, and several clients are available for each operating system.
64
65 === Jira
66
67 Check for existing issues in link:https://issues.apache.org/jira/projects/HBASE/issues[Jira].
68 If it's either a new feature request, enhancement, or a bug, file a ticket.
69
70 We track multiple types of work in JIRA:
71
72 - Bug: Something is broken in HBase itself.
73 - Test: A test is needed, or a test is broken.
74 - New feature: You have an idea for new functionality. It's often best to bring
75   these up on the mailing lists first, and then write up a design specification
76   that you add to the feature request JIRA.
77 - Improvement: A feature exists, but could be tweaked or augmented. It's often
78   best to bring these up on the mailing lists first and have a discussion, then
79   summarize or link to the discussion if others seem interested in the
80   improvement.
81 - Wish: This is like a new feature, but for something you may not have the
82   background to flesh out yourself.
83
84 Bugs and tests have the highest priority and should be actionable.
85
86 ==== Guidelines for reporting effective issues
87
88 - *Search for duplicates*: Your issue may have already been reported. Have a
89   look, realizing that someone else might have worded the summary differently.
90 +
91 Also search the mailing lists, which may have information about your problem
92 and how to work around it. Don't file an issue for something that has already
93 been discussed and resolved on a mailing list, unless you strongly disagree
94 with the resolution *and* are willing to help take the issue forward.
95
96 * *Discuss in public*: Use the mailing lists to discuss what you've discovered
97   and see if there is something you've missed. Avoid using back channels, so
98   that you benefit from the experience and expertise of the project as a whole.
99
100 * *Don't file on behalf of others*: You might not have all the context, and you
101   don't have as much motivation to see it through as the person who is actually
102   experiencing the bug. It's more helpful in the long term to encourage others
103   to file their own issues. Point them to this material and offer to help out
104   the first time or two.
105
106 * *Write a good summary*: A good summary includes information about the problem,
107   the impact on the user or developer, and the area of the code.
108 ** Good: `Address new license dependencies from hadoop3-alpha4`
109 ** Room for improvement: `Canary is broken`
110 +
111 If you write a bad title, someone else will rewrite it for you. This is time
112 they could have spent working on the issue instead.
113
114 * *Give context in the description*: It can be good to think of this in multiple
115   parts:
116 ** What happens or doesn't happen?
117 ** How does it impact you?
118 ** How can someone else reproduce it?
119 ** What would "fixed" look like?
120 +
121 You don't need to know the answers for all of these, but give as much
122 information as you can. If you can provide technical information, such as a
123 Git commit SHA that you think might have caused the issue or a build failure
124 on builds.apache.org where you think the issue first showed up, share that
125 info.
126
127 * *Fill in all relevant fields*: These fields help us filter, categorize, and
128   find things.
129
130 * *One bug, one issue, one patch*: To help with back-porting, don't split issues
131   or fixes among multiple bugs.
132
133 * *Add value if you can*: Filing issues is great, even if you don't know how to
134   fix them. But providing as much information as possible, being willing to
135   triage and answer questions, and being willing to test potential fixes is even
136   better! We want to fix your issue as quickly as you want it to be fixed.
137
138 * *Don't be upset if we don't fix it*: Time and resources are finite. In some
139   cases, we may not be able to (or might choose not to) fix an issue, especially
140   if it is an edge case or there is a workaround. Even if it doesn't get fixed,
141   the JIRA is a public record of it, and will help others out if they run into
142   a similar issue in the future.
143
144 ==== Working on an issue
145
146 To check for existing issues which you can tackle as a beginner, search for link:https://issues.apache.org/jira/issues/?jql=project%20%3D%20HBASE%20AND%20labels%20in%20(beginner)%20AND%20status%20in%20(Open%2C%20%22In%20Progress%22%2C%20Reopened)[issues in JIRA tagged with the label 'beginner'].
147
148 .JIRA Priorites
149 * *Blocker*: Should only be used if the issue WILL cause data loss or cluster instability reliably.
150 * *Critical*: The issue described can cause data loss or cluster instability in some cases.
151 * *Major*: Important but not tragic issues, like updates to the client API that will add a lot of much-needed functionality or significant bugs that need to be fixed but that don't cause data loss.
152 * *Minor*: Useful enhancements and annoying but not damaging bugs.
153 * *Trivial*: Useful enhancements but generally cosmetic.
154
155 .Code Blocks in Jira Comments
156 ====
157 A commonly used macro in Jira is {code}. Everything inside the tags is preformatted, as in this example.
158
159 [source]
160 ----
161
162 {code}
163 code snippet
164 {code}
165 ----
166 ====
167
168 [[repos]]
169 == Apache HBase Repositories
170
171 There are two different repositories for Apache HBase: Subversion (SVN) and Git.
172 GIT is our repository of record for all but the Apache HBase website.
173 We used to be on SVN.
174 We migrated.
175 See link:https://issues.apache.org/jira/browse/INFRA-7768[Migrate Apache HBase SVN Repos to Git].
176 See link:https://hbase.apache.org/source-repository.html[Source Code
177                 Management] page for contributor and committer links or search for HBase on the link:https://git.apache.org/[Apache Git] page.
178
179 == IDEs
180
181 [[eclipse]]
182 === Eclipse
183
184 [[eclipse.code.formatting]]
185 ==== Code Formatting
186
187 Under the _dev-support/_ folder, you will find _hbase_eclipse_formatter.xml_.
188 We encourage you to have this formatter in place in eclipse when editing HBase code.
189
190 Go to `Preferences->Java->Code Style->Formatter->Import` to load the xml file.
191 Go to `Preferences->Java->Editor->Save Actions`, and make sure 'Format source code' and 'Format
192 edited lines' is selected.
193
194 In addition to the automatic formatting, make sure you follow the style guidelines explained in
195 <<common.patch.feedback,common.patch.feedback>>.
196
197 [[eclipse.git.plugin]]
198 ==== Eclipse Git Plugin
199
200 If you cloned the project via git, download and install the Git plugin (EGit). Attach to your local git repo (via the [label]#Git Repositories#                    window) and you'll be able to see file revision history, generate patches, etc.
201
202 [[eclipse.maven.setup]]
203 ==== HBase Project Setup in Eclipse using `m2eclipse`
204
205 The easiest way is to use the +m2eclipse+ plugin for Eclipse.
206 Eclipse Indigo or newer includes +m2eclipse+, or you can download it from http://www.eclipse.org/m2e/. It provides Maven integration for Eclipse, and even lets you use the direct Maven commands from within Eclipse to compile and test your project.
207
208 To import the project, click  and select the HBase root directory. `m2eclipse`                    locates all the hbase modules for you.
209
210 If you install +m2eclipse+ and import HBase in your workspace, do the following to fix your eclipse Build Path.
211
212 . Remove _target_ folder
213 . Add _target/generated-jamon_ and _target/generated-sources/java_ folders.
214 . Remove from your Build Path the exclusions on the _src/main/resources_ and _src/test/resources_ to avoid error message in the console, such as the following:
215 +
216 ----
217 Failed to execute goal
218 org.apache.maven.plugins:maven-antrun-plugin:1.6:run (default) on project hbase:
219 'An Ant BuildException has occurred: Replace: source file .../target/classes/hbase-default.xml
220 doesn't exist
221 ----
222 +
223 This will also reduce the eclipse build cycles and make your life easier when developing.
224
225
226 [[eclipse.commandline]]
227 ==== HBase Project Setup in Eclipse Using the Command Line
228
229 Instead of using `m2eclipse`, you can generate the Eclipse files from the command line.
230
231 . First, run the following command, which builds HBase.
232   You only need to do this once.
233 +
234 [source,bourne]
235 ----
236 mvn clean install -DskipTests
237 ----
238
239 . Close Eclipse, and execute the following command from the terminal, in your local HBase project directory, to generate new _.project_ and _.classpath_                            files.
240 +
241 [source,bourne]
242 ----
243 mvn eclipse:eclipse
244 ----
245
246 . Reopen Eclipse and import the _.project_ file in the HBase directory to a workspace.
247
248 [[eclipse.maven.class]]
249 ==== Maven Classpath Variable
250
251 The `$M2_REPO` classpath variable needs to be set up for the project.
252 This needs to be set to your local Maven repository, which is usually _~/.m2/repository_
253
254 If this classpath variable is not configured, you will see compile errors in Eclipse like this:
255
256 ----
257
258 Description     Resource        Path    Location        Type
259 The project cannot be built until build path errors are resolved        hbase           Unknown Java Problem
260 Unbound classpath variable: 'M2_REPO/asm/asm/3.1/asm-3.1.jar' in project 'hbase'        hbase           Build path      Build Path Problem
261 Unbound classpath variable: 'M2_REPO/com/google/guava/guava/r09/guava-r09.jar' in project 'hbase'       hbase           Build path      Build Path Problem
262 Unbound classpath variable: 'M2_REPO/com/google/protobuf/protobuf-java/2.3.0/protobuf-java-2.3.0.jar' in project 'hbase'        hbase           Build path      Build Path Problem Unbound classpath variable:
263 ----
264
265 [[eclipse.issues]]
266 ==== Eclipse Known Issues
267
268 Eclipse will currently complain about _Bytes.java_.
269 It is not possible to turn these errors off.
270
271 ----
272
273 Description     Resource        Path    Location        Type
274 Access restriction: The method arrayBaseOffset(Class) from the type Unsafe is not accessible due to restriction on required library /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Classes/classes.jar     Bytes.java      /hbase/src/main/java/org/apache/hadoop/hbase/util       line 1061       Java Problem
275 Access restriction: The method arrayIndexScale(Class) from the type Unsafe is not accessible due to restriction on required library /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Classes/classes.jar     Bytes.java      /hbase/src/main/java/org/apache/hadoop/hbase/util       line 1064       Java Problem
276 Access restriction: The method getLong(Object, long) from the type Unsafe is not accessible due to restriction on required library /System/Library/Java/JavaVirtualMachines/1.6.0.jdk/Contents/Classes/classes.jar      Bytes.java      /hbase/src/main/java/org/apache/hadoop/hbase/util       line 1111       Java Problem
277 ----
278
279 [[eclipse.more]]
280 ==== Eclipse - More Information
281
282 For additional information on setting up Eclipse for HBase development on Windows, see link:http://michaelmorello.blogspot.com/2011/09/hbase-subversion-eclipse-windows.html[Michael Morello's blog] on the topic.
283
284 === IntelliJ IDEA
285
286 You can set up IntelliJ IDEA for similar functionality as Eclipse.
287 Follow these steps.
288
289 . Select
290 . You do not need to select a profile.
291   Be sure [label]#Maven project
292   required# is selected, and click btn:[Next].
293 . Select the location for the JDK.
294
295 .Using the HBase Formatter in IntelliJ IDEA
296 Using the Eclipse Code Formatter plugin for IntelliJ IDEA, you can import the HBase code formatter described in <<eclipse.code.formatting,eclipse.code.formatting>>.
297
298 === Other IDEs
299
300 It would be useful to mirror the <<eclipse,eclipse>> set-up instructions for other IDEs.
301 If you would like to assist, please have a look at link:https://issues.apache.org/jira/browse/HBASE-11704[HBASE-11704].
302
303 [[build]]
304 == Building Apache HBase
305
306 [[build.basic]]
307 === Basic Compile
308
309 HBase is compiled using Maven.
310 You must use at least Maven 3.0.4.
311 To check your Maven version, run the command +mvn -version+.
312
313 .JDK Version Requirements
314 [NOTE]
315 ====
316 Starting with HBase 1.0 you must use Java 7 or later to build from source code.
317 See <<java,java>> for more complete information about supported JDK versions.
318 ====
319
320 [[maven.build.commands]]
321 ==== Maven Build Commands
322
323 All commands are executed from the local HBase project directory.
324
325 ===== Package
326
327 The simplest command to compile HBase from its java source code is to use the `package` target, which builds JARs with the compiled files.
328
329 [source,bourne]
330 ----
331 mvn package -DskipTests
332 ----
333
334 Or, to clean up before compiling:
335
336 [source,bourne]
337 ----
338 mvn clean package -DskipTests
339 ----
340
341 With Eclipse set up as explained above in <<eclipse,eclipse>>, you can also use the menu:Build[] command in Eclipse.
342 To create the full installable HBase package takes a little bit more work, so read on.
343
344 [[maven.build.commands.compile]]
345 ===== Compile
346
347 The `compile` target does not create the JARs with the compiled files.
348
349 [source,bourne]
350 ----
351 mvn compile
352 ----
353
354 [source,bourne]
355 ----
356 mvn clean compile
357 ----
358
359 ===== Install
360
361 To install the JARs in your _~/.m2/_ directory, use the `install` target.
362
363 [source,bourne]
364 ----
365 mvn install
366 ----
367
368 [source,bourne]
369 ----
370 mvn clean install
371 ----
372
373 [source,bourne]
374 ----
375 mvn clean install -DskipTests
376 ----
377
378 [[maven.build.commands.unitall]]
379 ==== Running all or individual Unit Tests
380
381 See the <<hbase.unittests.cmds,hbase.unittests.cmds>> section in <<hbase.unittests,hbase.unittests>>
382
383 [[maven.build.hadoop]]
384 ==== Building against various hadoop versions.
385
386 HBase supports building against Apache Hadoop versions: 2.y and 3.y (early release artifacts). By default we build against Hadoop 2.x.
387
388 To build against a specific release from the Hadoop 2.y line, set e.g. `-Dhadoop-two.version=2.6.3`.
389
390 [source,bourne]
391 ----
392 mvn -Dhadoop-two.version=2.6.3 ...
393 ----
394
395 To change the major release line of Hadoop we build against, add a hadoop.profile property when you invoke +mvn+:
396
397 [source,bourne]
398 ----
399 mvn -Dhadoop.profile=3.0 ...
400 ----
401
402 The above will build against whatever explicit hadoop 3.y version we have in our _pom.xml_ as our '3.0' version.
403 Tests may not all pass so you may need to pass `-DskipTests` unless you are inclined to fix the failing tests.
404
405 To pick a particular Hadoop 3.y release, you'd set hadoop-three.version property e.g. `-Dhadoop-three.version=3.0.0`.
406
407 [[build.protobuf]]
408 ==== Build Protobuf
409
410 You may need to change the protobuf definitions that reside in the _hbase-protocol_ module or other modules.
411
412 Previous to hbase-2.0.0, protobuf definition files were sprinkled across all hbase modules but now all
413 to do with protobuf must reside in the hbase-protocol module; we are trying to contain our protobuf
414 use so we can freely change versions without upsetting any downstream project use of protobuf.
415
416 The protobuf files are located in _hbase-protocol/src/main/protobuf_.
417 For the change to be effective, you will need to regenerate the classes.
418
419 [source,bourne]
420 ----
421 mvn package -pl hbase-protocol -am
422 ----
423
424 Similarly, protobuf definitions for internal use are located in the _hbase-protocol-shaded_ module.
425
426 [source,bourne]
427 ----
428 mvn package -pl hbase-protocol-shaded -am
429 ----
430
431 Typically, protobuf code generation is done using the native `protoc` binary. In our build we use a maven plugin for
432 convenience; however, the plugin may not be able to retrieve appropriate binaries for all platforms. If you find yourself
433 on a platform where protoc fails, you will have to compile protoc from source, and run it independent of our maven build.
434 You can disable the inline code generation by specifying `-Dprotoc.skip` in your maven arguments, allowing your build to proceed further.
435
436 [NOTE]
437 If you need to manually generate your protobuf files, you should not use `clean` in subsequent maven calls, as that will delete the newly generated files.
438
439 Read the _hbase-protocol/README.txt_ for more details
440
441 [[build.thrift]]
442 ==== Build Thrift
443
444 You may need to change the thrift definitions that reside in the _hbase-thrift_ module or other modules.
445
446 The thrift files are located in _hbase-thrift/src/main/resources_.
447 For the change to be effective, you will need to regenerate the classes.
448 You can use maven profile  `compile-thrift` to do this.
449
450 [source,bourne]
451 ----
452 mvn compile -Pcompile-thrift
453 ----
454
455 You may also want to define `thrift.path` for the thrift binary, using the following command:
456
457 [source,bourne]
458 ----
459
460                   mvn compile -Pcompile-thrift -Dthrift.path=/opt/local/bin/thrift
461 ----
462
463 ==== Build a Tarball
464
465 You can build a tarball without going through the release process described in <<releasing,releasing>>, by running the following command:
466
467 ----
468 mvn -DskipTests clean install && mvn -DskipTests package assembly:single
469 ----
470
471 The distribution tarball is built in _hbase-assembly/target/hbase-<version>-bin.tar.gz_.
472
473 You can install or deploy the tarball by having the assembly:single goal before install or deploy in the maven command:
474
475 ----
476 mvn -DskipTests package assembly:single install
477 ----
478 ----
479 mvn -DskipTests package assembly:single deploy
480 ----
481
482
483 [[build.gotchas]]
484 ==== Build Gotchas
485
486 If you see `Unable to find resource 'VM_global_library.vm'`, ignore it.
487 It's not an error.
488 It is link:https://issues.apache.org/jira/browse/MSITE-286[officially ugly] though.
489
490 [[releasing]]
491 == Releasing Apache HBase
492
493 .Building against HBase 1.x
494 [NOTE]
495 ====
496 HBase 1.x requires Java 7 to build.
497 See <<java,java>> for Java requirements per HBase release.
498 ====
499
500 [[maven.settings.xml]]
501 .Example _~/.m2/settings.xml_ File
502 ====
503 Publishing to maven requires you sign the artifacts you want to upload.
504 For the build to sign them for you, you a properly configured _settings.xml_ in your local repository under _.m2_, such as the following.
505
506 [source,xml]
507 ----
508 <settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
509   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
510   xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
511                       http://maven.apache.org/xsd/settings-1.0.0.xsd">
512   <servers>
513     <!- To publish a snapshot of some part of Maven -->
514     <server>
515       <id>apache.snapshots.https</id>
516       <username>YOUR_APACHE_ID
517       </username>
518       <password>YOUR_APACHE_PASSWORD
519       </password>
520     </server>
521     <!-- To publish a website using Maven -->
522     <!-- To stage a release of some part of Maven -->
523     <server>
524       <id>apache.releases.https</id>
525       <username>YOUR_APACHE_ID
526       </username>
527       <password>YOUR_APACHE_PASSWORD
528       </password>
529     </server>
530   </servers>
531   <profiles>
532     <profile>
533       <id>apache-release</id>
534       <properties>
535     <gpg.keyname>YOUR_KEYNAME</gpg.keyname>
536     <!--Keyname is something like this ... 00A5F21E... do gpg --list-keys to find it-->
537     <gpg.passphrase>YOUR_KEY_PASSWORD
538     </gpg.passphrase>
539       </properties>
540     </profile>
541   </profiles>
542 </settings>
543 ----
544 ====
545
546 [[maven.release]]
547 === Making a Release Candidate
548 Only committers may make releases of hbase artifacts.
549
550 .Before You Begin
551 Make sure your environment is properly set up. Maven and Git are the main tooling
552 used in the below. You'll need a properly configured _settings.xml_ file in your
553 local _~/.m2_ maven repository with logins for apache repos (See <<maven.settings.xml>>).
554 You will also need to have a published signing key. Browse the Hadoop
555 link:http://wiki.apache.org/hadoop/HowToRelease[How To Release] wiki page on
556 how to release. It is a model for most of the instructions below. It often has more
557 detail on particular steps, for example, on adding your code signing key to the
558 project KEYS file up in Apache or on how to update JIRA in preparation for release.
559
560 Before you make a release candidate, do a practice run by deploying a SNAPSHOT.
561 Check to be sure recent builds have been passing for the branch from where you
562 are going to take your release. You should also have tried recent branch tips
563 out on a cluster under load, perhaps by running the `hbase-it` integration test
564 suite for a few hours to 'burn in' the near-candidate bits.
565
566
567 .Specifying the Heap Space for Maven
568 [NOTE]
569 ====
570 You may run into OutOfMemoryErrors building, particularly building the site and
571 documentation. Up the heap for Maven by setting the `MAVEN_OPTS` variable.
572 You can prefix the variable to the Maven command, as in the following example:
573
574 ----
575 MAVEN_OPTS="-Xmx4g -XX:MaxPermSize=256m" mvn package
576 ----
577
578 You could also set this in an environment variable or alias in your shell.
579 ====
580
581
582 [NOTE]
583 ====
584 The script _dev-support/make_rc.sh_ automates many of the below steps.
585 It will checkout a tag, clean the checkout, build src and bin tarballs,
586 and deploy the built jars to repository.apache.org.
587 It does NOT do the modification of the _CHANGES.txt_ for the release,
588 the checking of the produced artifacts to ensure they are 'good' --
589 e.g. extracting the produced tarballs, verifying that they
590 look right, then starting HBase and checking that everything is running
591 correctly -- or the signing and pushing of the tarballs to
592 link:https://people.apache.org[people.apache.org].
593 Take a look. Modify/improve as you see fit.
594 ====
595
596 .Procedure: Release Procedure
597 . Update the _CHANGES.txt_ file and the POM files.
598 +
599 Update _CHANGES.txt_ with the changes since the last release.
600 Make sure the URL to the JIRA points to the proper location which lists fixes for this release.
601 Adjust the version in all the POM files appropriately.
602 If you are making a release candidate, you must remove the `-SNAPSHOT` label from all versions
603 in all pom.xml files.
604 If you are running this receipe to publish a snapshot, you must keep the `-SNAPSHOT` suffix on the hbase version.
605 The link:http://www.mojohaus.org/versions-maven-plugin/[Versions Maven Plugin] can be of use here.
606 To set a version in all the many poms of the hbase multi-module project, use a command like the following:
607 +
608 [source,bourne]
609 ----
610 $ mvn clean org.codehaus.mojo:versions-maven-plugin:2.5:set -DnewVersion=2.1.0-SNAPSHOT\1a
611 ----
612 +
613 Make sure all versions in poms are changed! Checkin the _CHANGES.txt_ and any maven version changes.
614
615 . Update the documentation.
616 +
617 Update the documentation under _src/main/asciidoc_.
618 This usually involves copying the latest from master branch and making version-particular
619 adjustments to suit this release candidate version.
620
621 . Clean the checkout dir
622 +
623 [source,bourne]
624 ----
625
626 $ mvn clean
627 $ git clean -f -x -d
628 ----
629
630
631 . Run Apache-Rat
632 Check licenses are good
633 +
634 [source,bourne]
635 ----
636
637 $ mvn apache-rat
638 ----
639 +
640 If the above fails, check the rat log.
641
642 +
643 [source,bourne]
644 ----
645 $ grep 'Rat check' patchprocess/mvn_apache_rat.log
646 ----
647 +
648
649 . Create a release tag.
650 Presuming you have run basic tests, the rat check, passes and all is
651 looking good, now is the time to tag the release candidate (You
652 always remove the tag if you need to redo). To tag, do
653 what follows substituting in the version appropriate to your build.
654 All tags should be signed tags; i.e. pass the _-s_ option (See
655 link:http://https://git-scm.com/book/id/v2/Git-Tools-Signing-Your-Work[Signing Your Work]
656 for how to set up your git environment for signing).
657
658 +
659 [source,bourne]
660 ----
661
662 $ git tag -s 2.0.0-alpha4-RC0 -m "Tagging the 2.0.0-alpha4 first Releae Candidate (Candidates start at zero)"
663 ----
664
665 Or, if you are making a release, tags should have a _rel/_ prefix to ensure
666 they are preserved in the Apache repo as in:
667
668 [source,bourne]
669 ----
670 +$ git tag -s rel/2.0.0-alpha4 -m "Tagging the 2.0.0-alpha4 Release"
671 ----
672
673 Push the (specific) tag (only) so others have access.
674 +
675 [source,bourne]
676 ----
677
678 $ git push origin 2.0.0-alpha4-RC0
679 ----
680 +
681 For how to delete tags, see
682 link:http://www.manikrathee.com/how-to-delete-a-tag-in-git.html[How to Delete a Tag]. Covers
683 deleting tags that have not yet been pushed to the remote Apache
684 repo as well as delete of tags pushed to Apache.
685
686
687 . Build the source tarball.
688 +
689 Now, build the source tarball. Lets presume we are building the source
690 tarball for the tag _2.0.0-alpha4-RC0_ into _/tmp/hbase-2.0.0-alpha4-RC0/_
691 (This step requires that the mvn and git clean steps described above have just been done).
692 +
693 [source,bourne]
694 ----
695 $ git archive --format=tar.gz --output="/tmp/hbase-2.0.0-alpha4-RC0/hbase-2.0.0-alpha4-src.tar.gz" --prefix="hbase-2.0.0-alpha4/" $git_tag
696 ----
697
698 Above we generate the hbase-2.0.0-alpha4-src.tar.gz tarball into the
699 _/tmp/hbase-2.0.0-alpha4-RC0_ build output directory (We don't want the _RC0_ in the name or prefix.
700 These bits are currently a release candidate but if the VOTE passes, they will become the release so we do not taint
701 the artifact names with _RCX_).
702
703 . Build the binary tarball.
704 Next, build the binary tarball. Add the `-Prelease` profile when building.
705 It runs the license apache-rat check among other rules that help ensure
706 all is wholesome. Do it in two steps.
707
708 First install into the local repository
709
710 [source,bourne]
711 ----
712
713 $ mvn clean install -DskipTests -Prelease
714 ----
715
716 Next, generate documentation and assemble the tarball. Be warned,
717 this next step can take a good while, a couple of hours generating site
718 documentation.
719
720 [source,bourne]
721 ----
722
723 $ mvn install -DskipTests site assembly:single -Prelease
724 ----
725
726 +
727 Otherwise, the build complains that hbase modules are not in the maven repository
728 when you try to do it all in one step, especially on a fresh repository.
729 It seems that you need the install goal in both steps.
730 +
731 Extract the generated tarball -- you'll find it under
732 _hbase-assembly/target_ and check it out.
733 Look at the documentation, see if it runs, etc.
734 If good, copy the tarball beside the source tarball in the
735 build output directory.
736
737
738 . Deploy to the Maven Repository.
739 +
740 Next, deploy HBase to the Apache Maven repository. Add the
741 apache-release` profile when running the `mvn deploy` command.
742 This profile comes from the Apache parent pom referenced by our pom files.
743 It does signing of your artifacts published to Maven, as long as the
744 _settings.xml_ is configured correctly, as described in <<maven.settings.xml>>.
745 This step depends on the local repository having been populate
746 by the just-previous bin tarball build.
747
748 +
749 [source,bourne]
750 ----
751
752 $ mvn deploy -DskipTests -Papache-release -Prelease
753 ----
754 +
755 This command copies all artifacts up to a temporary staging Apache mvn repository in an 'open' state.
756 More work needs to be done on these maven artifacts to make them generally available.
757 +
758 We do not release HBase tarball to the Apache Maven repository. To avoid deploying the tarball, do not
759 include the `assembly:single` goal in your `mvn deploy` command. Check the deployed artifacts as described in the next section.
760
761 .make_rc.sh
762 [NOTE]
763 ====
764 If you run the _dev-support/make_rc.sh_ script, this is as far as it takes you.
765 To finish the release, take up the script from here on out.
766 ====
767
768 . Make the Release Candidate available.
769 +
770 The artifacts are in the maven repository in the staging area in the 'open' state.
771 While in this 'open' state you can check out what you've published to make sure all is good.
772 To do this, log in to Apache's Nexus at link:https://repository.apache.org[repository.apache.org] using your Apache ID.
773 Find your artifacts in the staging repository. Click on 'Staging Repositories' and look for a new one ending in "hbase" with a status of 'Open', select it.
774 Use the tree view to expand the list of repository contents and inspect if the artifacts you expect are present. Check the POMs.
775 As long as the staging repo is open you can re-upload if something is missing or built incorrectly.
776 +
777 If something is seriously wrong and you would like to back out the upload, you can use the 'Drop' button to drop and delete the staging repository.
778 Sometimes the upload fails in the middle. This is another reason you might have to 'Drop' the upload from the staging repository.
779 +
780 If it checks out, close the repo using the 'Close' button. The repository must be closed before a public URL to it becomes available. It may take a few minutes for the repository to close. Once complete you'll see a public URL to the repository in the Nexus UI. You may also receive an email with the URL. Provide the URL to the temporary staging repository in the email that announces the release candidate.
781 (Folks will need to add this repo URL to their local poms or to their local _settings.xml_ file to pull the published release candidate artifacts.)
782 +
783 When the release vote concludes successfully, return here and click the 'Release' button to release the artifacts to central. The release process will automatically drop and delete the staging repository.
784 +
785 .hbase-downstreamer
786 [NOTE]
787 ====
788 See the link:https://github.com/saintstack/hbase-downstreamer[hbase-downstreamer] test for a simple example of a project that is downstream of HBase an depends on it.
789 Check it out and run its simple test to make sure maven artifacts are properly deployed to the maven repository.
790 Be sure to edit the pom to point to the proper staging repository.
791 Make sure you are pulling from the repository when tests run and that you are not getting from your local repository, by either passing the `-U` flag or deleting your local repo content and check maven is pulling from remote out of the staging repository.
792 ====
793
794 See link:https://www.apache.org/dev/publishing-maven-artifacts.html[Publishing Maven Artifacts] for some pointers on this maven staging process.
795 +
796 If the HBase version ends in `-SNAPSHOT`, the artifacts go elsewhere.
797 They are put into the Apache snapshots repository directly and are immediately available.
798 Making a SNAPSHOT release, this is what you want to happen.
799 +
800 At this stage, you have two tarballs in your 'build output directory' and a set of artifacts
801 in a staging area of the maven repository, in the 'closed' state.
802 Next sign, fingerprint and then 'stage' your release candiate build output directory via svnpubsub by committing
803 your directory to link:https://dist.apache.org/repos/dist/dev/hbase/[The dev distribution directory]
804 (See comments on link:https://issues.apache.org/jira/browse/HBASE-10554[HBASE-10554 Please delete old releases from mirroring system]
805 but in essence it is an svn checkout of link:https://dist.apache.org/repos/dist/dev/hbase[dev/hbase] -- releases are at
806 link:https://dist.apache.org/repos/dist/release/hbase[release/hbase]). In the _version directory_ run the following commands:
807
808 [source,bourne]
809 ----
810
811 $ for i in *.tar.gz; do echo $i; gpg --print-md MD5 $i > $i.md5 ; done
812 $ for i in *.tar.gz; do echo $i; gpg --print-md SHA512 $i > $i.sha ; done
813 $ for i in *.tar.gz; do echo $i; gpg --armor --output $i.asc --detach-sig $i  ; done
814 $ cd ..
815 # Presuming our 'build output directory' is named 0.96.0RC0, copy it to the svn checkout of the dist dev dir
816 # in this case named hbase.dist.dev.svn
817 $ cd /Users/stack/checkouts/hbase.dist.dev.svn
818 $ svn info
819 Path: .
820 Working Copy Root Path: /Users/stack/checkouts/hbase.dist.dev.svn
821 URL: https://dist.apache.org/repos/dist/dev/hbase
822 Repository Root: https://dist.apache.org/repos/dist
823 Repository UUID: 0d268c88-bc11-4956-87df-91683dc98e59
824 Revision: 15087
825 Node Kind: directory
826 Schedule: normal
827 Last Changed Author: ndimiduk
828 Last Changed Rev: 15045
829 Last Changed Date: 2016-08-28 11:13:36 -0700 (Sun, 28 Aug 2016)
830 $ mv 0.96.0RC0 /Users/stack/checkouts/hbase.dist.dev.svn
831 $ svn add 0.96.0RC0
832 $ svn commit ...
833 ----
834 +
835 Ensure it actually gets published by checking link:https://dist.apache.org/repos/dist/dev/hbase/[https://dist.apache.org/repos/dist/dev/hbase/].
836
837 Announce the release candidate on the mailing list and call a vote.
838
839
840 [[maven.snapshot]]
841 === Publishing a SNAPSHOT to maven
842
843 Make sure your _settings.xml_ is set up properly (see <<maven.settings.xml>>).
844 Make sure the hbase version includes `-SNAPSHOT` as a suffix.
845 Following is an example of publishing SNAPSHOTS of a release that had an hbase version of 0.96.0 in its poms.
846
847 [source,bourne]
848 ----
849
850  $ mvn clean install -DskipTests  javadoc:aggregate site assembly:single -Prelease
851  $ mvn -DskipTests  deploy -Papache-release
852 ----
853
854 The _make_rc.sh_ script mentioned above (see <<maven.release,maven.release>>) can help you publish `SNAPSHOTS`.
855 Make sure your `hbase.version` has a `-SNAPSHOT`                suffix before running the script.
856 It will put a snapshot up into the apache snapshot repository for you.
857
858 [[hbase.rc.voting]]
859 == Voting on Release Candidates
860
861 Everyone is encouraged to try and vote on HBase release candidates.
862 Only the votes of PMC members are binding.
863 PMC members, please read this WIP doc on policy voting for a release candidate, link:https://github.com/rectang/asfrelease/blob/master/release.md[Release
864                 Policy]. [quote]_Before casting +1 binding votes, individuals are required to
865                 download the signed source code package onto their own hardware, compile it as
866                 provided, and test the resulting executable on their own platform, along with also
867                 validating cryptographic signatures and verifying that the package meets the
868                 requirements of the ASF policy on releases._ Regards the latter, run +mvn apache-rat:check+ to verify all files are suitably licensed.
869 See link:http://search-hadoop.com/m/DHED4dhFaU[HBase, mail # dev - On
870                 recent discussion clarifying ASF release policy].
871 for how we arrived at this process.
872
873 [[documentation]]
874 == Generating the HBase Reference Guide
875
876 The manual is marked up using Asciidoc.
877 We then use the link:http://asciidoctor.org/docs/asciidoctor-maven-plugin/[Asciidoctor maven plugin] to transform the markup to html.
878 This plugin is run when you specify the +site+ goal as in when you run +mvn site+.
879 See <<appendix_contributing_to_documentation,appendix contributing to documentation>> for more information on building the documentation.
880
881 [[hbase.org]]
882 == Updating link:https://hbase.apache.org[hbase.apache.org]
883
884 [[hbase.org.site.contributing]]
885 === Contributing to hbase.apache.org
886
887 See <<appendix_contributing_to_documentation,appendix contributing to documentation>> for more information on contributing to the documentation or website.
888
889 [[hbase.org.site.publishing]]
890 === Publishing link:https://hbase.apache.org[hbase.apache.org]
891
892 See <<website_publish>> for instructions on publishing the website and documentation.
893
894 [[hbase.tests]]
895 == Tests
896
897 Developers, at a minimum, should familiarize themselves with the unit test detail; unit tests in HBase have a character not usually seen in other projects.
898
899 This information is about unit tests for HBase itself.
900 For developing unit tests for your HBase applications, see <<unit.tests,unit.tests>>.
901
902 [[hbase.moduletests]]
903 === Apache HBase Modules
904
905 As of 0.96, Apache HBase is split into multiple modules.
906 This creates "interesting" rules for how and where tests are written.
907 If you are writing code for `hbase-server`, see <<hbase.unittests,hbase.unittests>> for how to write your tests.
908 These tests can spin up a minicluster and will need to be categorized.
909 For any other module, for example `hbase-common`, the tests must be strict unit tests and just test the class under test - no use of the HBaseTestingUtility or minicluster is allowed (or even possible given the dependency tree).
910
911 [[hbase.moduletest.shell]]
912 ==== Testing the HBase Shell
913
914 The HBase shell and its tests are predominantly written in jruby.
915
916 In order to make these tests run as a part of the standard build, there are a few JUnit test classes that take care of loading the jruby implemented tests and running them.
917 The tests were split into separate classes to accomodate class level timeouts (see <<hbase.unittests>> for specifics).
918 You can run all of these tests from the top level with:
919
920 [source,bourne]
921 ----
922       mvn clean test -Dtest=Test*Shell
923 ----
924
925 If you have previously done a `mvn install`, then you can instruct maven to run only the tests in the hbase-shell module with:
926
927 [source,bourne]
928 ----
929       mvn clean test -pl hbase-shell
930 ----
931
932 Alternatively, you may limit the shell tests that run using the system variable `shell.test`.
933 This value should specify the ruby literal equivalent of a particular test case by name.
934 For example, the tests that cover the shell commands for altering tables are contained in the test case `AdminAlterTableTest`        and you can run them with:
935
936 [source,bourne]
937 ----
938       mvn clean test -pl hbase-shell -Dshell.test=/AdminAlterTableTest/
939 ----
940
941 You may also use a link:http://docs.ruby-doc.com/docs/ProgrammingRuby/html/language.html#UJ[Ruby Regular Expression
942       literal] (in the `/pattern/` style) to select a set of test cases.
943 You can run all of the HBase admin related tests, including both the normal administration and the security administration, with the command:
944
945 [source,bourne]
946 ----
947
948       mvn clean test -pl hbase-shell -Dshell.test=/.*Admin.*Test/
949 ----
950
951 In the event of a test failure, you can see details by examining the XML version of the surefire report results
952
953 [source,bourne]
954 ----
955       vim hbase-shell/target/surefire-reports/TEST-org.apache.hadoop.hbase.client.TestShell.xml
956 ----
957
958 [[hbase.moduletest.run]]
959 ==== Running Tests in other Modules
960
961 If the module you are developing in has no other dependencies on other HBase modules, then you can cd into that module and just run:
962
963 [source,bourne]
964 ----
965 mvn test
966 ----
967
968 which will just run the tests IN THAT MODULE.
969 If there are other dependencies on other modules, then you will have run the command from the ROOT HBASE DIRECTORY.
970 This will run the tests in the other modules, unless you specify to skip the tests in that module.
971 For instance, to skip the tests in the hbase-server module, you would run:
972
973 [source,bourne]
974 ----
975 mvn clean test -PskipServerTests
976 ----
977
978 from the top level directory to run all the tests in modules other than hbase-server.
979 Note that you can specify to skip tests in multiple modules as well as just for a single module.
980 For example, to skip the tests in `hbase-server` and `hbase-common`, you would run:
981
982 [source,bourne]
983 ----
984 mvn clean test -PskipServerTests -PskipCommonTests
985 ----
986
987 Also, keep in mind that if you are running tests in the `hbase-server` module you will need to apply the maven profiles discussed in <<hbase.unittests.cmds,hbase.unittests.cmds>> to get the tests to run properly.
988
989 [[hbase.unittests]]
990 === Unit Tests
991
992 Apache HBase unit tests must carry a Category annotation and
993 as of `hbase-2.0.0`, must be stamped with the HBase `ClassRule`.
994 Here is an example of what a Test Class looks like with a 
995 Category and ClassRule included:
996
997 [source,java]
998 ----
999 ...
1000 @Category(SmallTests.class)
1001 public class TestHRegionInfo {
1002   @ClassRule
1003   public static final HBaseClassTestRule CLASS_RULE =
1004       HBaseClassTestRule.forClass(TestHRegionInfo.class);
1005
1006   @Test
1007   public void testCreateHRegionInfoName() throws Exception {
1008     // ...
1009   }
1010 }
1011 ----
1012 Here the Test Class is `TestHRegionInfo`. The `CLASS_RULE` has
1013 the same form in every test class only the `.class` you pass
1014 is that of the local test; i.e. in the TestTimeout Test Class, you'd
1015 pass `TestTimeout.class` to the `CLASS_RULE` instead of the
1016 `TestHRegionInfo.class` we have above. The `CLASS_RULE`
1017 is where we'll enforce timeouts (currently set at a hard-limit of
1018 thirteen! minutes for all tests -- 780 seconds) and other cross-unit test facility.
1019 The test is in the `SmallTest` Category.
1020
1021 Categories can be arbitrary and provided as a list but each test MUST
1022 carry one from the following list of sizings: `small`, `medium`, `large`, and
1023 `integration`. The test sizing is designated using the JUnit
1024 link:https://github.com/junit-team/junit4/wiki/Categories[categories]: `SmallTests`, `MediumTests`, `LargeTests`, `IntegrationTests`.
1025 JUnit Categories are denoted using java annotations (a special unit test looks
1026 for the presence of the @Category annotation in all unit tess and will fail if it
1027 finds a test suite missing a sizing marking).
1028
1029 The first three categories, `small`, `medium`, and `large`, are for test cases which run when you
1030 type `$ mvn test`.
1031 In other words, these three categorizations are for HBase unit tests.
1032 The `integration` category is not for unit tests, but for integration tests.
1033 These are normally run when you invoke `$ mvn verify`.
1034 Integration tests are described in <<integration.tests,integration.tests>>.
1035
1036 Keep reading to figure which annotation of the set `small`, `medium`, and `large`
1037 to put on your new HBase test case.
1038
1039 .Categorizing Tests
1040 Small Tests (((SmallTests)))::
1041   _Small_ test cases are executed in a shared JVM and each test suite/test class should
1042    run in 15 seconds or less; i.e. a link:https://en.wikipedia.org/wiki/JUnit[junit test fixture], a java object made
1043    up of test methods, should finish in under 15 seconds, no matter how many or how few test methods
1044    it has. These test cases should not use a minicluster.
1045
1046 Medium Tests (((MediumTests)))::
1047   _Medium_ test cases are executed in separate JVM and individual test suites or test classes or in
1048   junit parlance, link:https://en.wikipedia.org/wiki/JUnit[test fixture], should run in 50 seconds
1049    or less. These test cases can use a mini cluster.
1050
1051 Large Tests (((LargeTests)))::
1052   _Large_ test cases are everything else. They are typically large-scale tests, regression tests
1053   for specific bugs, timeout tests, or performance tests. No large test suite can take longer than
1054   ten minutes. It will be killed as timed out. Cast your test as an Integration Test if it needs
1055   to run longer.
1056
1057 Integration Tests (((IntegrationTests)))::
1058   _Integration_ tests are system level tests.
1059   See <<integration.tests,integration.tests>> for more info.
1060   If you invoke `$ mvn test` on integration tests, there is no timeout for the test.
1061
1062 [[hbase.unittests.cmds]]
1063 === Running tests
1064
1065 [[hbase.unittests.cmds.test]]
1066 ==== Default: small and medium category tests
1067
1068 Running `mvn test` will execute all small tests in a single JVM (no fork) and then medium tests in a separate JVM for each test instance.
1069 Medium tests are NOT executed if there is an error in a small test. Large tests are NOT executed.
1070
1071 [[hbase.unittests.cmds.test.runalltests]]
1072 ==== Running all tests
1073
1074 Running `mvn test -P runAllTests` will execute small tests in a single JVM then medium and large tests in a separate JVM for each test.
1075 Medium and large tests are NOT executed if there is an error in a small test.
1076
1077 [[hbase.unittests.cmds.test.localtests.mytest]]
1078 ==== Running a single test or all tests in a package
1079
1080 To run an individual test, e.g. `MyTest`, rum `mvn test -Dtest=MyTest` You can also pass multiple, individual tests as a comma-delimited list:
1081 [source,bash]
1082 ----
1083 mvn test  -Dtest=MyTest1,MyTest2,MyTest3
1084 ----
1085 You can also pass a package, which will run all tests under the package:
1086 [source,bash]
1087 ----
1088 mvn test '-Dtest=org.apache.hadoop.hbase.client.*'
1089 ----
1090
1091 When `-Dtest` is specified, the `localTests` profile will be used.
1092 Each junit test is executed in a separate JVM (A fork per test class). There is no parallelization when tests are running in this mode.
1093 You will see a new message at the end of the -report: `"[INFO] Tests are skipped"`.
1094 It's harmless.
1095 However, you need to make sure the sum of `Tests run:` in the `Results:` section of test reports matching the number of tests you specified because no error will be reported when a non-existent test case is specified.
1096
1097 [[hbase.unittests.cmds.test.profiles]]
1098 ==== Other test invocation permutations
1099
1100 Running `mvn test -P runSmallTests` will execute "small" tests only, using a single JVM.
1101
1102 Running `mvn test -P runMediumTests` will execute "medium" tests only, launching a new JVM for each test-class.
1103
1104 Running `mvn test -P runLargeTests` will execute "large" tests only, launching a new JVM for each test-class.
1105
1106 For convenience, you can run `mvn test -P runDevTests` to execute both small and medium tests, using a single JVM.
1107
1108 [[hbase.unittests.test.faster]]
1109 ==== Running tests faster
1110
1111 By default, `$ mvn test -P runAllTests` runs 5 tests in parallel.
1112 It can be increased on a developer's machine.
1113 Allowing that you can have 2 tests in parallel per core, and you need about 2GB of memory per test (at the extreme), if you have an 8 core, 24GB box, you can have 16 tests in parallel.
1114 but the memory available limits it to 12 (24/2), To run all tests with 12 tests in parallel, do this: +mvn test -P runAllTests
1115                         -Dsurefire.secondPartForkCount=12+.
1116 If using a version earlier than  2.0, do: +mvn test -P runAllTests -Dsurefire.secondPartThreadCount=12
1117                     +.
1118 To increase the speed, you can as well use a ramdisk.
1119 You will need 2GB  of memory to run all tests.
1120 You will also need to delete the files between two  test run.
1121 The typical way to configure a ramdisk on Linux is:
1122
1123 ----
1124 $ sudo mkdir /ram2G
1125 sudo mount -t tmpfs -o size=2048M tmpfs /ram2G
1126 ----
1127
1128 You can then use it to run all HBase tests on 2.0 with the command:
1129
1130 ----
1131 mvn test
1132                         -P runAllTests -Dsurefire.secondPartForkCount=12
1133                         -Dtest.build.data.basedirectory=/ram2G
1134 ----
1135
1136 On earlier versions, use:
1137
1138 ----
1139 mvn test
1140                         -P runAllTests -Dsurefire.secondPartThreadCount=12
1141                         -Dtest.build.data.basedirectory=/ram2G
1142 ----
1143
1144 [[hbase.unittests.cmds.test.hbasetests]]
1145 ==== +hbasetests.sh+
1146
1147 It's also possible to use the script +hbasetests.sh+.
1148 This script runs the medium and large tests in parallel with two maven instances, and provides a single report.
1149 This script does not use the hbase version of surefire so no parallelization is being done other than the two maven instances the script sets up.
1150 It must be executed from the directory which contains the _pom.xml_.
1151
1152 For example running +./dev-support/hbasetests.sh+ will execute small and medium tests.
1153 Running +./dev-support/hbasetests.sh
1154                         runAllTests+ will execute all tests.
1155 Running +./dev-support/hbasetests.sh replayFailed+ will rerun the failed tests a second time, in a separate jvm and without parallelisation.
1156
1157 [[hbase.unittests.timeouts]]
1158 ==== Test Timeouts(((Test Timeouts)))
1159 The HBase unit test sizing Categorization timeouts are not strictly enforced.
1160
1161 Any test that runs longer than ten minutes will be timedout/killed.
1162
1163 As of hbase-2.0.0, we have purged all per-test-method timeouts: i.e.
1164 [source,java]
1165 ----
1166 ...
1167   @Test(timeout=30000)
1168   public void testCreateHRegionInfoName() throws Exception {
1169     // ...
1170   }
1171 ----
1172 They are discouraged and don't make much sense given we are timing
1173 base of how long the whole Test Fixture/Class/Suite takes and 
1174 that the variance in how long a test method takes varies wildly
1175 dependent upon context (loaded Apache Infrastructure versus
1176 developer machine with nothing else running on it).
1177
1178
1179
1180 [[hbase.unittests.resource.checker]]
1181 ==== Test Resource Checker(((Test ResourceChecker)))
1182
1183 A custom Maven SureFire plugin listener checks a number of resources before and after each HBase unit test runs and logs its findings at the end of the test output files which can be found in _target/surefire-reports_                    per Maven module (Tests write test reports named for the test class into this directory.
1184 Check the _*-out.txt_ files). The resources counted are the number of threads, the number of file descriptors, etc.
1185 If the number has increased, it adds a _LEAK?_ comment in the logs.
1186 As you can have an HBase instance running in the background, some threads can be deleted/created without any specific action in the test.
1187 However, if the test does not work as expected, or if the test should not impact these resources, it's worth checking these log lines [computeroutput]+...hbase.ResourceChecker(157): before...+                    and [computeroutput]+...hbase.ResourceChecker(157): after...+.
1188 For example:
1189
1190 ----
1191 2012-09-26 09:22:15,315 INFO [pool-1-thread-1]
1192 hbase.ResourceChecker(157): after:
1193 regionserver.TestColumnSeeking#testReseeking Thread=65 (was 65),
1194 OpenFileDescriptor=107 (was 107), MaxFileDescriptor=10240 (was 10240),
1195 ConnectionCount=1 (was 1)
1196 ----
1197
1198 [[hbase.tests.writing]]
1199 === Writing Tests
1200
1201 [[hbase.tests.rules]]
1202 ==== General rules
1203
1204 * As much as possible, tests should be written as category small tests.
1205 * All tests must be written to support parallel execution on the same machine, hence they should not use shared resources as fixed ports or fixed file names.
1206 * Tests should not overlog.
1207   More than 100 lines/second makes the logs complex to read and use i/o that are hence not available for the other tests.
1208 * Tests can be written with `HBaseTestingUtility`.
1209   This class offers helper functions to create a temp directory and do the cleanup, or to start a cluster.
1210
1211 [[hbase.tests.categories]]
1212 ==== Categories and execution time
1213
1214 * All tests must be categorized, if not they could be skipped.
1215 * All tests should be written to be as fast as possible.
1216 * See <<hbase.unittests,hbase.unittests> for test case categories and corresponding timeouts.
1217   This should ensure a good parallelization for people using it, and ease the analysis when the test fails.
1218
1219 [[hbase.tests.sleeps]]
1220 ==== Sleeps in tests
1221
1222 Whenever possible, tests should not use [method]+Thread.sleep+, but rather waiting for the real event they need.
1223 This is faster and clearer for the reader.
1224 Tests should not do a [method]+Thread.sleep+ without testing an ending condition.
1225 This allows understanding what the test is waiting for.
1226 Moreover, the test will work whatever the machine performance is.
1227 Sleep should be minimal to be as fast as possible.
1228 Waiting for a variable should be done in a 40ms sleep loop.
1229 Waiting for a socket operation should be done in a 200 ms sleep loop.
1230
1231 [[hbase.tests.cluster]]
1232 ==== Tests using a cluster
1233
1234 Tests using a HRegion do not have to start a cluster: A region can use the local file system.
1235 Start/stopping a cluster cost around 10 seconds.
1236 They should not be started per test method but per test class.
1237 Started cluster must be shutdown using [method]+HBaseTestingUtility#shutdownMiniCluster+, which cleans the directories.
1238 As most as possible, tests should use the default settings for the cluster.
1239 When they don't, they should document it.
1240 This will allow to share the cluster later.
1241
1242 [[hbase.tests.example.code]]
1243 ==== Tests Skeleton Code
1244
1245 Here is a test skeleton code with Categorization and a Category-based timeout rule to copy and paste and use as basis for test contribution.
1246 [source,java]
1247 ----
1248 /**
1249  * Describe what this testcase tests. Talk about resources initialized in @BeforeClass (before
1250  * any test is run) and before each test is run, etc.
1251  */
1252 // Specify the category as explained in <<hbase.unittests,hbase.unittests>>.
1253 @Category(SmallTests.class)
1254 public class TestExample {
1255   // Replace the TestExample.class in the below with the name of your test fixture class.
1256   private static final Log LOG = LogFactory.getLog(TestExample.class);
1257
1258   // Handy test rule that allows you subsequently get the name of the current method. See
1259   // down in 'testExampleFoo()' where we use it to log current test's name.
1260   @Rule public TestName testName = new TestName();
1261
1262   // The below rule does two things. It decides the timeout based on the category
1263   // (small/medium/large) of the testcase. This @Rule requires that the full testcase runs
1264   // within this timeout irrespective of individual test methods' times. The second
1265   // feature is we'll dump in the log when the test is done a count of threads still
1266   // running.
1267   @Rule public static TestRule timeout = CategoryBasedTimeout.builder().
1268     withTimeout(this.getClass()).withLookingForStuckThread(true).build();
1269
1270   @Before
1271   public void setUp() throws Exception {
1272   }
1273
1274   @After
1275   public void tearDown() throws Exception {
1276   }
1277
1278   @Test
1279   public void testExampleFoo() {
1280     LOG.info("Running test " + testName.getMethodName());
1281   }
1282 }
1283 ----
1284
1285 [[integration.tests]]
1286 === Integration Tests
1287
1288 HBase integration/system tests are tests that are beyond HBase unit tests.
1289 They are generally long-lasting, sizeable (the test can be asked to 1M rows or 1B rows), targetable (they can take configuration that will point them at the ready-made cluster they are to run against; integration tests do not include cluster start/stop code), and verifying success, integration tests rely on public APIs only; they do not attempt to examine server internals asserting success/fail.
1290 Integration tests are what you would run when you need to more elaborate proofing of a release candidate beyond what unit tests can do.
1291 They are not generally run on the Apache Continuous Integration build server, however, some sites opt to run integration tests as a part of their continuous testing on an actual cluster.
1292
1293 Integration tests currently live under the _src/test_                directory in the hbase-it submodule and will match the regex: _**/IntegrationTest*.java_.
1294 All integration tests are also annotated with `@Category(IntegrationTests.class)`.
1295
1296 Integration tests can be run in two modes: using a mini cluster, or against an actual distributed cluster.
1297 Maven failsafe is used to run the tests using the mini cluster.
1298 IntegrationTestsDriver class is used for executing the tests against a distributed cluster.
1299 Integration tests SHOULD NOT assume that they are running against a mini cluster, and SHOULD NOT use private API's to access cluster state.
1300 To interact with the distributed or mini cluster uniformly, `IntegrationTestingUtility`, and `HBaseCluster` classes, and public client API's can be used.
1301
1302 On a distributed cluster, integration tests that use ChaosMonkey or otherwise manipulate services thru cluster manager (e.g.
1303 restart regionservers) use SSH to do it.
1304 To run these, test process should be able to run commands on remote end, so ssh should be configured accordingly (for example, if HBase runs under hbase user in your cluster, you can set up passwordless ssh for that user and run the test also under it). To facilitate that, `hbase.it.clustermanager.ssh.user`, `hbase.it.clustermanager.ssh.opts` and `hbase.it.clustermanager.ssh.cmd` configuration settings can be used.
1305 "User" is the remote user that cluster manager should use to perform ssh commands.
1306 "Opts" contains additional options that are passed to SSH (for example, "-i /tmp/my-key"). Finally, if you have some custom environment setup, "cmd" is the override format for the entire tunnel (ssh) command.
1307 The default string is {`/usr/bin/ssh %1$s %2$s%3$s%4$s "%5$s"`} and is a good starting point.
1308 This is a standard Java format string with 5 arguments that is used to execute the remote command.
1309 The argument 1 (%1$s) is SSH options set the via opts setting or via environment variable, 2 is SSH user name, 3 is "@" if username is set or "" otherwise, 4 is the target host name, and 5 is the logical command to execute (that may include single quotes, so don't use them). For example, if you run the tests under non-hbase user and want to ssh as that user and change to hbase on remote machine, you can use:
1310 [source,bash]
1311 ----
1312 /usr/bin/ssh %1$s %2$s%3$s%4$s "su hbase - -c \"%5$s\""
1313 ----
1314 That way, to kill RS (for example) integration tests may run:
1315 [source,bash]
1316 ----
1317 {/usr/bin/ssh some-hostname "su hbase - -c \"ps aux | ... | kill ...\""}
1318 ----
1319 The command is logged in the test logs, so you can verify it is correct for your environment.
1320
1321 To disable the running of Integration Tests, pass the following profile on the command line `-PskipIntegrationTests`.
1322 For example,
1323 [source]
1324 ----
1325 $ mvn clean install test -Dtest=TestZooKeeper  -PskipIntegrationTests
1326 ----
1327
1328 [[maven.build.commands.integration.tests.mini]]
1329 ==== Running integration tests against mini cluster
1330
1331 HBase 0.92 added a `verify` maven target.
1332 Invoking it, for example by doing `mvn verify`, will run all the phases up to and including the verify phase via the maven link:https://maven.apache.org/plugins/maven-failsafe-plugin/[failsafe
1333                         plugin], running all the above mentioned HBase unit tests as well as tests that are in the HBase integration test group.
1334 After you have completed +mvn install -DskipTests+ You can run just the integration tests by invoking:
1335
1336 [source,bourne]
1337 ----
1338
1339 cd hbase-it
1340 mvn verify
1341 ----
1342
1343 If you just want to run the integration tests in top-level, you need to run two commands.
1344 First: +mvn failsafe:integration-test+ This actually runs ALL the integration tests.
1345
1346 NOTE: This command will always output `BUILD SUCCESS` even if there are test failures.
1347
1348 At this point, you could grep the output by hand looking for failed tests.
1349 However, maven will do this for us; just use: +mvn
1350                         failsafe:verify+ The above command basically looks at all the test results (so don't remove the 'target' directory) for test failures and reports the results.
1351
1352 [[maven.build.commands.integration.tests2]]
1353 ===== Running a subset of Integration tests
1354
1355 This is very similar to how you specify running a subset of unit tests (see above), but use the property `it.test` instead of `test`.
1356 To just run `IntegrationTestClassXYZ.java`, use: +mvn
1357                             failsafe:integration-test -Dit.test=IntegrationTestClassXYZ+                        The next thing you might want to do is run groups of integration tests, say all integration tests that are named IntegrationTestClassX*.java: +mvn failsafe:integration-test -Dit.test=*ClassX*+ This runs everything that is an integration test that matches *ClassX*. This means anything matching: "**/IntegrationTest*ClassX*". You can also run multiple groups of integration tests using comma-delimited lists (similar to unit tests). Using a list of matches still supports full regex matching for each of the groups. This would look something like: +mvn
1358                             failsafe:integration-test -Dit.test=*ClassX*, *ClassY+
1359
1360 [[maven.build.commands.integration.tests.distributed]]
1361 ==== Running integration tests against distributed cluster
1362
1363 If you have an already-setup HBase cluster, you can launch the integration tests by invoking the class `IntegrationTestsDriver`.
1364 You may have to run test-compile first.
1365 The configuration will be picked by the bin/hbase script.
1366 [source,bourne]
1367 ----
1368 mvn test-compile
1369 ----
1370 Then launch the tests with:
1371
1372 [source,bourne]
1373 ----
1374 bin/hbase [--config config_dir] org.apache.hadoop.hbase.IntegrationTestsDriver
1375 ----
1376
1377 Pass `-h` to get usage on this sweet tool.
1378 Running the IntegrationTestsDriver without any argument will launch tests found under `hbase-it/src/test`, having `@Category(IntegrationTests.class)` annotation, and a name starting with `IntegrationTests`.
1379 See the usage, by passing -h, to see how to filter test classes.
1380 You can pass a regex which is checked against the full class name; so, part of class name can be used.
1381 IntegrationTestsDriver uses Junit to run the tests.
1382 Currently there is no support for running integration tests against a distributed cluster using maven (see link:https://issues.apache.org/jira/browse/HBASE-6201[HBASE-6201]).
1383
1384 The tests interact with the distributed cluster by using the methods in the `DistributedHBaseCluster` (implementing `HBaseCluster`) class, which in turn uses a pluggable `ClusterManager`.
1385 Concrete implementations provide actual functionality for carrying out deployment-specific and environment-dependent tasks (SSH, etc). The default `ClusterManager` is `HBaseClusterManager`, which uses SSH to remotely execute start/stop/kill/signal commands, and assumes some posix commands (ps, etc). Also assumes the user running the test has enough "power" to start/stop servers on the remote machines.
1386 By default, it picks up `HBASE_SSH_OPTS`, `HBASE_HOME`, `HBASE_CONF_DIR` from the env, and uses `bin/hbase-daemon.sh` to carry out the actions.
1387 Currently tarball deployments, deployments which uses _hbase-daemons.sh_, and link:https://incubator.apache.org/ambari/[Apache Ambari]                    deployments are supported.
1388 _/etc/init.d/_ scripts are not supported for now, but it can be easily added.
1389 For other deployment options, a ClusterManager can be implemented and plugged in.
1390
1391 [[maven.build.commands.integration.tests.destructive]]
1392 ==== Destructive integration / system tests (ChaosMonkey)
1393
1394 HBase 0.96 introduced a tool named `ChaosMonkey`, modeled after
1395 link:https://netflix.github.io/chaosmonkey/[same-named tool by Netflix's Chaos Monkey tool].
1396 ChaosMonkey simulates real-world
1397 faults in a running cluster by killing or disconnecting random servers, or injecting
1398 other failures into the environment. You can use ChaosMonkey as a stand-alone tool
1399 to run a policy while other tests are running. In some environments, ChaosMonkey is
1400 always running, in order to constantly check that high availability and fault tolerance
1401 are working as expected.
1402
1403 ChaosMonkey defines *Actions* and *Policies*.
1404
1405 Actions:: Actions are predefined sequences of events, such as the following:
1406
1407 * Restart active master (sleep 5 sec)
1408 * Restart random regionserver (sleep 5 sec)
1409 * Restart random regionserver (sleep 60 sec)
1410 * Restart META regionserver (sleep 5 sec)
1411 * Restart ROOT regionserver (sleep 5 sec)
1412 * Batch restart of 50% of regionservers (sleep 5 sec)
1413 * Rolling restart of 100% of regionservers (sleep 5 sec)
1414
1415 Policies:: A policy is a strategy for executing one or more actions. The default policy
1416 executes a random action every minute based on predefined action weights.
1417 A given policy will be executed until ChaosMonkey is interrupted.
1418
1419 Most ChaosMonkey actions are configured to have reasonable defaults, so you can run
1420 ChaosMonkey against an existing cluster without any additional configuration. The
1421 following example runs ChaosMonkey with the default configuration:
1422
1423 [source,bash]
1424 ----
1425 $ bin/hbase org.apache.hadoop.hbase.util.ChaosMonkey
1426
1427 12/11/19 23:21:57 INFO util.ChaosMonkey: Using ChaosMonkey Policy: class org.apache.hadoop.hbase.util.ChaosMonkey$PeriodicRandomActionPolicy, period:60000
1428 12/11/19 23:21:57 INFO util.ChaosMonkey: Sleeping for 26953 to add jitter
1429 12/11/19 23:22:24 INFO util.ChaosMonkey: Performing action: Restart active master
1430 12/11/19 23:22:24 INFO util.ChaosMonkey: Killing master:master.example.com,60000,1353367210440
1431 12/11/19 23:22:24 INFO hbase.HBaseCluster: Aborting Master: master.example.com,60000,1353367210440
1432 12/11/19 23:22:24 INFO hbase.ClusterManager: Executing remote command: ps aux | grep master | grep -v grep | tr -s ' ' | cut -d ' ' -f2 | xargs kill -s SIGKILL , hostname:master.example.com
1433 12/11/19 23:22:25 INFO hbase.ClusterManager: Executed remote command, exit code:0 , output:
1434 12/11/19 23:22:25 INFO hbase.HBaseCluster: Waiting service:master to stop: master.example.com,60000,1353367210440
1435 12/11/19 23:22:25 INFO hbase.ClusterManager: Executing remote command: ps aux | grep master | grep -v grep | tr -s ' ' | cut -d ' ' -f2 , hostname:master.example.com
1436 12/11/19 23:22:25 INFO hbase.ClusterManager: Executed remote command, exit code:0 , output:
1437 12/11/19 23:22:25 INFO util.ChaosMonkey: Killed master server:master.example.com,60000,1353367210440
1438 12/11/19 23:22:25 INFO util.ChaosMonkey: Sleeping for:5000
1439 12/11/19 23:22:30 INFO util.ChaosMonkey: Starting master:master.example.com
1440 12/11/19 23:22:30 INFO hbase.HBaseCluster: Starting Master on: master.example.com
1441 12/11/19 23:22:30 INFO hbase.ClusterManager: Executing remote command: /homes/enis/code/hbase-0.94/bin/../bin/hbase-daemon.sh --config /homes/enis/code/hbase-0.94/bin/../conf start master , hostname:master.example.com
1442 12/11/19 23:22:31 INFO hbase.ClusterManager: Executed remote command, exit code:0 , output:starting master, logging to /homes/enis/code/hbase-0.94/bin/../logs/hbase-enis-master-master.example.com.out
1443 ....
1444 12/11/19 23:22:33 INFO util.ChaosMonkey: Started master: master.example.com,60000,1353367210440
1445 12/11/19 23:22:33 INFO util.ChaosMonkey: Sleeping for:51321
1446 12/11/19 23:23:24 INFO util.ChaosMonkey: Performing action: Restart random region server
1447 12/11/19 23:23:24 INFO util.ChaosMonkey: Killing region server:rs3.example.com,60020,1353367027826
1448 12/11/19 23:23:24 INFO hbase.HBaseCluster: Aborting RS: rs3.example.com,60020,1353367027826
1449 12/11/19 23:23:24 INFO hbase.ClusterManager: Executing remote command: ps aux | grep regionserver | grep -v grep | tr -s ' ' | cut -d ' ' -f2 | xargs kill -s SIGKILL , hostname:rs3.example.com
1450 12/11/19 23:23:25 INFO hbase.ClusterManager: Executed remote command, exit code:0 , output:
1451 12/11/19 23:23:25 INFO hbase.HBaseCluster: Waiting service:regionserver to stop: rs3.example.com,60020,1353367027826
1452 12/11/19 23:23:25 INFO hbase.ClusterManager: Executing remote command: ps aux | grep regionserver | grep -v grep | tr -s ' ' | cut -d ' ' -f2 , hostname:rs3.example.com
1453 12/11/19 23:23:25 INFO hbase.ClusterManager: Executed remote command, exit code:0 , output:
1454 12/11/19 23:23:25 INFO util.ChaosMonkey: Killed region server:rs3.example.com,60020,1353367027826. Reported num of rs:6
1455 12/11/19 23:23:25 INFO util.ChaosMonkey: Sleeping for:60000
1456 12/11/19 23:24:25 INFO util.ChaosMonkey: Starting region server:rs3.example.com
1457 12/11/19 23:24:25 INFO hbase.HBaseCluster: Starting RS on: rs3.example.com
1458 12/11/19 23:24:25 INFO hbase.ClusterManager: Executing remote command: /homes/enis/code/hbase-0.94/bin/../bin/hbase-daemon.sh --config /homes/enis/code/hbase-0.94/bin/../conf start regionserver , hostname:rs3.example.com
1459 12/11/19 23:24:26 INFO hbase.ClusterManager: Executed remote command, exit code:0 , output:starting regionserver, logging to /homes/enis/code/hbase-0.94/bin/../logs/hbase-enis-regionserver-rs3.example.com.out
1460
1461 12/11/19 23:24:27 INFO util.ChaosMonkey: Started region server:rs3.example.com,60020,1353367027826. Reported num of rs:6
1462 ----
1463
1464 The output indicates that ChaosMonkey started the default `PeriodicRandomActionPolicy`
1465 policy, which is configured with all the available actions. It chose to run `RestartActiveMaster` and `RestartRandomRs` actions.
1466
1467 ==== Available Policies
1468 HBase ships with several ChaosMonkey policies, available in the
1469 `hbase/hbase-it/src/test/java/org/apache/hadoop/hbase/chaos/policies/` directory.
1470
1471 [[chaos.monkey.properties]]
1472 ==== Configuring Individual ChaosMonkey Actions
1473
1474 ChaosMonkey integration tests can be configured per test run.
1475 Create a Java properties file in the HBase CLASSPATH and pass it to ChaosMonkey using
1476 the `-monkeyProps` configuration flag. Configurable properties, along with their default
1477 values if applicable, are listed in the `org.apache.hadoop.hbase.chaos.factories.MonkeyConstants`
1478 class. For properties that have defaults, you can override them by including them
1479 in your properties file.
1480
1481 The following example uses a properties file called <<monkey.properties,monkey.properties>>.
1482
1483 [source,bourne]
1484 ----
1485 $ bin/hbase org.apache.hadoop.hbase.IntegrationTestIngest -m slowDeterministic -monkeyProps monkey.properties
1486 ----
1487
1488 The above command will start the integration tests and chaos monkey. It will look for the
1489 properties file _monkey.properties_ on the HBase CLASSPATH; e.g. inside the HBASE _conf_ dir.
1490
1491 Here is an example chaos monkey file:
1492
1493 [[monkey.properties]]
1494 .Example ChaosMonkey Properties File
1495 [source]
1496 ----
1497 sdm.action1.period=120000
1498 sdm.action2.period=40000
1499 move.regions.sleep.time=80000
1500 move.regions.max.time=1000000
1501 move.regions.sleep.time=80000
1502 batch.restart.rs.ratio=0.4f
1503 ----
1504
1505 Periods/time are expressed in milliseconds.
1506
1507 HBase 1.0.2 and newer adds the ability to restart HBase's underlying ZooKeeper quorum or
1508 HDFS nodes. To use these actions, you need to configure some new properties, which
1509 have no reasonable defaults because they are deployment-specific, in your ChaosMonkey
1510 properties file, which may be `hbase-site.xml` or a different properties file.
1511
1512 [source,xml]
1513 ----
1514 <property>
1515   <name>hbase.it.clustermanager.hadoop.home</name>
1516   <value>$HADOOP_HOME</value>
1517 </property>
1518 <property>
1519   <name>hbase.it.clustermanager.zookeeper.home</name>
1520   <value>$ZOOKEEPER_HOME</value>
1521 </property>
1522 <property>
1523   <name>hbase.it.clustermanager.hbase.user</name>
1524   <value>hbase</value>
1525 </property>
1526 <property>
1527   <name>hbase.it.clustermanager.hadoop.hdfs.user</name>
1528   <value>hdfs</value>
1529 </property>
1530 <property>
1531   <name>hbase.it.clustermanager.zookeeper.user</name>
1532   <value>zookeeper</value>
1533 </property>
1534 ----
1535
1536 [[developing]]
1537 == Developer Guidelines
1538
1539 === Branches
1540
1541 We use Git for source code management and latest development happens on `master` branch. There are
1542 branches for past major/minor/maintenance releases and important features and bug fixes are often
1543  back-ported to them.
1544
1545 [[code.standards]]
1546 === Code Standards
1547
1548
1549 ==== Interface Classifications
1550
1551 Interfaces are classified both by audience and by stability level.
1552 These labels appear at the head of a class.
1553 The conventions followed by HBase are inherited by its parent project, Hadoop.
1554
1555 The following interface classifications are commonly used:
1556
1557 .InterfaceAudience
1558 `@InterfaceAudience.Public`::
1559   APIs for users and HBase applications.
1560   These APIs will be deprecated through major versions of HBase.
1561
1562 `@InterfaceAudience.Private`::
1563   APIs for HBase internals developers.
1564   No guarantees on compatibility or availability in future versions.
1565   Private interfaces do not need an `@InterfaceStability` classification.
1566
1567 `@InterfaceAudience.LimitedPrivate(HBaseInterfaceAudience.COPROC)`::
1568   APIs for HBase coprocessor writers.
1569
1570 No `@InterfaceAudience` Classification::
1571   Packages without an `@InterfaceAudience` label are considered private.
1572   Mark your new packages if publicly accessible.
1573
1574 .Excluding Non-Public Interfaces from API Documentation
1575 [NOTE]
1576 ====
1577 Only interfaces classified `@InterfaceAudience.Public` should be included in API documentation (Javadoc). Committers must add new package excludes `ExcludePackageNames` section of the _pom.xml_ for new packages which do not contain public classes.
1578 ====
1579
1580 .@InterfaceStability
1581 `@InterfaceStability` is important for packages marked `@InterfaceAudience.Public`.
1582
1583 `@InterfaceStability.Stable`::
1584   Public packages marked as stable cannot be changed without a deprecation path or a very good reason.
1585
1586 `@InterfaceStability.Unstable`::
1587   Public packages marked as unstable can be changed without a deprecation path.
1588
1589 `@InterfaceStability.Evolving`::
1590   Public packages marked as evolving may be changed, but it is discouraged.
1591
1592 No `@InterfaceStability` Label::
1593   Public classes with no `@InterfaceStability` label are discouraged, and should be considered implicitly unstable.
1594
1595 If you are unclear about how to mark packages, ask on the development list.
1596
1597 [[common.patch.feedback]]
1598 ==== Code Formatting Conventions
1599
1600 Please adhere to the following guidelines so that your patches can be reviewed more quickly.
1601 These guidelines have been developed based upon common feedback on patches from new contributors.
1602
1603 See the link:http://www.oracle.com/technetwork/java/index-135089.html[Code
1604                     Conventions for the Java Programming Language] for more information on coding conventions in Java.
1605 See <<eclipse.code.formatting,eclipse.code.formatting>> to setup Eclipse to check for some of
1606 these guidelines automatically.
1607
1608 [[common.patch.feedback.space.invaders]]
1609 ===== Space Invaders
1610
1611 Do not use extra spaces around brackets.
1612 Use the second style, rather than the first.
1613
1614 [source,java]
1615 ----
1616
1617 if ( foo.equals( bar ) ) {     // don't do this
1618 ----
1619
1620 [source,java]
1621 ----
1622
1623 if (foo.equals(bar)) {
1624 ----
1625
1626 [source,java]
1627 ----
1628
1629 foo = barArray[ i ];     // don't do this
1630 ----
1631
1632 [source,java]
1633 ----
1634
1635 foo = barArray[i];
1636 ----
1637
1638 [[common.patch.feedback.autogen]]
1639 ===== Auto Generated Code
1640
1641 Auto-generated code in Eclipse often uses bad variable names such as `arg0`.
1642 Use more informative variable names.
1643 Use code like the second example here.
1644
1645 [source,java]
1646 ----
1647
1648  public void readFields(DataInput arg0) throws IOException {    // don't do this
1649    foo = arg0.readUTF();                                       // don't do this
1650 ----
1651
1652 [source,java]
1653 ----
1654
1655  public void readFields(DataInput di) throws IOException {
1656    foo = di.readUTF();
1657 ----
1658
1659 [[common.patch.feedback.longlines]]
1660 ===== Long Lines
1661
1662 Keep lines less than 100 characters.
1663 You can configure your IDE to do this automatically.
1664
1665 [source,java]
1666 ----
1667
1668 Bar bar = foo.veryLongMethodWithManyArguments(argument1, argument2, argument3, argument4, argument5, argument6, argument7, argument8, argument9);  // don't do this
1669 ----
1670
1671 [source,java]
1672 ----
1673
1674 Bar bar = foo.veryLongMethodWithManyArguments(
1675  argument1, argument2, argument3,argument4, argument5, argument6, argument7, argument8, argument9);
1676 ----
1677
1678 [[common.patch.feedback.trailingspaces]]
1679 ===== Trailing Spaces
1680
1681 Be sure there is a line break after the end of your code, and avoid lines with nothing but whitespace.
1682 This makes diffs more meaningful.
1683 You can configure your IDE to help with this.
1684
1685 [source,java]
1686 ----
1687
1688 Bar bar = foo.getBar();     <--- imagine there is an extra space(s) after the semicolon.
1689 ----
1690
1691 [[common.patch.feedback.javadoc]]
1692 ===== API Documentation (Javadoc)
1693
1694 Don't forget Javadoc!
1695
1696 Javadoc warnings are checked during precommit.
1697 If the precommit tool gives you a '-1', please fix the javadoc issue.
1698 Your patch won't be committed if it adds such warnings.
1699
1700 Also, no `@author` tags - that's a rule.
1701
1702 [[common.patch.feedback.findbugs]]
1703 ===== Findbugs
1704
1705 `Findbugs` is used to detect common bugs pattern.
1706 It is checked during the precommit build.
1707 If errors are found, please fix them.
1708 You can run findbugs locally with `mvn
1709                             findbugs:findbugs`, which will generate the `findbugs` files locally.
1710 Sometimes, you may have to write code smarter than `findbugs`.
1711 You can annotate your code to tell `findbugs` you know what you're doing, by annotating your class with the following annotation:
1712
1713 [source,java]
1714 ----
1715 @edu.umd.cs.findbugs.annotations.SuppressWarnings(
1716 value="HE_EQUALS_USE_HASHCODE",
1717 justification="I know what I'm doing")
1718 ----
1719
1720 It is important to use the Apache-licensed version of the annotations. That generally means using
1721 annotations in the `edu.umd.cs.findbugs.annotations` package so that we can rely on the cleanroom
1722 reimplementation rather than annotations in the `javax.annotations` package.
1723
1724 [[common.patch.feedback.javadoc.defaults]]
1725 ===== Javadoc - Useless Defaults
1726
1727 Don't just leave javadoc tags the way IDE generates them, or fill redundant information in them.
1728
1729 [source,java]
1730 ----
1731
1732   /**
1733    * @param table                              <---- don't leave them empty!
1734    * @param region An HRegion object.          <---- don't fill redundant information!
1735    * @return Foo Object foo just created.      <---- Not useful information
1736    * @throws SomeException                     <---- Not useful. Function declarations already tell that!
1737    * @throws BarException when something went wrong  <---- really?
1738    */
1739   public Foo createFoo(Bar bar);
1740 ----
1741
1742 Either add something descriptive to the tags, or just remove them.
1743 The preference is to add something descriptive and useful.
1744
1745 [[common.patch.feedback.onething]]
1746 ===== One Thing At A Time, Folks
1747
1748 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.
1749
1750 Likewise, don't add unrelated cleanup or refactorings outside the scope of your Jira.
1751
1752 [[common.patch.feedback.tests]]
1753 ===== Ambigious Unit Tests
1754
1755 Make sure that you're clear about what you are testing in your unit tests and why.
1756
1757 [[common.patch.feedback.writable]]
1758 ===== Implementing Writable
1759
1760 .Applies pre-0.96 only
1761 [NOTE]
1762 ====
1763 In 0.96, HBase moved to protocol buffers (protobufs). The below section on Writables applies to 0.94.x and previous, not to 0.96 and beyond.
1764 ====
1765
1766 Every class returned by RegionServers must implement the `Writable` interface.
1767 If you are creating a new class that needs to implement this interface, do not forget the default constructor.
1768
1769 ==== Garbage-Collection Conserving Guidelines
1770
1771 The following guidelines were borrowed from http://engineering.linkedin.com/performance/linkedin-feed-faster-less-jvm-garbage.
1772 Keep them in mind to keep preventable garbage  collection to a minimum. Have a look
1773 at the blog post for some great examples of how to refactor your code according to
1774 these guidelines.
1775
1776 - Be careful with Iterators
1777 - Estimate the size of a collection when initializing
1778 - Defer expression evaluation
1779 - Compile the regex patterns in advance
1780 - Cache it if you can
1781 - String Interns are useful but dangerous
1782
1783 [[design.invariants]]
1784 === Invariants
1785
1786 We don't have many but what we have we list below.
1787 All are subject to challenge of course but until then, please hold to the rules of the road.
1788
1789 [[design.invariants.zk.data]]
1790 ==== No permanent state in ZooKeeper
1791
1792 ZooKeeper state should transient (treat it like memory). If ZooKeeper state is deleted, hbase should be able to recover and essentially be in the same state.
1793
1794 * .Exceptions: There are currently a few exceptions that we need to fix around whether a table is enabled or disabled.
1795 * Replication data is currently stored only in ZooKeeper.
1796   Deleting ZooKeeper data related to replication may cause replication to be disabled.
1797   Do not delete the replication tree, _/hbase/replication/_.
1798 +
1799 WARNING: Replication may be disrupted and data loss may occur if you delete the replication tree (_/hbase/replication/_) from ZooKeeper.
1800 Follow progress on this issue at link:https://issues.apache.org/jira/browse/HBASE-10295[HBASE-10295].
1801
1802
1803 [[run.insitu]]
1804 === Running In-Situ
1805
1806 If you are developing Apache HBase, frequently it is useful to test your changes against a more-real cluster than what you find in unit tests.
1807 In this case, HBase can be run directly from the source in local-mode.
1808 All you need to do is run:
1809
1810 [source,bourne]
1811 ----
1812 ${HBASE_HOME}/bin/start-hbase.sh
1813 ----
1814
1815 This will spin up a full local-cluster, just as if you had packaged up HBase and installed it on your machine.
1816
1817 Keep in mind that you will need to have installed HBase into your local maven repository for the in-situ cluster to work properly.
1818 That is, you will need to run:
1819
1820 [source,bourne]
1821 ----
1822 mvn clean install -DskipTests
1823 ----
1824
1825 to ensure that maven can find the correct classpath and dependencies.
1826 Generally, the above command is just a good thing to try running first, if maven is acting oddly.
1827
1828 [[add.metrics]]
1829 === Adding Metrics
1830
1831 After adding a new feature a developer might want to add metrics.
1832 HBase exposes metrics using the Hadoop Metrics 2 system, so adding a new metric involves exposing that metric to the hadoop system.
1833 Unfortunately the API of metrics2 changed from hadoop 1 to hadoop 2.
1834 In order to get around this a set of interfaces and implementations have to be loaded at runtime.
1835 To get an in-depth look at the reasoning and structure of these classes you can read the blog post located link:https://blogs.apache.org/hbase/entry/migration_to_the_new_metrics[here].
1836 To add a metric to an existing MBean follow the short guide below:
1837
1838 ==== Add Metric name and Function to Hadoop Compat Interface.
1839
1840 Inside of the source interface the corresponds to where the metrics are generated (eg MetricsMasterSource for things coming from HMaster) create new static strings for metric name and description.
1841 Then add a new method that will be called to add new reading.
1842
1843 ==== Add the Implementation to Both Hadoop 1 and Hadoop 2 Compat modules.
1844
1845 Inside of the implementation of the source (eg.
1846 MetricsMasterSourceImpl in the above example) create a new histogram, counter, gauge, or stat in the init method.
1847 Then in the method that was added to the interface wire up the parameter passed in to the histogram.
1848
1849 Now add tests that make sure the data is correctly exported to the metrics 2 system.
1850 For this the MetricsAssertHelper is provided.
1851
1852 [[git.best.practices]]
1853 === Git Best Practices
1854
1855 Avoid git merges.::
1856   Use `git pull --rebase` or `git fetch` followed by `git rebase`.
1857 Do not use `git push --force`.::
1858   If the push does not work, fix the problem or ask for help.
1859
1860 Please contribute to this document if you think of other Git best practices.
1861
1862 ==== `rebase_all_git_branches.sh`
1863
1864 The _dev-support/rebase_all_git_branches.sh_ script is provided to help keep your Git repository clean.
1865 Use the `-h`                    parameter to get usage instructions.
1866 The script automatically refreshes your tracking branches, attempts an automatic rebase of each local branch against its remote branch, and gives you the option to delete any branch which represents a closed `HBASE-` JIRA.
1867 The script has one optional configuration option, the location of your Git directory.
1868 You can set a default by editing the script.
1869 Otherwise, you can pass the git directory manually by using the `-d` parameter, followed by an absolute or relative directory name, or even '.' for the current working directory.
1870 The script checks the directory for sub-directory called _.git/_, before proceeding.
1871
1872 [[submitting.patches]]
1873 === Submitting Patches
1874
1875 If you are new to submitting patches to open source or new to submitting patches to Apache, start by
1876  reading the link:https://commons.apache.org/patches.html[On Contributing Patches] page from
1877  link:https://commons.apache.org/[Apache Commons Project].
1878 It provides a nice overview that applies equally to the Apache HBase Project.
1879 link:https://accumulo.apache.org/git.html[Accumulo doc on how to contribute and develop] is also
1880 good read to understand development workflow.
1881
1882 [[submitting.patches.create]]
1883 ==== Create Patch
1884
1885 Make sure you review <<common.patch.feedback,common.patch.feedback>> for code style. If your
1886 patch
1887 was generated incorrectly or your code does not adhere to the code formatting guidelines, you may
1888 be asked to redo some work.
1889
1890
1891 .Using submit-patch.py (recommended)
1892
1893 [source,bourne]
1894 ----
1895 $ dev-support/submit-patch.py -jid HBASE-xxxxx
1896 ----
1897
1898 Use this script to create patches, upload to jira and optionally create/update reviews on
1899 Review Board. Patch name is automatically formatted as _(JIRA).(branch name).(patch number).patch_
1900  to follow Yetus' naming rules. Use `-h` flag to know detailed usage information. Most useful options
1901 are:
1902
1903 * `-b BRANCH, --branch BRANCH` : Specify base branch for generating the diff. If not specified,
1904 tracking branch is used. If there is no tracking branch, error will be thrown.
1905 * `-jid JIRA_ID, --jira-id JIRA_ID` : If used, deduces next patch version from attachments in the
1906 jira and uploads the new patch. Script will ask for jira username/password for authentication.
1907 If not set, patch is named <branch>.patch.
1908
1909 By default, it'll also create/update review board. To skip that action, use `-srb` option. It uses
1910 'Issue Links' in the jira to figure out if a review request already exists. If no review
1911 request is present, then creates a new one and populates all required fields using jira summary,
1912 patch description, etc. Also adds this review's link to the jira.
1913
1914 Save authentication credentials (optional)::
1915 Since attaching patches on JIRA and creating/changing review request on ReviewBoard requires
1916 valid user authentication, the script will prompt you for username and password. To avoid the hassle every
1917 time, set up `~/.apache-creds` with login details and encrypt it by following the steps in footer
1918 of script's help message.
1919
1920 Python dependencies:: To install required python dependencies, execute
1921 `pip install -r dev-support/python-requirements.txt` from the master branch.
1922
1923 .Manually
1924
1925   . Use `git rebase -i` first, to combine (squash) smaller commits into a single larger one.
1926   . Create patch using IDE or Git commands. `git format-patch` is preferred since it preserves patch
1927     author's name and commit message. Also, it handles binary files by default, whereas `git diff`
1928     ignores them unless you use the `--binary` option.
1929   . Patch name should be as follows to adhere to Yetus' naming convention: +
1930     `(JIRA).(branch name).(patch number).patch` +
1931     For eg. HBASE-11625.master.001.patch, HBASE-XXXXX.branch-1.2.0005.patch, etc.
1932   . Attach the patch to the JIRA using `More->Attach Files` then click on btn:[Submit Patch]
1933     button, which'll trigger Hudson job to check patch for validity.
1934   . If your patch is longer than a single screen, also create a review on Review Board  and
1935     add the link to JIRA. See <<reviewboard,reviewboard>>.
1936
1937
1938
1939 .Few general guidelines
1940 * Always patch against the master branch first, even if you want to patch in another branch.
1941   HBase committers always apply patches first to the master branch, and backport if necessary.
1942 * Submit one single patch for a fix. If necessary, squash local commits to merge local commits into
1943   a single one first. See this
1944   link:http://stackoverflow.com/questions/5308816/how-to-use-git-merge-squash[Stack Overflow
1945   question] for more information about squashing commits.
1946 * Please understand that not every patch may get committed, and that feedback will likely be
1947   provided on the patch.
1948 * If you need to revise your patch, leave the previous patch file(s) attached to the JIRA, and
1949   upload a new one with incremented patch number. +
1950   Click on btn:[Cancel Patch] and then on btn:[Submit Patch] to trigger the presubmit run.
1951
1952 [[submitting.patches.tests]]
1953 ==== Unit Tests
1954 Always add and/or update relevant unit tests when making the changes.
1955 Make sure that new/changed unit tests pass locally before submitting the patch because it is faster
1956 than waiting for presubmit result which runs full test suite. This will save your own time and
1957 effort.
1958 Use <<mockito,mockito>> to make mocks which are very useful for testing failure scenarios by
1959 injecting appropriate failures.
1960
1961 If you are creating a new unit test class, notice how other unit test classes have
1962 classification/sizing annotations before class name and a static methods for setup/teardown of
1963 testing environment. Be sure to include annotations in any new unit test files.
1964 See <<hbase.tests,hbase.tests>> for more information on tests.
1965
1966 ==== Integration Tests
1967
1968 Significant new features should provide an integration test in addition to unit tests, suitable for exercising the new feature at different points in its configuration space.
1969
1970 [[reviewboard]]
1971 ==== ReviewBoard
1972
1973 Patches larger than one screen, or patches that will be tricky to review, should go through link:https://reviews.apache.org[ReviewBoard].
1974
1975 .Procedure: Use ReviewBoard
1976 . Register for an account if you don't already have one.
1977   It does not use the credentials from link:https://issues.apache.org[issues.apache.org].
1978   Log in.
1979 . Click [label]#New Review Request#.
1980 . Choose the `hbase-git` repository.
1981   Click Choose File to select the diff and optionally a parent diff.
1982   Click btn:[Create
1983   Review Request].
1984 . Fill in the fields as required.
1985   At the minimum, fill in the [label]#Summary# and choose `hbase` as the [label]#Review Group#.
1986   If you fill in the [label]#Bugs# field, the review board links back to the relevant JIRA.
1987   The more fields you fill in, the better.
1988   Click btn:[Publish] to make your review request public.
1989   An email will be sent to everyone in the `hbase` group, to review the patch.
1990 . Back in your JIRA, click , and paste in the URL of your ReviewBoard request.
1991   This attaches the ReviewBoard to the JIRA, for easy access.
1992 . To cancel the request, click .
1993
1994 For more information on how to use ReviewBoard, see link:http://www.reviewboard.org/docs/manual/1.5/[the ReviewBoard
1995                         documentation].
1996
1997 ==== Guide for HBase Committers
1998
1999 ===== New committers
2000
2001 New committers are encouraged to first read Apache's generic committer documentation:
2002
2003 * link:https://www.apache.org/dev/new-committers-guide.html[Apache New Committer Guide]
2004 * link:https://www.apache.org/dev/committers.html[Apache Committer FAQ]
2005
2006 ===== Review
2007
2008 HBase committers should, as often as possible, attempt to review patches submitted by others.
2009 Ideally every submitted patch will get reviewed by a committer _within a few days_.
2010 If a committer reviews a patch they have not authored, and believe it to be of sufficient quality, then they can commit the patch, otherwise the patch should be cancelled with a clear explanation for why it was rejected.
2011
2012 The list of submitted patches is in the link:https://issues.apache.org/jira/secure/IssueNavigator.jspa?mode=hide&requestId=12312392[HBase Review Queue], which is ordered by time of last modification.
2013 Committers should scan the list from top to bottom, looking for patches that they feel qualified to review and possibly commit.
2014
2015 For non-trivial changes, it is required to get another committer to review your own patches before commit.
2016 Use the btn:[Submit Patch]                        button in JIRA, just like other contributors, and then wait for a `+1` response from another committer before committing.
2017
2018 ===== Reject
2019
2020 Patches which do not adhere to the guidelines in link:https://hbase.apache.org/book.html#developer[HowToContribute] and to the link:https://wiki.apache.org/hadoop/CodeReviewChecklist[code review checklist] should be rejected.
2021 Committers should always be polite to contributors and try to instruct and encourage them to contribute better patches.
2022 If a committer wishes to improve an unacceptable patch, then it should first be rejected, and a new patch should be attached by the committer for review.
2023
2024 [[committing.patches]]
2025 ===== Commit
2026
2027 Committers commit patches to the Apache HBase GIT repository.
2028
2029 .Before you commit!!!!
2030 [NOTE]
2031 ====
2032 Make sure your local configuration is correct, especially your identity and email.
2033 Examine the output of the +$ git config
2034                                 --list+ command and be sure it is correct.
2035 See this GitHub article, link:https://help.github.com/articles/set-up-git[Set Up Git] if you need pointers.
2036 ====
2037
2038 When you commit a patch, please:
2039
2040 . Include the Jira issue id in the commit message along with a short description of the change. Try
2041   to add something more than just the Jira title so that someone looking at git log doesn't
2042   have to go to Jira to discern what the change is about.
2043   Be sure to get the issue ID right, as this causes Jira to link to the change in Git (use the
2044   issue's "All" tab to see these).
2045 . Commit the patch to a new branch based off master or other intended branch.
2046   It's a good idea to call this branch by the JIRA ID.
2047   Then check out the relevant target branch where you want to commit, make sure your local branch has all remote changes, by doing a +git pull --rebase+ or another similar command, cherry-pick the change into each relevant branch (such as master), and do +git push <remote-server>
2048   <remote-branch>+.
2049 +
2050 WARNING: If you do not have all remote changes, the push will fail.
2051 If the push fails for any reason, fix the problem or ask for help.
2052 Do not do a +git push --force+.
2053 +
2054 Before you can commit a patch, you need to determine how the patch was created.
2055 The instructions and preferences around the way to create patches have changed, and there will be a transition period.
2056 +
2057 .Determine How a Patch Was Created
2058 * If the first few lines of the patch look like the headers of an email, with a From, Date, and
2059   Subject, it was created using +git format-patch+. This is the preferred way, because you can
2060   reuse the submitter's commit message. If the commit message is not appropriate, you can still use
2061   the commit, then run `git commit --amend` and reword as appropriate.
2062 * If the first line of the patch looks similar to the following, it was created using +git diff+                                        without `--no-prefix`.
2063   This is acceptable too.
2064   Notice the `a` and `b` in front of the file names.
2065   This is the indication that the patch was not created with `--no-prefix`.
2066 +
2067 ----
2068 diff --git a/src/main/asciidoc/_chapters/developer.adoc b/src/main/asciidoc/_chapters/developer.adoc
2069 ----
2070
2071 * If the first line of the patch looks similar to the following (without the `a` and `b`), the
2072 patch was created with +git diff --no-prefix+ and you need to add `-p0` to the +git apply+ command
2073 below.
2074 +
2075 ----
2076 diff --git src/main/asciidoc/_chapters/developer.adoc src/main/asciidoc/_chapters/developer.adoc
2077 ----
2078
2079 +
2080 .Example of committing a Patch
2081 ====
2082 One thing you will notice with these examples is that there are a lot of +git pull+ commands.
2083 The only command that actually writes anything to the remote repository is +git push+, and you need to make absolutely sure you have the correct versions of everything and don't have any conflicts before pushing.
2084 The extra +git
2085                                         pull+ commands are usually redundant, but better safe than sorry.
2086
2087 The first example shows how to apply a patch that was generated with +git format-patch+ and apply it to the `master` and `branch-1` branches.
2088
2089 The directive to use +git format-patch+                                    rather than +git diff+, and not to use `--no-prefix`, is a new one.
2090 See the second example for how to apply a patch created with +git
2091                                         diff+, and educate the person who created the patch.
2092
2093 ----
2094 $ git checkout -b HBASE-XXXX
2095 $ git am ~/Downloads/HBASE-XXXX-v2.patch --signoff  # If you are committing someone else's patch.
2096 $ git checkout master
2097 $ git pull --rebase
2098 $ git cherry-pick <sha-from-commit>
2099 # Resolve conflicts if necessary or ask the submitter to do it
2100 $ git pull --rebase          # Better safe than sorry
2101 $ git push origin master
2102
2103 # Backport to branch-1
2104 $ git checkout branch-1
2105 $ git pull --rebase
2106 $ git cherry-pick <sha-from-commit>
2107 # Resolve conflicts if necessary
2108 $ git pull --rebase          # Better safe than sorry
2109 $ git push origin branch-1
2110 $ git branch -D HBASE-XXXX
2111 ----
2112
2113 This example shows how to commit a patch that was created using +git diff+ without `--no-prefix`.
2114 If the patch was created with `--no-prefix`, add `-p0` to the +git apply+ command.
2115
2116 ----
2117 $ git apply ~/Downloads/HBASE-XXXX-v2.patch
2118 $ git commit -m "HBASE-XXXX Really Good Code Fix (Joe Schmo)" --author=<contributor> -a  # This
2119 and next command is needed for patches created with 'git diff'
2120 $ git commit --amend --signoff
2121 $ git checkout master
2122 $ git pull --rebase
2123 $ git cherry-pick <sha-from-commit>
2124 # Resolve conflicts if necessary or ask the submitter to do it
2125 $ git pull --rebase          # Better safe than sorry
2126 $ git push origin master
2127
2128 # Backport to branch-1
2129 $ git checkout branch-1
2130 $ git pull --rebase
2131 $ git cherry-pick <sha-from-commit>
2132 # Resolve conflicts if necessary or ask the submitter to do it
2133 $ git pull --rebase           # Better safe than sorry
2134 $ git push origin branch-1
2135 $ git branch -D HBASE-XXXX
2136 ----
2137 ====
2138
2139 . Resolve the issue as fixed, thanking the contributor.
2140   Always set the "Fix Version" at this point, but please only set a single fix version for each branch where the change was committed, the earliest release in that branch in which the change will appear.
2141
2142 ====== Commit Message Format
2143
2144 The commit message should contain the JIRA ID and a description of what the patch does.
2145 The preferred commit message format is:
2146
2147 ----
2148 <jira-id> <jira-title> (<contributor-name-if-not-commit-author>)
2149 ----
2150
2151 ----
2152 HBASE-12345 Fix All The Things (jane@example.com)
2153 ----
2154
2155 If the contributor used +git format-patch+ to generate the patch, their commit message is in their patch and you can use that, but be sure the JIRA ID is at the front of the commit message, even if the contributor left it out.
2156
2157 [[committer.amending.author]]
2158 ====== Add Amending-Author when a conflict cherrypick backporting
2159
2160 We've established the practice of committing to master and then cherry picking back to branches whenever possible.
2161 When there is a minor conflict we can fix it up and just proceed with the commit.
2162 The resulting commit retains the original author.
2163 When the amending author is different from the original committer, add notice of this at the end of the commit message as: `Amending-Author: Author
2164                                 <committer&apache>` See discussion at link:http://search-hadoop.com/m/DHED4wHGYS[HBase, mail # dev
2165                                 - [DISCUSSION] Best practice when amending commits cherry picked
2166                                 from master to branch].
2167
2168 ====== Close related GitHub PRs
2169
2170 As a project we work to ensure there's a JIRA associated with each change, but we don't mandate any particular tool be used for reviews. Due to implementation details of the ASF's integration between hosted git repositories and GitHub, the PMC has no ability to directly close PRs on our GitHub repo. In the event that a contributor makes a Pull Request on GitHub, either because the contributor finds that easier than attaching a patch to JIRA or because a reviewer prefers that UI for examining changes, it's important to make note of the PR in the commit that goes to the master branch so that PRs are kept up to date.
2171
2172 To read more about the details of what kinds of commit messages will work with the GitHub "close via keyword in commit" mechanism see link:https://help.github.com/articles/closing-issues-using-keywords/[the GitHub documentation for "Closing issues using keywords"]. In summary, you should include a line with the phrase "closes #XXX", where the XXX is the pull request id. The pull request id is usually given in the GitHub UI in grey at the end of the subject heading.
2173
2174 [[committer.tests]]
2175 ====== Committers are responsible for making sure commits do not break the build or tests
2176
2177 If a committer commits a patch, it is their responsibility to make sure it passes the test suite.
2178 It is helpful if contributors keep an eye out that their patch does not break the hbase build and/or tests, but ultimately, a contributor cannot be expected to be aware of all the particular vagaries and interconnections that occur in a project like HBase.
2179 A committer should.
2180
2181 [[git.patch.flow]]
2182 ====== Patching Etiquette
2183
2184 In the thread link:http://search-hadoop.com/m/DHED4EiwOz[HBase, mail # dev - ANNOUNCEMENT: Git Migration In Progress (WAS =>
2185                                 Re: Git Migration)], it was agreed on the following patch flow
2186
2187 . Develop and commit the patch against master first.
2188 . Try to cherry-pick the patch when backporting if possible.
2189 . If this does not work, manually commit the patch to the branch.
2190
2191 ====== Merge Commits
2192
2193 Avoid merge commits, as they create problems in the git history.
2194
2195 ====== Committing Documentation
2196
2197 See <<appendix_contributing_to_documentation,appendix contributing to documentation>>.
2198
2199 ==== Dialog
2200
2201 Committers should hang out in the #hbase room on irc.freenode.net for real-time discussions.
2202 However any substantive discussion (as with any off-list project-related discussion) should be re-iterated in Jira or on the developer list.
2203
2204 ==== Do not edit JIRA comments
2205
2206 Misspellings and/or bad grammar is preferable to the disruption a JIRA comment edit causes: See the discussion at link:http://search-hadoop.com/?q=%5BReopened%5D+%28HBASE-451%29+Remove+HTableDescriptor+from+HRegionInfo&fc_project=HBase[Re:(HBASE-451) Remove HTableDescriptor from HRegionInfo]
2207
2208 [[thirdparty]]
2209 === The hbase-thirdparty dependency and shading/relocation
2210
2211 A new project was created for the release of hbase-2.0.0. It was called
2212 `hbase-thirdparty`. This project exists only to provide the main hbase
2213 project with relocated -- or shaded -- versions of popular thirdparty
2214 libraries such as guava, netty, and protobuf. The mainline HBase project
2215 relies on the relocated versions of these libraries gotten from hbase-thirdparty
2216 rather than on finding these classes in their usual locations. We do this so
2217 we can specify whatever the version we wish. If we don't relocate, we must
2218 harmonize our version to match that which hadoop, spark, and other projects use.
2219
2220 For developers, this means you need to be careful referring to classes from
2221 netty, guava, protobuf, gson, etc. (see the hbase-thirdparty pom.xml for what
2222 it provides). Devs must refer to the hbase-thirdparty provided classes. In
2223 practice, this is usually not an issue (though it can be a bit of a pain). You
2224 will have to hunt for the relocated version of your particular class. You'll
2225 find it by prepending the general relocation prefix of `org.apache.hbase.thirdparty.`.
2226 For example if you are looking for `com.google.protobuf.Message`, the relocated
2227 version used by HBase internals can be found at
2228 `org.apache.hbase.thirdparty.com.google.protobuf.Message`.
2229
2230 For a few thirdparty libs, like protobuf (see the protobuf chapter in this book
2231 for the why), your IDE may give you both options -- the `com.google.protobuf.*`
2232 and the `org.apache.hbase.thirdparty.com.google.protobuf.*` -- because both
2233 classes are on your CLASSPATH. Unless you are doing the particular juggling
2234 required in Coprocessor Endpoint development (again see above cited protobuf
2235 chapter), you'll want to use the shaded version, always.
2236
2237 The `hbase-thirdparty` project has groupid of `org.apache.hbase.thirdparty`.
2238 As of this writing, it provides three jars; one for netty with an artifactid of
2239 `hbase-thirdparty-netty`, one for protobuf at `hbase-thirdparty-protobuf` and then
2240 a jar for all else -- gson, guava -- at `hbase-thirdpaty-miscellaneous`.
2241
2242 The hbase-thirdparty artifacts are a product produced by the Apache HBase
2243 project under the aegis of the HBase Project Management Committee. Releases
2244 are done via the usual voting project on the hbase dev mailing list. If issue
2245 in the hbase-thirdparty, use the hbase JIRA and mailing lists to post notice.
2246
2247 [[hbase.archetypes.development]]
2248 === Development of HBase-related Maven archetypes
2249
2250 The development of HBase-related Maven archetypes was begun with
2251 link:https://issues.apache.org/jira/browse/HBASE-14876[HBASE-14876].
2252 For an overview of the hbase-archetypes infrastructure and instructions
2253 for developing new HBase-related Maven archetypes, please see
2254 `hbase/hbase-archetypes/README.md`.
2255
2256 ifdef::backend-docbook[]
2257 [index]
2258 == Index
2259 // Generated automatically by the DocBook toolchain.
2260 endif::backend-docbook[]