Forrest Release Process
                          ============================


This file documents the steps a release manager should follow when making a new
Forrest release.

Preparations
------------

 - Ensure that as many PMC members as possible have their PGP keys in
   the KEYS file.

 - Edit module.xml and replace the '-dev' text with '':
    ...
    <project name="xml-forrest">
        <version fix="0" major="0" minor="4" tag="-dev"/>

 - Edit status.xml, remove the -dev from the current <release> tag, and set the
   date.  Also add a new <release> for development on the next version  e.g.
   from:

    <release version="0.4-dev" date="unreleased">
      ...
 
   to:

    <release version="0.5-dev" date="unreleased">
    </release>
    <release version="0.4" date="2002-02-13">
      ...

 - Edit src/core/forrest.build.xml to update the version tag which is
   embedded in the Ant script:

    |                 Forrest Site Builder                  |
    |                        0.4-dev                        |
                                ^^^^

 - Create a new file, etc/RELEASE-NOTES-x.y.txt, where x.y is the version
   currently being released.  It is best to copy an earlier RELEASE-NOTES file,
   to keep a common layout.
   In this file, provide a summary of changes, and check for general accuracy.
   Scan the status.xml/changes and the Roadmap via the issues tracker,
   to find the important issues.

 - Check out a fresh copy from SVN to make sure you have no local modifications,
   especially those that might be hidden by svn:ignore settings.

 - Run 'build release-dist' to generate the distributions.
   - Two archives are created: apache-forrest-X.Y.tar.gz apache-forrest-X.Y.zip

 - Repeat that on a Windows machine.
   - Use the .tar.gz from the UNIX machine and .zip from the Windows machine.
   - In that way, SVN will ensure correct line-endings on all text files.

 - Test the actual distribution on various platforms.
   - Put the tar.gz and the zip file at a committers' Apache website.
   - Ask all developers to download and test (command-line, run, and webapp).
   - Follow the actual user instructions.
   - Use it to build some difficult sites.
   - Ensure that the compressed archives will unpack correctly.

 - Understand how to sign releases and generate MD5 and PGP.
   http://wiki.apache.org/old/SigningReleases

 - If everything looks okay, tag CVS with 'cvs tag FORREST_xy', where 'xy' is a
   compact form of the version (eg 04, 041, 05).  Run 'cvs log build.xml' to
   see existing tags.

FIXME: update for SVN.

 - For 0.x releases, create a maintenance branch in CVS with 'cvs tag -b
   FORREST_xy_BRANCH'.

  Note: if you realise you tagged too soon, tags can be updated with 
  'cvs tag -F <tag>'.  See 'cvs --help tag' for more info.


Upload and announcement
-----------------------

 - Upload the binaries, the source archives, the *.asc and *.md5 files,
   **and the RELEASE-NOTES**
   to www.apache.org at /www/www.apache.org/ dist/forrest/
   Each PMC member has a server account and belongs to the forrest group.
   The process is documented at http://cvs.apache.org/~bodewig/mirror.html

 - Edit the forrest/src/documentation/content/xdocs/mirrors.ihtml
 - Edit the Forrest home page in the "News and events" section.
 - Rebuild the Forrest website as normal.

 - Wait for the various mirrors to pick up the new files.
   This has been known to take up to 10 hours. Test it via 
   http://forrest.apache.org/mirrors.cgi

 - Edit xml-site/src/documentation/content/xdocs/news.xml and record the
   announcement, and then commit the new HTML to xml-site/targets/forrest
   Note that they still use forrest-0.5.1 to build their website.

 - Send announcement email.  Typically this is sent as:
   To: dev@forrest.apache.org, user@forrest.apache.org, announce@apache.org,
       announcements@xml.apache.org
   Subject: [Announce] Apache Forrest X.Y.Z
     !! Always refer them to the mirror facility
     !! Never mention the URL www.apache.org/ dist/ in email.
   Use the template at /etc/announcement.txt
   
See previous announcements:
0.2   http://marc.theaimsgroup.com/?l=xml-apache-announce&m=103746673310573
0.3   http://marc.theaimsgroup.com/?l=xml-apache-announce&m=104399934113331
0.4   http://marc.theaimsgroup.com/?l=jakarta-announce&m=104510734501302
0.5   http://marc.theaimsgroup.com/?l=xml-apache-announce&m=106352706005681
0.5.1 http://marc.theaimsgroup.com/?l=xml-apache-announce&m=106541447606765

 - Ask Jeff Turner to do the freshmeat announcement, or add you as an admin.
   http://freshmeat.net/projects/forrest/

Cleanups
--------

 - Edit module.xml, increment the version and add a -dev tag:

    <project name="xml-forrest">
        <version fix="0" major="0" minor="5" tag="-dev"/>

 - Edit src/core/forrest.build.xml and update the version:

    |                 Forrest Site Builder                  |
    |                          0.5                          |



All done!

Or perhaps not.. if you think of anything, please add it here.