Some more detail on publishing artifacts to maven repo (for Lars)

git-svn-id: https://svn.apache.org/repos/asf/hbase/trunk@1399109 13f79535-47bb-0310-9956-ffa450edef68

src/docbkx/developer.xml

@@ -179,28 +179,32 @@ mvn clean package -DskipTests
         <title>Adding an HBase release to Apache's Maven Repository</title>
         <para>Follow the instructions at
         <link xlink:href="http://www.apache.org/dev/publishing-maven-artifacts.html">Publishing Maven Artifacts</link> after
-        reading the below.
+        reading the below miscellaney.
         </para>
-        <para>You must use maven 3.0.x.
+        <para>You must use maven 3.0.x (Check by running <command>mvn -version</command>).
         </para>
         <para>Let me list out the commands I used first.  The sections that follow dig in more
         on what is going on.  In this example, we are releasing the 0.92.2 jar to the apache
         maven repository.
         <programlisting>
+  # First make a copy of the tag we want to release; presumes the release has been tagged already
+  # We do this because we need to make some commits for the mvn release plugin to work.
   853  svn copy -m "Publishing 0.92.2 to mvn"  https://svn.apache.org/repos/asf/hbase/tags/0.92.2 https://svn.apache.org/repos/asf/hbase/tags/0.92.2mvn
   857  svn checkout https://svn.apache.org/repos/asf/hbase/tags/0.92.2mvn
   858  cd 0.92.2mvn/
+  # Edit the version making it release version with a '-SNAPSHOT' suffix (See below for more on this)
   860  vi pom.xml
   861  svn commit -m "Add SNAPSHOT to the version" pom.xml
   862  ~/bin/mvn/bin/mvn release:clean
   863  ~/bin/mvn/bin/mvn release:perform
   865  ~/bin/mvn/bin/mvn release:prepare
-  866  # Answer questions and then ^C to kill the build
+  866  # Answer questions and then ^C to kill the build after the last question. See below for more on this.
   867  vi release.properties
-       # Change the references to trunk svn to be 0.92.2mvn
+       # Change the references to trunk svn to be 0.92.2mvn; the release plugin presumes trunk
        # Then restart the release:prepare -- it won't ask questions
        # because the properties file exists.
   868  ~/bin/mvn/bin/mvn release:prepare
+  # The apache-release profile comes from the apache parent pom and does signing of artifacts published
   869  ~/bin/mvn/bin/mvn release:perform  -Papache-release
        # When done copying up to apache staging repository,
        # browse to repository.apache.org, login and finish
@@ -208,10 +212,11 @@ mvn clean package -DskipTests
        # "Publishing Maven Artifacts.
         </programlisting>
         </para>
+        <para>Below is more detail on the commmands listed above.</para>
         <para>At the <command>mvn release:perform</command> step, before starting, if you are for example
         releasing hbase 0.92.2, you need to make sure the pom.xml version is 0.92.2-SNAPSHOT.  This needs
         to be checked in.  Since we do the maven release after actual release, I've been doing this
-        checkin into a particular tag that is a copy of the release rather than into the actual release tag.
+        checkin into a copy of the release tag rather than into the actual release tag itself (presumes the release has been properly tagged in svn).
         So, say we released hbase 0.92.2 and now we want to do the release to the maven repository, in svn, the 0.92.2
         release will be tagged 0.92.2.  Making the maven release, copy the 0.92.2 tag to 0.92.2mvn.
         Check out this tag and change the version therein and commit.
@@ -219,11 +224,12 @@ mvn clean package -DskipTests
         <para>
             Currently, the mvn release wants to go against trunk.  I haven't figured how to tell it to do otherwise
             so I do the below hack.  The hack comprises answering the questions put to you by the mvn release plugin properly,
-            then immediately control-C'ing the build.  You'll notice a release.properties in your build dir.  Review it.
+            then immediately control-C'ing the build after the last question asked as the build release step starts to run.
+            After control-C'ing it, You'll notice a release.properties in your build dir.  Review it.
             Make sure it is using the proper branch -- it tends to use trunk rather than the 0.92.2mvn or whatever
             that you want it to use -- so hand edit the release.properties file that was put under <varname>${HBASE_HOME}</varname>
             by the <command>release:perform</command> invocation.  When done, resstart the
-            <command>release:perform</command> invocation.
+            <command>release:perform</command>.
         </para>
         <para>Here is how I'd answer the questions at <command>release:prepare</command> time:
         <programlisting>What is the release version for "HBase"? (org.apache.hbase:hbase) 0.92.2: :
@@ -239,6 +245,10 @@ What is the new development version for "HBase"? (org.apache.hbase:hbase) 0.92.3
         not release.  See <link xlink:href="https://issues.apache.org/jira/browse/INFRA-4482">INFRA-4482 Why is my upload to mvn spread across multiple repositories?</link>.</para>
 
         <para xml:id="mvn.settings.file">Here is my <filename>~/.m2/settings.xml</filename>.
+        This is read by the release plugin.  The apache-release profile will pick up your
+        gpg key setup from here if you've specified it into the file.  The password
+        can be maven encrypted as suggested in the "Publishing Maven Artifacts" but plain
+        text password works too (just don't let anyone see your local settings.xml).
         <programlisting>&lt;settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0