# 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>
   2a. You must have shell access to people.apache.org; and you should 
       have key-based authentication set up 
       (e.g. <a href="http://www.linuxproblem.org/art_9.html">how to</a>.
   2b. You must be a member of the committee group
   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 the Java JDK 1.6 installed and active (don't use newer
      ones for building the release)
   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
   6a. 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>. 
      Currently, Forrest needs to be 0.5.1, Ant 1.8+ should be fine

   6b. To deploy with Maven, you should have the latest stable Maven 2.x.
        POI 3.10-beta2 was deployed with Maven 2.2.1.

   6c. Ensure you can log in to https://repository.apache.org/ with your Apache
        credentials, and that you can see the "Staging Repositories" area on
        the left hand side.

   6d. Ensure your ~/.m2/settings.xml contains a server entry with your
        Apache credentials in, to be used for uploading. Something like:

<?xml version="1.0" encoding="UTF-8"?>
<settings>
  <servers>
    <server>
      <id>apache-releases</id>
      <username>MyApacheUsername</username>
      <password>mySecurePassw0rd</password>
    </server>
  </servers>
</settings>

   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

   8. Check file permissions are correct 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)

   9. Before building, ensure that the year in the NOTICE file is correct,
      and review any new or updated dependencies to ensure that if they
      required LICENSE or NOTICE updates then these were done.

  10. Ensure that the changelog is up to date

  11. Ensure that the KEYs files in the dist areas are up-to-date with the
      latest ones in svn:
      https://dist.apache.org/repos/dist/dev/poi/KEYS
      https://dist.apache.org/repos/dist/release/poi/KEYS


(II) Making release artefacts
  1. Update version id and rel in build.xml, for the version you are
     about to release as (might already be correct!)
{code:xml}
  <property name="version.id" value="3.12-beta1"/>
  <property name="version.rel" value="REL_3_12_BETA1"/>
{code}
{code:xml}
  <property name="version.id" value="3.12/>
  <property name="version.rel" value="REL_3_12_FINAL"/>
{code}

  2. Update the date in src/documentation/content/xdocs/status.xml with
     the expected release date, and create a commented out entry for the 
     next release. (Must be commented out, as there are no actions
     for it yet)

  3. Pin the documentation explicitly to the current version, rather
     than trunk. Run "svn up" to get the current version number, then
     edit the svn:externals property on src and add to the definition, eg

     documentation -r1496657 https://svn.apache.org/repos/asf/poi/site/src/documentation

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

{code}
$ TAG=REL_3_8_FINAL
$ TAG=REL_3_12_ALPHA5
$ 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

  5. On trunk, update "version.id" and "version.rel" to be the next version 
     in build.xml, and remove the version pinning on the documentation 
     external definition.

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

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

     Note that if there's set to be lots of merging, you may be best
     to create a branch for the release, then create tags from there
     rather than trunk

  8. Build as if the vote had passed. The build date must be +7 days from current.
{code}
# eg ant -DDSTAMP=20100924 dist
ant -DDSTAMP=YYYYMMDD dist
{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). 

  9. Sign and checksum the release artifacts:
{code}
cd build/dist
./multisign.sh
{code}

 10. Summarise key changes, and any backwards incompatible ones,
     in the partially auto-generated build/dist/RELEASE-NOTES.txt

 11. Upload to the dev svn dist repo, 
     https://dist.apache.org/repos/dist/dev/poi/ eg
     https://dist.apache.org/repos/dist/dev/poi/3.8-RC3/

How to upload:

{code}
svn co https://dist.apache.org/repos/dist/dev/poi
mkdir 3.8-RC3/
svn add 3.8-RC3
{code}

may need --force as in:
{code}
svn add 3.8-RC3 --force
{code}

then add .gz and .zip packages along with checksums and release notes.

 binaries should be in ./bin, sources in ./src sub-directories

8c. commit
After commit the files should be accessible at https://dist.apache.org/repos/dist/dev/poi/3.8-RC2/

8d. validate signatures

Check your signed files

{code}
find . -name "*.md5" -type f -execdir md5sum -c {} \;
find . -name "*.sha1" -type f -execdir sha1sum -c {} \;
find . -name "*.asc" -exec gpg --verify {} \;
{code}

 (III) Calling the vote:

   1. The release manager should call the vote
   2. Include the URL of the release artifacts
   3. Include the time for the vote to run
   4. Provide guidance on what needs to be checked
   5. Complete a tally, and send a result once the time has passed

 (IV) After the vote:

In the release area of the dist repo:
    https://dist.apache.org/repos/dist/release/poi/release/   (FINAL)
    https://dist.apache.org/repos/dist/release/poi/dev/       (Alpha/Beta)
Remove the previous release

Next, svn move the files from the /dist/dev/ area to the appropriate
/dist/release/ area

example:
$ svn rm -m "remove the previous release" \ 
    https://dist.apache.org/repos/dist/release/poi/dev/src
    https://dist.apache.org/repos/dist/release/poi/dev/bin

$ svn mv -m "move staging files to the release area" \
    https://dist.apache.org/repos/dist/dev/poi/bin \
    https://dist.apache.org/repos/dist/dev/poi/src/  \
    https://dist.apache.org/repos/dist/release/poi/dev/


deploy Maven artifacts, via the Nexus staging repository
{code}
cd build/dist
./mvn-deploy.sh
{code}

When the Maven upload has completed, log into https://repository.apache.org/
and go to the "Staging Repositories" area. Find the "orgapachepoi" entry, check
it has the right content, then Close the repository. When that completes, 
Release it.

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

3. Wait for the maven artifacts to appear on Maven Central, and ensure
   they work:

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-ooxml</artifactId>
      <version>3.11-beta1</version>
    </dependency>
    <dependency>
      <groupId>org.apache.poi</groupId>
      <artifactId>poi-scratchpad</artifactId>
      <version>3.11-beta1</version>
    </dependency>
{code}

edit src/main/java/Test.java and add this:

{code:java}
import org.apache.poi.ss.usermodel.Workbook;
import org.apache.poi.ss.usermodel.WorkbookFactory;

public class Test {}
{code}

{code}
mvn compile 
{code}

You should see [INFO] BUILD SUCCESSFUL in the end, which tells you that
the jars could be donwloaded fine.

4. Edit the website homepage and list the new release there. If a full release,
   remove older full releases and all beta releases. If a beta release, keep
   the last full release, and replace any other beta releases

5. Edit the website download page, and list the new release there. This should
   reference the checksums, so take care when updating

6. Build site using a recent version of Java 1.6 or 1.7 (must be after the fix
   for TA13-169A).
   Commit the site changes to svn, and publish live

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

8. Send announcements:
 - to poi-user and poi-dev lists
 - to announce@apache.org

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

9. Add a new project version in Bugzilla

10. If this is a final release, add it to the DOAP file too

11. Delete directory that held RC.

e.g.
{code}
svn delete -m "delete empty RC directory for 3.10-beta2" https://dist.apache.org/repos/dist/dev/poi/3.10-beta2-RC1
{code}
