HBASE-11915 Document and test 0.94 -> 1.0.0 update

src/main/docbkx/configuration.xml

@@ -671,6 +671,14 @@ Index: pom.xml
       </section>
     </section>
     <!--  hadoop -->
+    <section xml:id="zookeeper.requirements">
+      <title>ZooKeeper Requirements</title>
+      <para>ZooKeeper 3.4.x is required as of HBase 1.0.0. HBase makes use of the
+        <methodname>multi</methodname> functionality that is only available since 3.4.0
+        (The <property>useMulti</property> is defaulted true in HBase 1.0.0).
+        See <link href="https://issues.apache.org/jira/browse/HBASE-12241">HBASE-12241 The crash of regionServer when taking deadserver's replication queue breaks replication</link>
+        and <link href="https://issues.apache.org/jira/browse/HBASE-6775">Use ZK.multi when available for HBASE-6710 0.92/0.94 compatibility fix</link> for background.</para>
+    </section>
   </section>
 
   <section

src/main/docbkx/upgrading.xml

@@ -85,15 +85,19 @@
                 binary with a 0.94.6 binary. </para>
         </section>
     </section>
-    <section
+    <section xml:id="upgrade1.0">
-        xml:id="upgrade1.0">
         <title>Upgrading from 0.98.x to 1.0.x</title>
-        <para>A rolling upgrade from 0.98.x to 1.0.x works (TODO: Verify!!!!). The two versions are not binary
+        <para>In this section we first note the significant changes that come in with 1.0.0 HBase and then
-            compatible.</para>
+          we go over the upgrade process.  Be sure to read the significant changes section with care
+          so you avoid surprises.
+        </para>
         <section xml:id="upgrade1.0.changes">
             <title>Changes of Note!</title>
             <para>In here we list important changes that are in 1.0.0 since 0.98.x., changes you should
             be aware that will go into effect once you upgrade.</para>
+            <section xml:id="zookeeper.3.4"><title>ZooKeeper 3.4 is required in HBase 1.0.0</title>
+              <para>See <xref linkend="zookeeper.requirements" />.</para>
+            </section>
             <section xml:id="upgrade1.0.hbase.bucketcache.percentage.in.combinedcache">
                 <title>hbase.bucketcache.percentage.in.combinedcache configuration has been REMOVED</title>
                 <para>You may have made use of this configuration if you are using BucketCache.
@@ -114,6 +118,19 @@
                 </para>
           </section>
         </section>
+        <section xml:id="upgrade1.0.rolling.upgrade">
+          <title>Rolling upgrade from 0.98.x to HBase 1.0.0</title>
+          <para>TODO</para>
+        </section>
+        <section xml:id="upgrade1.0.from.0.94">
+          <title>Upgrading to 1.0 from 0.94</title>
+          <para>You cannot rolling upgrade from 0.94.x to 1.x.x.  You must stop your cluster,
+            install the 1.x.x software, run the migration described at <xref linkend="executing.the.0.96.upgrade" />
+            (substituting 1.x.x. wherever we make mention of 0.96.x in the section below),
+            and then restart.  Be sure to upgrade your zookeeper if it is a version less than the required 3.4.x.
+          </para>
+
+        </section>
     </section>
 
     <section
@@ -142,11 +159,12 @@
     <section
         xml:id="upgrade0.96">
         <title>Upgrading from 0.94.x to 0.96.x</title>
-        <subtitle>The Singularity</subtitle>
+        <subtitle>The "Singularity"</subtitle>
         <note><title>HBase 0.96.x was EOL'd, September 1st, 2014</title><para>
             Do not deploy 0.96.x  Deploy a 0.98.x at least.
             See <link xlink:href="https://issues.apache.org/jira/browse/HBASE-11642">EOL 0.96</link>.
         </para></note>
+
         <para>You will have to stop your old 0.94.x cluster completely to upgrade. If you are
             replicating between clusters, both clusters will have to go down to upgrade. Make sure
             it is a clean shutdown. The less WAL files around, the faster the upgrade will run (the
@@ -154,9 +172,10 @@
             process). All clients must be upgraded to 0.96 too. </para>
         <para>The API has changed. You will need to recompile your code against 0.96 and you may
             need to adjust applications to go against new APIs (TODO: List of changes). </para>
-        <section>
+        <section xml:id="executing.the.0.96.upgrade">
             <title>Executing the 0.96 Upgrade</title>
             <note>
+              <title>HDFS and ZooKeeper must be up!</title>
                 <para>HDFS and ZooKeeper should be up and running during the upgrade process.</para>
             </note>
             <para>hbase-0.96.0 comes with an upgrade script. Run