antliscence/ReleaseInstructions

Instructions for making a Release:

Authors: Conor MacNeill
         Stefan Bodewig
         Magesh Umasankar
         Antoine Levy-Lambert

Note: This document was updated in the context of releasing Ant 1.7.
      Please interpret the branch names, tags, etc. according to
      your context.

1.  Propose a release plan for vote.  This should set out the timetable for
    the release under ideal circumstances.  

    The issue of whether to create a branch for the release should be
    discussed in the release vote.

    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.

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

3.  Once the freeze date arrives, create a branch for the release builds,
    if this was decided in the release vote. This was done for Ant 1.6, 
    but not for Ant 1.7, nor for Ant 1.8.

    You will need to be comfortable in handling SVN branches with multiple
    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://svnbook.red-bean.com/nightly/en/svn-book.html

    Label such branches ANT_16_BRANCH.
    
    If the new version is created on the trunk, create or update a branch ANT_SITE
    and switch /www/ant.apache.org to point to ANT_SITE rather than to the trunk.
    
    The ANT_SITE branch and the trunk will be different during the time between 
    the new build and the actual release, which is normally one week in order 
    to vote on the release artifacts. During this time, ANT_SITE does not mention
    yet the new release.
    

4.  Once the branch is setup, the version numbers in SVN are changed. On the
    branch, the project.version property in build.xml becomes 1.7Beta.

    If there were a main branch, its build.xml would have 1.8alpha.

    [[ TODO: Check if the documentation files also need to be updated to point
    to the right areas of Ant's website. ]]

5.  Before a build :

    the first beta on the 1.7 branch has been called 1.7.0Beta1, ...

    the project.version property in build.xml governs the output of
    ant -version and the naming of the distribution files.

    Update the following files for version number:

        On the branch only :

            * docs/manual/cover.html
            * docs/manual/credits.html
            * build.xml properties : project-version & manifest-version 
            * POM files under src/etc/poms and subdirectories
            * ivy.xml in release subdirectory

        Commit your changes.

        On the branch and on the main trunk (*):

            * WHATSNEW
            * xdocs/antnews.xml (Announcement)
            * xdocs/faq.xml (Ant's history details - not for betas)
            * xdocs/index.xml (Announcement, latest release details, link to
            manual under "Documentation")
            * xdocs/srcdownload.xml
            * xdocs/bindownload.xml
            * xdocs/manualdownload.xml

        Generate the html files by invoking ant on docs.xml
        (use -projecthelp for instructions).
        Commit the modified/generated files

6.  Ensure you have all the external libraries that Ant uses in your
    lib/optional directory.  In fact NetRexxC/NetRexxR are the only commercial
    dependencies as of 1.8.0 which are "hard to find". Other dependencies are
    either provided by JDK 1.5.0 or downloadable using 
    ant -f fetch.xml -Ddest=optional.
    To find out whether you have all the libraries you need, execute
    the build with -verbose option and scan for lines beginning with
    "Unable to load...". 

7.  Make sure that your directory tree is clean by running svn status.
    Some tests leave behind leftovers which end up in the source
    distribution otherwise.

8.  Next bootstrap, build and run the tests.  Then build the distribution
    on the branch. It is important that this be a clean build. Label this with
    a tag ANT_170_B1.

    The file release.sh gives an idea of how to do this build process,
    currently in two steps, one with JDK 1.4 and one with JDK 1.5

    C:\dev\asf\ant-core>
    svn copy https://svn.apache.org/repos/asf/ant/core/trunk \
    https://svn.apache.org/repos/asf/ant/core/tags/ANT_170_B1 \
    -m "Tagging version 1.7.0Beta1 of Ant"

    Revision 437509 Uebertragen.

9.  Sign the distribution files using the following simple script

    @TODO : document using commons-openpgp to sign the artefacts,
    change the build file to do this
 
    #!/bin/sh
    # signing the various source and binary archives of the entire distribution
    for i in `/usr/bin/find distribution \( -name "*.bz2" -o -name  "*.zip" -o -name "*.gz" \)`
    do
         echo "Signing " $i
         gpg -a -b --force-v3-sigs $i
    done
    # signing the maven artefacts
    for i in `/usr/bin/find java-repository \( -name "*.pom" -o -name  "*.jar" \)`
    do
         echo "Signing " $i
         gpg -a -b --force-v3-sigs $i
    done

    The --force-v3-sigs will improve the interoperability with PGP 5.x,
    see <http://www.gnupg.org/(en)/documentation/faqs.html#q5.5>.

    Before you do that, ensure that the key you use is inside the KEYS
    file in Ant's SVN repository
    <https://svn.apache.org/repos/asf/ant/antlibs/common/trunk/KEYS> -
    and that you perform a svn update on the KEYS file in
    /www/www.apache.org/dist/ant/common

    Also make sure you have sent the key that you use to a public
    keyserver.

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

11. Meanwhile, convert the part of the WHATSNEW file covering the changes
    since the last release into HTML for the README file on the
    website. See the previous release directories for examples of these files.
    Add instructions and warnings (GNU tar format issues, etc).

    Use the target txt2html of docs.xml

    Name the generated file RELEASE-NOTES-x.y.z.html.

    Change the title to something like "Release Notes of Apache Ant
    1.7.0Beta2" (from the default txt2html)


12. Once this is uploaded, unpack things in your home directory
    and call for a release vote on dev@ant.  The vote will only pass
    if at least three PMC members have voted +1 and more +1s than -1s
    have been cast.  The vote will run for a week.

13. Once the vote has passed, create the release directory,
    something like v1.7.0Beta1, push the release and RELEASE-NOTES files
    into this directory.  Create a symbolic link named README.html
    that points to the RELEASE-NOTES.

    The files should go to /www/www.apache.org/dist/ant/ on people.apache.org.

14. Address the available release tags in BugZilla. Create a new tag 1.7.0Beta1.
    If there is a separate main branch, create a 1.8alpha tag.
    Assign all existing 1.7 alpha bugs to 1.7.0Beta1.
    Note that such massive changes can be done at once by choosing the
    link "Change several bugs at once" at the bottom of the bug list
    displaying the 1.7alpha bugs.

15. 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 (RemoveEncoding stuff)

    If it looks OK, announce it on dev@ant and user@ant. After a few
    days pass and there are no major problems, a wider announcement is
    made (ant website, main jakarta website, announcements@jakarta.apache.org,
    etc).


    you also need to checkout parallel to ant-core
    https://svn.apache.org/repos/asf/ant/site then go to the
    subdirectory generated svn propedit svn:externals to change the
    location of the manual

    Announce beta releases at freshmeat.net (Stefan Bodewig is the
    owner of Ant's project entry - bug him ;-).

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

17. Try to advertise the need for testing of the betas as much as possible.
    This would eliminate the need to release minor patch versions like
    we had to do when releasing Ant 1.4.

    To monitor the number of downloads, look at the access_log
    file under /usr/local/apache2/logs

18. When the final beta is considered OK, propose a vote on dev@ant to
    officially adopt the latest beta as the Ant 1.6 release. If it is passed,
    (it usually does,) this would be labelled ANT_16 and built in a similar
    fashion to the above process.

    It is probably a good idea to have the re-labeled distribution
    files ready in time for the vote so that no additional vote on the
    actual package is required later.

19. This time you'll have to do some house-keeping for the old
    release:

    * upload the new release files to

      from distribution
      to   /www/www.apache.org/dist/ant/[source|binaries|manual].

      
    * upload the maven artifacts located under java-repository/org/apache/ant
      these artifacts comprise currently for each ant jar of one POM file, the corresponding jar file
      and the corresponding GPG signatures (x.pom, x.jar, x.pom.asc, x.jar.asc)
      MD5 and SHA1 are generated by ivy during the upload

      to  

      https://repository.apache.org (nexus repository)

      using the build file release/upload.xml
      
      ant -Dupload.user=foo -Dupload.password=secret -lib location_of_ivy_jar -f upload.xml      

    *  after the upload, you need to access the web interface of nexus under https://repository.apache.org
       login using your Apache credentials
       select the Staging enterprise repository
       expand org.apache.ant 
       right click the upload that you just did
       select the context menu entry "Close"
       once this is done, you have to again select your upload in the web interface,
       right click, and select the menu entry promote.
       4 hours later, the artefacts will be in the maven central repository.
      

    * remove the symbolic links from /www/www.apache.org/dist/ant.

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

    * Make sure that the symbolic link README.html points to the new
      RELEASE-NOTES.

    (**)

20. Update the ant.apache.org site :

    Perform update on files in people.apache.org's /www/ant.apache.org/
    This might mean switching /www/ant.apache.org back from the ANT_SITE branch
    to the trunk.
    
    svn update runs as a cron job, what matters is to which branch the web site
    points too.
     
    svn switch the online manual to the tag of the release.

21. Clean up.

    * remove the remaining files of the previous release and betas from
      /www/www.apache.org/dist/ant/[source|binaries|manual].
      This includes the old release notes.

    (+)

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

23. At this point in time, the release is done and announcements are made.
    PGP-sign your announcement posts.

    [[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:
    announcements@jakarta.apache.org, announcements@xml.apache.org,
    announce@apache.org, dev@ant and user@ant.

    Announce release at freshmeat.net
    (Stefan Bodewig is the owner of Ant's project entry - bug him ;-).

    Announce release in the usenet group comp.lang.java.softwaretools .

24. Add a new release tag to doap_Ant.rdf in Ant's trunk.

25. You can now reacquaint yourself with your family and friends.

(*)  the xdocs need to be updated on both the branch and the HEAD revision
     because traditionally the ant.apache.org web site reflects the HEAD
     revision of the xdocs, but the users downloading a distribution will get
     the xdocs and the generated html from the branch and will complain if there
     are discrepancies in version numbers.

(**) Mirrors : the srcdownload.html, bindownload.html and
     manualdownload.html each list a number of mirrors. For ant 1.6.0
     the mirrors picked up the new version in 8 hours or less, the
     release having been done at midnight on Dec 18th, the mirrors had
     it on Dec 19th at 8 am. The
     srcdownload/bindownload/manualdownload pages all contain a note
     advising users to be patient immediately after the release.

(+)  Don't expect the old releases to disappear from
     www.apache.org/dist as soon as the new releases are there.
     The rsync process from people.a.o to www.a.o adds files once per
     hour but only deletes once per day.


Related Information

http://www.apache.org/dev/#releases
http://commons.apache.org/releases/index.html
http://wiki.apache.org/commons/SigningReleases