Mailing-List: contact commits-help@ace.apache.org; run by ezmlm
Precedence: bulk
Reply-To: dev@ace.apache.org
Content-Type: text/plain; charset="utf-8"
MIME-Version: 1.0
Content-Transfer-Encoding: 7bit
Subject: svn commit: r1727564 - in /ace/trunk/build: README README.md
Date: Fri, 29 Jan 2016 12:26:17 -0000
To: commits@ace.apache.org
From: jawi@apache.org
Message-Id: <20160129122617.17E893A0185@svn01-us-west.apache.org>

Author: jawi
Date: Fri Jan 29 12:26:16 2016
New Revision: 1727564

URL: http://svn.apache.org/viewvc?rev=1727564&view=rev
Log:
Updated the release README:

- properly format it using MarkDown;
- in progress of correcting all steps for the ACE release process.


Added:
    ace/trunk/build/README.md
      - copied, changed from r1727563, ace/trunk/build/README
Removed:
    ace/trunk/build/README

Copied: ace/trunk/build/README.md (from r1727563, ace/trunk/build/README)
URL: http://svn.apache.org/viewvc/ace/trunk/build/README.md?p2=ace/trunk/build/README.md&p1=ace/trunk/build/README&r1=1727563&r2=1727564&rev=1727564&view=diff
==============================================================================
--- ace/trunk/build/README (original)
+++ ace/trunk/build/README.md Fri Jan 29 12:26:16 2016
@@ -1,118 +1,151 @@
+# Apache Ace Release Guide
+ 
+This document describes how to do a source release. It is based on the Apache
+Development [Release FAQ] [1].
 
+## Prerequisites
 
+To create a release you must:
 
-Apache Ace Release Guide 
-This document describes how to do a source release. It is based on the Release FAQ [1]
+  * Have Subversion installed on your system;
+  * Have gpg installed on your system;
+  * Have a public key added to the [KEYS file] [2]; 
+  * If you are using an http proxy, configure the following:
 
-Prerequisites
-=============
+    export GRADLE_OPTS="-Dhttps.proxyHost=www.somehost.org -Dhttps.proxyPort=8080"
 
-To create a release you must:
+Before you can start staging a release candidate, you must:
 
-* Have Subversion installed on your system;
-* Have gpg installed on your system;
-* Have a public key added to the keys file, and committed to [2] 
-* If you are using an http proxy, configure the following:
+  * Make sure there are no dependencies on snapshots/unreleased versions;
+  * Increment the version parameter in build/build.gradle, if not already 
+    done, and commit;
+  * Under bndtools, release (only) the bundles that needs to be released
+    (using "Release workspace bundles" menu);
+  * Create a tagged version of the sources in preparation of the release
+    candidate.
 
-  export GRADLE_OPTS="-Dhttps.proxyHost=www.somehost.org -Dhttps.proxyPort=8080"
 
-Before you can start staging a release candidate, you must:
+## Release only the necessary bundles
 
-* make sure there are no dependencies on snapshots/unreleased versions;
-* increment the version parameter in build/build.gradle, if not already done, and commit.
-* under bndtools, release (only) the bundles that needs to be released (using "Release workspace bundles" menu).
-* create a tagged version of the sources in preparation of the release candidate.
+Click on the Bndtools "Release workspace bundles", and release the bundles that
+have been modified and need to be released.
 
-Release only the necessary bundles
-===================================
+Do *not* release other *unmodified* bundles.
 
-Click on the bndtools "Release workspace bundles", and release the bundles that have been modified and need to be released.
-Don't release other unmodified bundles.
-Once done, under the shell prompt, go to the "cnf/releaserepo/" directory, svn remove the previous old released bundles,
-and svn add the new released bundles.
-refresh the repositories under bndtools, and commit.  
+Once done, under the shell prompt, go to the `cnf/releaserepo/` directory, run
+`svn remove` to remove the previous (old) versions of the released bundles, and
+run `svn add` to add the just released bundles.
 
-Create a tagged version
-=======================
+Refresh the repositories using Bndtools, and commit all changes.  
 
-Creating a tagged version of the sources can be done directly through svn (replace r<n> by the actual release number, like "r1"):
 
-svn copy https://svn.apache.org/repos/asf/ace/trunk https://svn.apache.org/repos/asf/ace/releases/<version> -m "Release of Apache Ace <version>"
+## Create a tagged version
 
-Staging a release candidate
-===========================
+Creating a tagged version of the sources can be done directly through svn
+(replace `r<n>` by the actual release number, like "r1"):
 
-Staging a release starts by checking out a tagged version of the sources (replace <version> by the actual release version, like "2.0.0"):
+    v=<version> \
+      svn copy https://svn.apache.org/repos/asf/ace/trunk \
+      https://svn.apache.org/repos/asf/ace/releases/$v \
+      -m "Release of Apache Ace $v"
 
-svn co https://svn.apache.org/repos/asf/ace/releases/<version> apache-ace-<version>
 
-The next step is to build/test the software and create the release/staging/ directory (where the source/jars will be packaged):
-(replace <version> by the actual release number, like "2.0.0")
+## Staging a release candidate
 
-Use a Java6 JDK
+Staging a release starts by checking out a tagged version of the sources 
+(again, replace `<version>` by the actual release version, like "2.0.0"):
 
-$ cd apache-ace-<version>
-$ ./gradlew rat 
-$ ./gradlew build
+    v=<version> \
+      svn co https://svn.apache.org/repos/asf/ace/releases/$v apache-ace-$v
 
-create the staging:
+The next step is to build/test the software and create the `release/staging/`
+directory (where the source/jars will be packaged, again, replace `<version>`
+by the actual release number, like "2.0.0"):
 
-$ ./gradlew makeStaging (this will create ./build/staging/ directory containing the signed release archives)
+Use Java 7 as JDK
 
-You can upload the archives and the signatures to our development area, which we use to stage this release candidate. This development area can be found at 
-https://dist.apache.org/repos/dist/dev/ace and adding files to it can be done using "svnpubsub" which is taken care of by the following target:
+    $ cd apache-ace-<version>
+    $ ./gradlew rat
+    $ ./gradlew build runbundles
 
-$ ./gradlew commitToStaging
+Create the staging directory and artifacts (this will create `./build/staging/`
+directory containing the signed release archives):
 
-Voting on the release
-=====================
+    $ ./gradlew makeStaging
 
-Start a vote on the dev@ace.apache.org list, for example (be sure to replace <version> with the correct release number, like "1.0.0"):
+You can upload the archives and the signatures to our development area, which 
+we use to stage this release candidate. This development area can be found at 
+`https://dist.apache.org/repos/dist/dev/ace` and adding files to it can be done
+using "svnpubsub" which is taken care of by the following target:
 
->>>
-To: "Ace Developers List" <dev@ace.apache.org>
-Subject: [VOTE] Release of Apache Ace release r<n>
+    $ ./gradlew commitToStaging
 
-Hi,
 
-We solved N issues in this release:
-http://issues.apache.org/jira/...
+## Voting on the release
 
-There are still some outstanding issues:
-http://issues.apache.org/jira/...
+Start a vote on the `dev@ace.apache.org` list, for example (be sure to replace 
+`<version>` with the correct release number, like "1.0.0"):
 
-Staging repository:
-https://dist.apache.org/repos/dist/dev/ace/apache-ace-<version>/
+    To: "Ace Developers List" <dev@ace.apache.org>
+    Subject: [VOTE] Release of Apache Ace release r<n>
+    
+    Hi,
+    
+    We solved N issues in this release:
+    http://issues.apache.org/jira/...
+    
+    There are still some outstanding issues:
+    http://issues.apache.org/jira/...
+    
+    Staging repository:
+    https://dist.apache.org/repos/dist/dev/ace/apache-ace-<version>/
+    
+    You can use this UNIX script to download the release and verify the signatures:
+    http://svn.apache.org/repos/asf/ace/trunk/build/check_staged_release.sh
+    
+    Usage:
+    sh check_staged_ace_release.sh <version> /tmp/ace-staging
+    
+    This script, unlike the original check_staged_release.sh from Apache Felix,
+    will download staging artifacts from https://dist.apache.org/repos/dist/dev/ace
+    instead of http://repository.apache.org/content/repositories.
+    
+    Please vote to approve this release:
+    
+    [ ] +1 Approve the release
+    [ ] -1 Veto the release (please provide specific comments)
+    
+    This vote will be open for 72 hours.
 
-You can use this UNIX script to download the release and verify the signatures:
-http://svn.apache.org/repos/asf/ace/trunk/build/check_staged_release.sh
 
-Usage:
-sh check_staged_ace_release.sh <version> /tmp/ace-staging
+## Promoting the release:
 
-This script, unlike the original Felix check_staged_release.sh, will download staging from https://dist.apache.org/repos/dist/dev/ace instead of http://repository.apache.org/content/repositories.
+Move the artifacts from the development area to the final release location at 
+`https://dist.apache.org/repos/dist/release/ace` by invoking the following
+target:
 
+    $ ./gradlew promoteToRelease
 
-Please vote to approve this release:
+Notify the `dev@ace.apache.org` list about the successful promotion and notify
+the `users@ace.apache.org` list that a new release is available.
 
-[ ] +1 Approve the release
-[ ] -1 Veto the release (please provide specific comments)
+### Update the JIRA issues
 
-This vote will be open for 72 hours.
-<<<
+Close all issues in JIRA that were fixed as part of the release and create a 
+new version for the next release. This probably means that you need to rename
+the existing `next` version to the released version of ACE and recreate a new
+`next` version.
 
-Promoting the release:
-=====================
 
-Move the artifacts from the development area to the final release location at 
-https://dist.apache.org/repos/dist/release/ace by invoking the following target:
+## Cancelling the release
+
+To cancel the release for whatever reason, run:
 
-$ ./gradlew promoteToRelease
+    $ ./gradlew deleteFromStaging
 
-Cancelling the release
-======================
+And notify the `dev@ace.apache.org` list to make everybody aware of this. 
 
-$ ./gradlew deleteFromStaging
+## References
 
-[1] http://www.apache.org/dev/release.html
-[2] http://www.apache.org/dist/ace/KEYS
+[1]: http://www.apache.org/dev/release.html
+[2]: http://www.apache.org/dist/ace/KEYS