path: root/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.9.3.
      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.  We used until Ant 1.6 to create branches, for instance ANT_16_BRANCH
    to allow parallel development on trunk and on the current branch.

    In the case of parallel development on a branch and on trunk, the project
    version would be x.y+1 on trunk and x.y on the branch, for instance 2.0.alpha on trunk
    and 1.9.xbeta on the branch.

    For more information on performing branching and merging, please visit
    http://svnbook.red-bean.com/nightly/en/svn-book.html


4.  Before a build :

    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:
    
    see at the end of this document the list of files containing version information

5.  Ensure you have all the external libraries that Ant uses in your
    lib/optional directory.  All 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...". 

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

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

    The file release.sh gives an idea of how to do this build process.
    buid.xml specifies that the code should be compiled with source=1.5 and target=1.5.

    svn copy https://svn.apache.org/repos/asf/ant/core/trunk \
     https://svn.apache.org/repos/asf/ant/core/tags/ANT_193 \
     -m "Tagging version 1.9.3 of Ant"

8.  Sign the distribution files using the script release/signit.xml

    This script requires using commons-openpgp to sign the artefacts,

    This tool can be checked out from 
    http://svn.apache.org/repos/asf/commons/sandbox/openpgp/trunk
    You have to build it using maven
    
    You can create a property file .gnupg.properties in your home directory 
    with your key id
    and pass your key passphrase on the command line with -Dpassword=****

    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 copy the KEYS file to
    /www/www.apache.org/dist/ant

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

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

    This target generates a file build/html/WHATSNEW.html

    Add an html head element with a title like "Release Notes of Apache Ant
    1.9.3" (from the default txt2html)

    Cut all sections about previous releases to keep only the current release,
    and save as  RELEASE-NOTES-1.9.3.html inside the distribution folder.

    Copy the file RELEASE-NOTES-1.9.3.html also as README.html

10. The distribution is now ready to go.
    Create a SVN sandbox on your computer with https://dist.apache.org/repos/dist/dev/ant in it
    Copy the distribution folder to the location of the sandbox.
    svn add the files and commit into https://dist.apache.org/repos/dist/dev/ant

11.     * 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
           in the left pane, below "build promotion", click on the "Stagings Repositories" links
           expand org.apache.ant
           select the checkbox next to the upload that you just did
           click the button "Close" on the top of the table listing the uploads
           make a note of the location of the staging repository for the vote email


12. Once this is committed send a release vote email on dev@ant.
    The email will typically mention :
       - the SVN tag for the release including revision number,
       - the location of the tarballs, including revision number in dist.apache.org repository
       - the URL for the maven artifacts

    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 3 days.

13. Update the files listed at the end of the document (files containing 
    version information) to prepare the development of the next version of Ant

14. Once the vote has passed, the distrib artifacts should be published the
    apache dist. It is managed via svnpubsub so the release should be
    committed to the subversion repository
    https://dist.apache.org/repos/dist/release/ant/.

    In order to keep the main dist area of a reasonable size, old releases
    should be removed. They will disapear from the main dist but will still be
    available via the archive. To do so, just use the "svn rm" command against
    the artifacts or folders to remove.

15. Address the available version tags in BugZilla. Create a new version 1.9.4.
    Assign all existing 1.9.3 bugs to 1.9.4.
    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.9.3 bugs.

16. 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, announce@apache.org, etc).

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

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

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

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

    * commit the new release files to

      from distribution
      to   https://dist.apache.org/repos/dist/release/ant/[source|binaries|manual].

    *  release the maven artifacts using the web interface of nexus under https://repository.apache.org
       login using your Apache credentials
       in the left pane, below "build promotion", click on the "Stagings Repositories" links
       expand org.apache.ant 
       select the checkbox next to the upload that you just did
       and click the button "Release".
       4 hours later, the artefacts will be in the maven central repository.
      

    * Make README.html points to the new RELEASE-NOTES or is a copy of
      it.

    (*)

21. Update the ant.apache.org site :

    The website is managed here: https://svn.apache.org/repos/asf/ant/site/ant/

    Update the following files for version number:

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

    Generate the html files by invoking 'ant'
    Commit the modified/generated files in the 'production' folder, it will go
    live on ant.apache.org in a matter on seconds.
     
    Change the version of the manual published on the site: svn copy the manual into
    the production folder, using a command similar to :
    svn merge https://svn.apache.org/repos/asf/ant/core/tags/ANT_193/manual/ ./manual/
    followed by a commit.

22. Clean up.

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

    (+)

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

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

    Apache mailing lists that should get the announcements:
    announce@apache.org, dev@ant and user@ant.

25. Add a new release tag to doap_Ant.rdf in Ant's site.

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

(*)  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

Files containing version information
------------------------------------

   * manual/cover.html
   * manual/credits.html
   * build.xml properties : project.version,manifest-version,pom.version
   * POM files under src/etc/poms and subdirectories
   * ivy.xml in release subdirectory
   * WHATSNEW
   * src/etc/testcases/taskdefs/conditions/antversion.xml

cover.html, credits.html, POM files, antversion.xml should be 
adjusted for the [newversion] right after the build and tagging 
of the release

build.xml
---------

  right before a release :

    the project.version gets bumped to the exact release
    number, for instance 1.9.2

  right after a release :
 
    project.version property in build.xml gets bumped to
    [newversion]alpha, for example 1.9.2alpha

    manifest-version gets bumped to the exact next release number
    for example 1.9.2

    pom.version gets bumped to [newversion]-SNAPSHOT