
                          Release Instructions
                          --------------------
                                
								V0.1Draft


This document provides an outline of how to perform a release for the C or Java
XML-Security libraries.  (Hosted at http://xml.apache.org/xml-security.)

Document Authors : 
   Berin Lautenbach

NOTE: Based on ReleaseInstructions.txt from the Ant CVS

Announce Release Plan
---------------------

Propose a release plan for vote.  This should set out the timetable for
the release under ideal circumstances.  The level of bugs reported 
can delay things. Generally, give a few weeks to "close" the source tree 
to further changes so people can finalise contributions, etc. At this time,
the first beta will be cut and there will be then a period of beta testing,
usually 1 month but this should be flexible.

Note that any mention of a deadline causes a flood of bug fixes, new tasks,
etc.  This needs to be managed as best it can. Some fixes will be applied, 
others held over. Make this clear in the release plan. The committers and 
particularly the release manager will need to make judgement calls here. 
Anything too "big" is likely to be held over.

Create Branches in CVS
----------------------
    
Once the freeze date arrives, create a branch for the release builds. You 
will need to be comfortable in handling CVS branches with mutliple 
merge-backs to the main branch and even selected merges from the the main 
branch to the release branch.  
    
For more information on performing branching and merging, please visit
http://www.durak.org/cvswebsites/doc/cvs_54.php#SEC54

Label such branches XMLSECC_11_BRANCH (for C library branches) or
XMLSECJ_11_BRANCH (for Java library branches).
    
Once the branch is setup, the version numbers in CVS are changed. On the 
branch, the build.xml (Java) or configure.ac (C++) version becomes 1.1Beta1
while the main branch is updated to 1.2alpha. 
    
Build the Archives
------------------

Ensure your GPG/PGP key is in the keys.txt file in the CVS.

Export the xml-security module to a clean directory :

	   cvs export xml-security

Label the branch XMLSECC_11_B1 or XMLSECJ_11_B1

** TODO - Create make process to build distributions and add commands here **

** Java guys - what are the instructions to build the archives? **

Sign the archives
-----------------

Sign the distribution files using the following simple script
#!/bin/sh
for i in distribution/*
do
     echo "Signing " $i
     gpg -a -b --force-v3-sigs $i
done

Try to do this on Linux since the gpg signatures generated on Windows may 
cause some PGP users problems verifying signatures even though they seem 
OK.
    
Also make sure you have sent the key that you use to a public 
keyserver.

Transfer to Apache Web Site
---------------------------

The beta distribution is now ready to go. Bundle it up into a tar.gz file 
and scp to your apache account.

** Do we have a standard set of WHATSNEW/README files? The would be updated
here **

Once this is uploaded, unpack things, create the release directory, 
something like v1.1Beta1, push the release and README files into this 
directory.

The files should go to /www/xml.apache.org/builds/xml-security/release
on daedalus.

** Is the above correct? **

Address the available release tags in BugZilla. Create a new tag 1.1Beta1 
and a 1.2alpha. Assign all existing 1.1alpha bugs to one of these release 
labels.

Test the distribtion
--------------------

Once that is done, do a test download to make sure everything is OK. A 
common problem may be:

    * the file's mime type is not recognized and is interpreted as 
      text/plain.  Fix it by using some .htaccess magic (AddEncoding stuff)
    * Your gz.asc files are not being displayed properly (RemoveEncoing stuff)

** What tests should be done to validate archives? **
    
If it looks OK, announce it on security-dev. After a few days pass and 
there are no major problems, a wider announcement is made (main xml 
website, general@xml.apache.org, etc).
    
** Any other files/lists to update? **

Announce beta releases at freshmeat.net (Do we have an entry?)

As problems in the beta are discovered, there may be a need for
one or more subsequent betas. The release manager makes this
call. Each time, the versions are updated and the above process is
repeated. Try not to have too many betas.

Try to advertise the need for testing of the betas as much as possible.
This should eliminate the need to release minor patch versions.
    
To monitor the number of downloads, look at the access_log
file under /usr/local/apache2/logs

When the final beta is considered OK, propose a vote on ant-dev to 
officially adopt the latest beta as the XML-Security-C/J 1.1 release. If it is 
passed,  (it usually does,) this would be labelled XMLSECC_11 or XMLSECJ_11
and built in a similar fashion to the above process.

BUT

This time the directory you upload the files to is different and
you'll have to do some house-keeping for the old release:

** NOTE I am guessing at all directories here **

    * create a directory for the old release in 
      /www/xml.apache.org/builds/xml-security/release on daedalus.

    * Move the release notes, .zip files and corresponding signatures
      and md5 hashes of the old release from 
      /www/www.apache.org/dist/xml-security
      to a matching directory structure in
      /www/xml.apache.org/builds/xml-security/release.

    * remove the remaining files except for the KEYS file from
      /www/www.apache.org/dist/xml-security.

    * upload the new release files to 
      /www/www.apache.org/dist/xml-security/[source|binary].

    * Create proper -current symlinks in /www/www.apache.org/dist/xml-security/

Change the links in /xdocs/bindownload.xml and /xdocs/srcdownload.xml,
regenerate the HTML files, commit and update the site.

As the mirrors may need some days to pick up the new release, you
may want to add a note to that effect to the pages and remove it a few
days later.

Now and perhaps during previous betas any changes on the branch must 
be merged back into the tree.

At this point in time, the release is done and announcements are made. 

**TODO: Identify the mailing lists where announcements are to be made.
Also identify the webpages to which the announcements must go. **

Apache mailing lists that should get the announcements:
announce@jakarta.apache.org, announce@xml.apache.org,
announce@apache.org and security-dev

Announce release at freshmeat.net
** Do we have an entry? **

You can now reacquaint yourself with your family and friends.