how to do a release

BUILDING-RELEASES.adoc

@@ -0,0 +1,51 @@
+= How To Build Releases Using Maven Release Plugin and Nexus Repositories
+
+The following steps will tell you what you need to do in order to build a release for public consumption.
+
+Before you can do anything, you must ensure your Maven environment and project are configured property.
+
+1. Put your Maven public repository credentials in your ~/.m2/settings.xml file. For example, the Hawkular parent pom defines the public maven repository that we use for releases under the name "jboss-releases-repository", so in your settings.xml you will need something like this:
+
+<servers>
+  <server>
+    <id>jboss-releases-repository</id>
+    <username>your.maven.repository.username</username>
+    <password>your.maven.repository.password</password>
+  </server>
+</servers>
+
+2. Make sure your Maven project's main pom.xml defines an <scm> section with at least a <developerConnection> entry. Here's an example:
+
+  <scm>
+    <developerConnection>scm:git:git@github.com:hawkular/hawkular-alerts.git</developerConnection>
+  </scm>
+
+Once you make sure your Maven environment and project are properly configured as explained above, you can release your project's artifacts. The following steps will ensure you do all of the release build work on your local machine only. Only at the end will things be sent out to the remote git repository and the public maven repository. That way, if something fails along the way, you can delete your local git repository and git clone a fresh clean copy to try again.
+
+1. Make sure your project builds. If your project inherits from the hawkular parent POM, you can build with -Prelease to make it better resemble the release build (But it won't be exact. For example, the Maven release plugin performs stricter Javadoc checking - so building with -Prelease might pass, but your Maven release plugin build may still fail).
+
+mvn clean install -Prelease
+
+2. Prepare your release. Once you execute this, you will be asked for version strings to use for your release and your next development snapshot version. You can usually just hit "enter" on all the questions to simply take the defaults. Once this step completes, you will have a release tag created in your local git repository and your pom.xml files will be moved to your next development snapshot version.
+
+mvn clean release:clean release:prepare -DpushChanges=false
+
+3. Now perform your release build. This forks a separate build and performs the release compile and assembly as well as performing strict javadoc checks. It also builds source and javadoc jars when appropriate. After this is complete, your artifacts will be uploaded to a Nexus staging repository that has been created for you.
+
+mvn release:perform -DlocalCheckout=true
+
+**Note that if this step fails, you will need to go into the Nexus UI and drop the unfinished staging repository that was created for it (see below for how to find your staging repository).** 
+
+4. Push your git local repo to the git remote repo. Make sure you tell it to push tags.
+
+git push origin master --tags
+
+**Note that had you not passed in -DpushChanges=false in step 2 and -DlocalCheckout=true in step 3, you can skip this step 4. The Maven plugin will push everything for you along the way. The problem is if you didn't use those -D settings and step 2 or 3 fail, you will have commits and tags up in your remote maven repo that you will have to either remove or workaround.
+
+5. Now publish your Nexus snapshot repository by doing a "release"
+
+* Go to https://repository.jboss.org/nexus/#stagingRepositories and log in as a user with the appropriate permissions.
+* Sort the list by the "Updated" column so the newest staging repositories are at the top of the list.
+* Find your staging repository that was created for your release. You will have to select each row and look at the Summary tab at the bottom. Find the one with you as the "Owner". Further verify by looking at the "Content" tab - make sure the artifacts in that repository are what you expect.
+* Once you find your staging repository, select it and click the "Close" button.
+* Once the staging repository is closed successfully, click the "Release" button. By default your staging repository will be dropped and your content will be moved to the public repository. At that point, Nexus will serve your artifacts via the public repository to anyone that wants to download them.