src/site/apt/dev/release.apt

~~ $Id$
~~
~~ Licensed to the Apache Software Foundation (ASF) under one
~~ or more contributor license agreements.  See the NOTICE file
~~ distributed with this work for additional information
~~ regarding copyright ownership.  The ASF licenses this file
~~ to you under the Apache License, Version 2.0 (the
~~ "License"); you may not use this file except in compliance
~~ with the License.  You may obtain a copy of the License at
~~
~~ http://www.apache.org/licenses/LICENSE-2.0
~~
~~ Unless required by applicable law or agreed to in writing,
~~ software distributed under the License is distributed on an
~~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
~~ KIND, either express or implied.  See the License for the
~~ specific language governing permissions and limitations
~~ under the License.
~~
         -----------
         Release Process
         -----------

Tiles Release Process

  Here you will find the steps to create releases for Tiles.

Prerequisites

  To create a release you have to install:
  
  * {{{http://java.sun.com/j2se/1.5.0/}Java 5.0}}. If you are using a newer
  version of Java, it is suggested to <<change JAVA_HOME environment variable>>
  when calling Maven, so it points to an instance of Java 5.0;
  
  * {{{http://maven.apache.org/}Maven 2}};
  
  * {{{http://www.gnupg.org/}GnuPG}};
  
  * {{{http://www.openssh.com/}OpenSSH}};
  
  * {{{http://www.graphviz.org/}GraphViz}}: use version 2.8. See
  {{{building.html}building Tiles}} for the reason of not using the latest
  version.

One-time operations

  These operations need to be performed only one time.

* Create and publish your GPG key

  To create a GPG key, follow the
  {{{http://maven.apache.org/developers/release/pmc-gpg-keys.html}guidelines}}
  from Maven team. Include it in:

-------------------------------------
https://svn.apache.org/repos/asf/tiles/site/KEYS
-------------------------------------

  Publish your GPG key in a PGP key server, such as
  {{{http://pgp.mit.edu/} MIT Keyserver}}.

* Create and upload yout SSH key

  * Generate your SSH key (in this case we will use DSA encryption):

---------------------------------
ssh-keygen -t dsa
---------------------------------

  * Copy your public key to the server:

--------------------------------------
scp ~/.ssh/id_dsa.pub user@people.apache.org:.ssh/authorized_keys
--------------------------------------

  * Try to login:

---------------------------------
ssh user@people.apache.org
---------------------------------

  If it does not ask you a password, everything is ok.

Repeatable operations

  These steps must be performed <<for each>> release.

* Remove snapshot repositories

  Snapshot repositories (for libraries and plugins) should be removed from the
  main POM before a release. The problem is that a system behind a corporate
  firewall/white list cannot access to the snapshot repository URL, thus giving
  an error.

* Prepare the release tag

  To prepare the release Subversion tag, check out the branch/trunk from where
  you are preparing the release and type:

-----------------------------------
mvn release:prepare -Dusername=YOUR_SVN_USER -Dpassword=YOUR_SVN_PASSWORD
-----------------------------------

  The plugin interactively will ask you the version to release, the Subversion
  tag to use and the next snapshot version. It is reccomended to use the tag:
  <<tiles-X.X.X>>.

* Check-out and install the release

  Due to an {{{https://issues.apache.org/struts/browse/TILES-149}open bug}}, it
  is needed to check out and install, through <<<mvn install>>>, the tag;
  otherwise the release process fails.

* Perform the Release

  To perform the release, i.e. creating and deploying Maven artifacts, use:

-----------------------------------
mvn -Prelease -Darguments="-Prelease,j4" release:perform
-----------------------------------

* Digest and upload assemblies

  * Go into the release assembly target directory:

-----------------------------------
cd target/checkout/assembly/target/assembly/out
-----------------------------------

  * Create MD5 and SHA1 files for each files (including ASC files). You can do
  it with this simple shell script:

-----------------------------------
#!/bin/sh

for fileitem in *
do
  openssl md5 < $fileitem > $fileitem.md5
  openssl sha1 < $fileitem > $fileitem.sha1
done
-----------------------------------

  * Upload everything to the build site:
  
-----------------------------------
scp * user@people.apache.org:/www/people.apache.org/builds/tiles/${version}
-----------------------------------

* Release the JIRA version

  * In JIRA go to the version that you want to release and release it.
  
  * Create a new version, if it has not been done before.
  
  * Create the release notes and <<write down the link>> that it uses.

* Send announcement for the test build

  In <<developers mailing list>> send an announcement for the test build:

-----------------------------------
Subject: [ANNOUNCE] Tiles ${version} test build available

The test build of Tiles ${version} is available.


No determination as to the quality ('alpha,' 'beta,' or 'GA') of Tiles
${version} has been made, and at this time it is simply a "test build". We
welcome any comments you may have, and will take all feedback into
account if a quality vote is called for this build.

Release notes:

* ${jira.release.notes}

Distribution:

 * http://people.apache.org/builds/tiles/${version}/

Maven 2 staging repository:

 * http://people.apache.org/builds/tiles/${version}/m2-staging-repository/

A vote regarding the quality of this test build will be initiated
within the next couple of days.
-----------------------------------

* Call for a vote

  A few days after the test build announcement, call for a vote in
  <<developers mailing list>>.

-----------------------------------
Subject: [VOTE] ${version} Release Quality

The Tiles ${version} test build has been available since ${testBuildDate}.

Release notes:

* ${jira.release.notes}

Distribution:

 * http://people.apache.org/builds/tiles/${version}/

Maven 2 staging repository:

 * http://people.apache.org/builds/tiles/${version}/m2-staging-repository/

If you have had a chance to review the test build, please respond with
a vote on its quality:

 [ ] Leave at test build
 [ ] Alpha
 [ ] Beta
 [ ] General Availability (GA)


Everyone who has tested the build is invited to vote. Votes by PMC
members are considered binding. A vote passes if there are at least
three binding +1s and more +1s than -1s.
-----------------------------------

* Post-vote operations

  After a vote is finished, and it has been decided that is
  <<at least of alpha quality>>, there is the need of a post-vote process.

** Move artifacts

  * Move Maven artifacts to the rsync repository. To do it there is an
  {{{https://svn.apache.org/repos/asf/maven/plugins/trunk/maven-stage-plugin/}<<experimental stage plugin>>}}
  to help in the process (WARNING: not tested yet!).
  Merge the staging repository with the rsync repository:

------------------------------------------
mvn stage:copy -Dsource="http://people.apache.org/builds/tiles/${version}/m2-staging-repository/"
-Dtarget="scp://people.apache.org/www/people.apache.org/repo/m2-ibiblio-rsync-repository" -Dversion=${version}
------------------------------------------

  * Move assemblies to the Apache distribution mirrors:

-------------------------------------------
ssh user@people.apache.org

cd /www/people.apache.org/builds/tiles/${version}
mkdir /www/www.apache.org/dist/tiles/v${version}/
cp * /www/www.apache.org/dist/tiles/v${version}/
-------------------------------------------

  * Upload the <<<KEYS>>> file to the Apache mirrors:

-------------------------------------------
scp KEYS user@people.apache.org:/www/www.apache.org/dist/tiles/v${version}/
-------------------------------------------

** Update the site

  * Wait 24 hours to let the mirror sync to the release and then update the
  site. In particular you have to update the index and the download pages:

------------------------------------------------
https://svn.apache.org/repos/asf/tiles/site/src/site/xdoc/index.xml
https://svn.apache.org/repos/asf/tiles/site/src/site/apt/download.apt
------------------------------------------------

  Build and publish the site:

--------------------------------------
mvn site
mvn site:deploy
--------------------------------------

** Send announcement

  Finally, send an an announcement to the <<users>> and <<developers mailing
  list>>:

--------------------------------------
Subject: [ANNOUNCE] Tiles ${version} ${quality} released

The Apache Tiles team is pleased to announce the release of Tiles ${version}
${quality}.

Tiles ${version} is available in a binary and a source distribution.

http://tiles.apache.org/download.html

It is also available in the central Maven repository under Group ID
"org.apache.tiles".

The 2.0.x series of the Apache Tiles framework has a minimum
requirement of the following specification versions:

* Java Servlet 2.4 and JavaServer Pages (JSP) 2.0
* Java Standard Edition (Java SE) 1.5

The release notes are available online at:

* ${jira.release.notes}

Please feel free to test the distribution and post your comments to
the user list, or, if appropriate, file a ticket with JIRA.
--------------------------------------

  <<You have finished!>>