busbey commented on a change in pull request #1871:
URL: https://github.com/apache/hbase/pull/1871#discussion_r437027415
##########
File path: src/main/asciidoc/_chapters/developer.adoc
##########
@@ -397,28 +396,109 @@ mvn clean install -DskipTests
See the <<hbase.unittests.cmds,hbase.unittests.cmds>> section in
<<hbase.unittests,hbase.unittests>>
[[maven.build.hadoop]]
-==== Building against various hadoop versions.
+==== Building against various Hadoop versions
+
+HBase supports building against Apache Hadoop versions: 2.y and 3.y (early
release artifacts).
+Exactly which version of Hadoop is used by default varies by release branch.
See the section
+<<hadoop,Hadoop>> for the complete breakdown of supported Hadoop version by
HBase release.
+
+The mechanism for selecting a Hadoop version at build time is identical across
all releases. Which
+version of Hadoop is default varies. We manage Hadoop major version selection
by way of Maven
+profiles. Due to the peculiarities of Maven profile mutual exclusion, the
profile that builds
+against a particular Hadoop version is activated by setting a property, *not*
the usual profile
+activation. Hadoop version profile activation is summarized by the following
table.
+
+.Hadoop Profile Activation by HBase Release
+[cols="3*^.^", options="header"]
+|===
+| | Hadoop2 Activation | Hadoop3 Activation
+| HBase 1.3+ | _active by default_ | `-Dhadoop.profile=3.0`
+| HBase 3.0+ | _not supported_ | _active by default_
+|===
+
+[WARNING]
+====
+Please note that where a profile is active by default, `hadoop.profile` must
NOT be provided.
+====
+
+Once the Hadoop major version profile is activated, the exact Hadoop version
can be
+specified by overriding the appropriate property value. For Hadoop2 versions,
the property name
+is `hadoop-two.version`. With Hadoop3 versions, the property name is
`hadoop-three.version`.
-HBase supports building against Apache Hadoop versions: 2.y and 3.y (early
release artifacts). By default we build against Hadoop 2.x.
+.Example 1, Building HBase 1.7 against Hadoop 2.10.0
-To build against a specific release from the Hadoop 2.y line, set e.g.
`-Dhadoop-two.version=2.6.3`.
+For example, to build HBase 1.7 against Hadoop 2.10.0, the profile is set for
Hadoop2 by default,
+so only `hadoop-two.version` must be specified:
[source,bourne]
----
-mvn -Dhadoop-two.version=2.6.3 ...
+git checkout branch-1
+mvn -Dhadoop-two.version=2.10.0 ...
----
-To change the major release line of Hadoop we build against, add a
hadoop.profile property when you invoke +mvn+:
+.Example 2, Building HBase 2.3 against Hadoop 3.3.0-SNAPSHOT
Review comment:
nit: we shouldn't be telling folks to build against non-released
versions of Apache Hadoop I think?
##########
File path: src/main/asciidoc/_chapters/developer.adoc
##########
@@ -397,28 +396,109 @@ mvn clean install -DskipTests
See the <<hbase.unittests.cmds,hbase.unittests.cmds>> section in
<<hbase.unittests,hbase.unittests>>
[[maven.build.hadoop]]
-==== Building against various hadoop versions.
+==== Building against various Hadoop versions
+
+HBase supports building against Apache Hadoop versions: 2.y and 3.y (early
release artifacts).
+Exactly which version of Hadoop is used by default varies by release branch.
See the section
+<<hadoop,Hadoop>> for the complete breakdown of supported Hadoop version by
HBase release.
+
+The mechanism for selecting a Hadoop version at build time is identical across
all releases. Which
+version of Hadoop is default varies. We manage Hadoop major version selection
by way of Maven
+profiles. Due to the peculiarities of Maven profile mutual exclusion, the
profile that builds
+against a particular Hadoop version is activated by setting a property, *not*
the usual profile
+activation. Hadoop version profile activation is summarized by the following
table.
+
+.Hadoop Profile Activation by HBase Release
+[cols="3*^.^", options="header"]
+|===
+| | Hadoop2 Activation | Hadoop3 Activation
+| HBase 1.3+ | _active by default_ | `-Dhadoop.profile=3.0`
+| HBase 3.0+ | _not supported_ | _active by default_
+|===
+
+[WARNING]
+====
+Please note that where a profile is active by default, `hadoop.profile` must
NOT be provided.
+====
+
+Once the Hadoop major version profile is activated, the exact Hadoop version
can be
+specified by overriding the appropriate property value. For Hadoop2 versions,
the property name
+is `hadoop-two.version`. With Hadoop3 versions, the property name is
`hadoop-three.version`.
-HBase supports building against Apache Hadoop versions: 2.y and 3.y (early
release artifacts). By default we build against Hadoop 2.x.
+.Example 1, Building HBase 1.7 against Hadoop 2.10.0
-To build against a specific release from the Hadoop 2.y line, set e.g.
`-Dhadoop-two.version=2.6.3`.
+For example, to build HBase 1.7 against Hadoop 2.10.0, the profile is set for
Hadoop2 by default,
+so only `hadoop-two.version` must be specified:
[source,bourne]
----
-mvn -Dhadoop-two.version=2.6.3 ...
+git checkout branch-1
+mvn -Dhadoop-two.version=2.10.0 ...
----
-To change the major release line of Hadoop we build against, add a
hadoop.profile property when you invoke +mvn+:
+.Example 2, Building HBase 2.3 against Hadoop 3.3.0-SNAPSHOT
Review comment:
this is where it's problematic that our ref guide is both the resource
for downstream users of HBase and the development community of HBase. Can we
make this "build against a different major release line of hadoop" use a
released version? and then belwo when we talk about development versions
include a note that the instructions are for folks subscribed to dev@hbase
working on development of the project?
##########
File path: src/main/asciidoc/_chapters/developer.adoc
##########
@@ -397,28 +396,109 @@ mvn clean install -DskipTests
See the <<hbase.unittests.cmds,hbase.unittests.cmds>> section in
<<hbase.unittests,hbase.unittests>>
[[maven.build.hadoop]]
-==== Building against various hadoop versions.
+==== Building against various Hadoop versions
+
+HBase supports building against Apache Hadoop versions: 2.y and 3.y (early
release artifacts).
+Exactly which version of Hadoop is used by default varies by release branch.
See the section
+<<hadoop,Hadoop>> for the complete breakdown of supported Hadoop version by
HBase release.
+
+The mechanism for selecting a Hadoop version at build time is identical across
all releases. Which
+version of Hadoop is default varies. We manage Hadoop major version selection
by way of Maven
+profiles. Due to the peculiarities of Maven profile mutual exclusion, the
profile that builds
+against a particular Hadoop version is activated by setting a property, *not*
the usual profile
+activation. Hadoop version profile activation is summarized by the following
table.
+
+.Hadoop Profile Activation by HBase Release
+[cols="3*^.^", options="header"]
+|===
+| | Hadoop2 Activation | Hadoop3 Activation
+| HBase 1.3+ | _active by default_ | `-Dhadoop.profile=3.0`
+| HBase 3.0+ | _not supported_ | _active by default_
+|===
+
+[WARNING]
+====
+Please note that where a profile is active by default, `hadoop.profile` must
NOT be provided.
+====
+
+Once the Hadoop major version profile is activated, the exact Hadoop version
can be
+specified by overriding the appropriate property value. For Hadoop2 versions,
the property name
+is `hadoop-two.version`. With Hadoop3 versions, the property name is
`hadoop-three.version`.
-HBase supports building against Apache Hadoop versions: 2.y and 3.y (early
release artifacts). By default we build against Hadoop 2.x.
+.Example 1, Building HBase 1.7 against Hadoop 2.10.0
-To build against a specific release from the Hadoop 2.y line, set e.g.
`-Dhadoop-two.version=2.6.3`.
+For example, to build HBase 1.7 against Hadoop 2.10.0, the profile is set for
Hadoop2 by default,
+so only `hadoop-two.version` must be specified:
[source,bourne]
----
-mvn -Dhadoop-two.version=2.6.3 ...
+git checkout branch-1
+mvn -Dhadoop-two.version=2.10.0 ...
----
-To change the major release line of Hadoop we build against, add a
hadoop.profile property when you invoke +mvn+:
+.Example 2, Building HBase 2.3 against Hadoop 3.3.0-SNAPSHOT
Review comment:
I like that last proposed edit.
How much of a problem telling folks to use unreleased artifacts is depends
on the winds of ASF policy vs spirit stuff. So I'd rather avoid getting near
the morass
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
[email protected]
