poi/src/documentation/release-guide.txt

# 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.


             ==============================
                   POI Release Guide
             ==============================


(I) Prerequisites

   1. You should read the <a href="http://apache.org/dev/release.html">Apache Release FAQ</a>
   2. You must have shell access to people.apache.org
   3. Release manager must have his public key appended to the KEYS file checked in to SVN and the key published on one of the public key servers.
      More info can be found here: <a href="http://www.apache.org/dev/release-signing.html">http://www.apache.org/dev/release-signing.html</a>
   4. You must have <a href="java.sun.com">JDK 1.5</a>
   5. You must have the following utilities installed on your local machine and available in your path:
          * <a href="www.openssh.com">ssh</a>
          * <a href="www.gnupg.org">gnupg</a>
          * <a href="www.openssl.org">openssl</a>
      For Windows users, install Cygwin and make sure you have the above utilities
   6. The POI build system requires two components to perform a build
          * <a href="ant.apache.org">Ant</a>  
          * <a href="http://forrest.apache.org/">Forrest</a>. 
  POI 3.0.2 and 3.1 were built using Ant 1.6.2 and Forrest 0.5

   7. Before building, you should run the "rat-check" build task, which
      uses <a href="http://incubator.apache.org/rat/">Apache Rat</a>
      to check the source tree for files lacking license headers. Files
      without headers should be either fixed, or added to the exlude list


(II) Making release artefacts
  1. Update version id in build.xml
{code:xml}
  <property name="version.id" value="3.1-beta1"/>
{code}


  1a Check file permissions in SVN. 
 There can be  files in the SVN tree marked executable (have the
 svn:executable property set), but which should not be. Checking them out will cause 
 the executable bit to be set for them on filesystems which support it. 
 The flag can be removed in batch using
 
$ svn pd 'svn:executable' $(find -name .svn -prune -or -type f ! -name \*.sh \
 -print0 | xargs -0 svn pg 'svn:executable' | cut -d ' ' -f 1)


  2. Tag current version. Include the current revision number in the comment

{code}
$ svn cp https://svn.apache.org/repos/asf/poi/trunk \
https://svn.apache.org/repos/asf/poi/tags/$TAG \
-m "tag r649911 as 3.1-beta1"
{code}

where $TAG is the release tag, for example, REL_3_1_BETA1

  3. Checkout the tagged version
{code}
cd tags
svn checkout https://svn.apache.org/repos/asf/poi/tags/$TAG
{code}

  4. Merge (if required)

{code}
cd $TAG
$ svn merge https://svn.apache.org/repos/asf/poi/tags/$TAG \
https://svn.apache.org/repos/asf/poi/trunk
{code}

  5. Start a new section in status.xml. 

  6. Build as if the vote had passed. The build date must be +7 days from current.
{code}
ant build
{code}

where $TAG is the release tag specified in build.xml in the version.id property, $DATE is the release date (typically +7 days from the actual build date). 

  7. Signing the release artifacts:
{code}
cd build/dist
./multisign.sh

   8. Upload to your area at people.apache.org, e.g. public_html/poi

Make sure that the all files have read permission. 

 (III) After the vote:

Log-in on people.apache.org

1. Go to ~/POI-3.1-BETA1

zap previous version first.

{code}
cd ~/POI-3.1-BETA1/main
{code}

BETA and ALPHA releases:

{code}
cp *-src-* /www/www.apache.org/dist/poi/dev/src
cp *-bin-* /www/www.apache.org/dist/poi/dev/bin
{code}

FINAL release:
{code}
cp *-src-* /www/www.apache.org/dist/poi/release/src
cp *-bin-* /www/www.apache.org/dist/poi/release/bin
{code}

deploy Maven artifacts
{code}
cd build/dist
./mvn-deploy.sh
{code}

2. Make sure that the files are owned by the unix group apcvs and that they are writable by this group. 

3. Wait for the distributions to appear on your favourite mirror

4. test maven
create a simple project and make sure the release artifacts are accessible by maven:

{code}
$ mvn archetype:create -DgroupId=org.apache.poi.scratchpad -DartifactId=maven-test
cd maven-test
{code}
edit pom.xml and add the release artefacts to the project dependencies: 

{code:xml}
    <dependency>
      <groupId>org.apache.poi</groupId>
      <artifactId>poi</artifactId>
      <version>3.1-beta1</version>
    </dependency>
    <dependency>
      <groupId>org.apache.poi</groupId>
      <artifactId>poi-scratchpad</artifactId>
      <version>3.1-beta1</version>
    </dependency>
{code}

{code}
mvn compile 
{code}

You should see [INFO] BUILD SUCCESSFUL in the end.

5. Don't forget to upload the latest version of the site and javadocs

6. Send announcements:
 - to poi-user and poi-dev lists
 - to announcement@apache.org, announcements@jakarta.apache.org

Note, announcements should be sent from your @apache.org e-mail address.