*** Introduction ***

This document describes how to do a flexdock release.  It assumes the following
things:
  - versioned releases are done off of the HEAD of the trunk branch of the 
    project in CVS
  - there is an effective project freeze during the time of the release where 
    no one except those doing the release commit onto the trunk branch
  - all future development work is located on branches and will be merged to 
    trunk after the release is performed
  - if a problem is found shortly after the release, and future release work 
    has already been merged to trunk, a ..release (e.g. will be done by 
    creating a .. release branch, repeating the release with the new .. version
    number relative to that specific branch and once the files are released to 
    the server, merging the ..release fixes to the trunk branch. 

This may change in the future, but is a very simple release management approach
for the time being.


*** About Native Code ***

Currently, native code for a flexdock build is checked into the project.  For 
the time being we will trust that committers of C code check in updated 
linux-x86 and windows libraries when changing the C code.

Therefore, a releaser does not need to figure out how to build native code.

In the future we will add checks to the build process to ensure that the commit
timestamps of the native code libraries are newer.  This will help us detect 
the obvious case where someone updates the C code without updating the native 
code library


*** Diffing dirtrees/zips ***

The instructions below call for diffing of directory trees and/or zips.  You 
cannot just use diff to do this as you will need something that can recurse 
into zip/jar archives.  If you are release on Windows, then consider using 
BeyondCompare (it's got a try/buy license).  I'm not sure what UNIX tools are 
available yet, but will research to make ensure there's no reason not to follow
the directions below on UNIX system.


*** Instructions for Performing a Release ***

If at any point you run into problems and have to change code to do the 
release, restart at the first step (or at least make sure that all code is 
committed back to HEAD in the clean working copy you create in step 1).  We 
want this to be repeatable.

Note: the files located in the www directory are used by java.net to display 
the flexdock home page.  Since the contents of these pages are dependent upon
the release, these files will NOT be updated until after the new flexdock 
version are archived on the web site.

1) Create a clean CVS working copy from HEAD of trunk branch

2) Ensure that "version" property in build.xml is matches that for the 
   upcomping release.  If it does not,

    a) update build.xml to specify the proper version number in the "version"
       property
    b) test that you haven't broken the build.xml by doing a build and noting
       that the generated artifacts use the new version number in their file 
       names
    c) commit the build.xml with the updated version number to CVS

3) Test that you can run:

    a) ant clean
    b) ant dist

  and that the build dir contains:

    flexdock-[version].jar
    flexdock-[version]-src.zip
    dist/flexdock-[version].zip
    dist/flexdock-demo-[version].jar

4) Verify that the demo app runs and reports the correct version.  To do this 
   run:

    java -jar build/flexdoc-demo-[version].jar

5) Verify that the src.zip can be used to produce the same output as a build
   from CVS.  Instructions

    a) make a new dir
    b) cd to that dir
    c) expand flexdock-[version]-src.zip from the CVS build/dist dir
    d) run 'ant dist' from the exp
    e) run a recursive differ on that dir and the CVS dir ignoring timestamps 
       and CVS dirs.  Verify that there are no differences

6) Tag the release.  To do this, you can tag the remote trunk branch or the 
   working copy (assuming that the working copy is representative of trunk 
   HEAD, i.e. if you had to change anything else, you've committed it).

   The format of the tag should be:  flexdock_[major]_[minor]_[patch].  For 
   example flexdock_0_4_0.

   To tag the from the working copy

    cvs tag [versiontag]

   for example

    cvs tag flexdock_0_4_0

   *  This'll probably be replaced with some ant targets later on
   ** the tag scheme is pretty simple now and will probably be enhanced when we
      start doing dailies/weeklies and/or preview releases

7) Create a clean CVS working copy from the tag created in the previous step

8) in that working copy run

    a) ant clean
    b) ant dist

9) diff the dist dir contents ignoring timestamps of the files and entries of 
   the zips and jars in this working copy's build/dist dir to the build/dist 
   dir of the working copy where you performed the tag two steps ago.

10) if #9 shows they are the same, then release the files

    a) Log into flexdock.dev.java.net
    b) Go to the "Documents & files" section of the project
    c) Select "Add new file"
    d) From the CVS versioned working copy add the file 
       build/dist/flexdock-[version].zip (NOT THE JAR):
        i)   Specify as the file name the same name as the file in the working
             copy (without the path)
        ii)  As a description put "FlexDock [version] Binary Release" 
             (substituting the right version number of course)
        iii) Select the zip file from the working copy via "Browse" button next
             to the "Attachment" radio button in the "Contents" section

    e) repeat c&d for the build/dist/flexdock-[version]-src.zip file, but use 
       the description "FlexDock [version] Source Release"

11) Update the index.html file, the web start JNLP file, as necessary and copy
    the flexdock versions into the www area with:

    a) ant webstartapp
