path: root/ReleaseInstructions

Instructions for making a Release:

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

Note: This document was adapted from the one created in the context of
      releasing Ant 1.9.7. It assumes the first release created from
      master will be 1.10.
      Please interpret the branch names, tags, etc. according to
      your context.

      It reflects the way Stefan prefers to cut the release, parts of
      this process haven't even been discussed on the dev list and may
      change with later releases.

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

    In reality, you send a note to the list that you intend to cut the
    release and wait for a few days whether anybody objects.

    We haven't created extra branches for releases in a long time and
    with our new 1.9.x LTS policy there is a permanent branch for
    Java5 compatible releases anyway. So no extra branch for the
    releases is needed.

    This document assumes you are familiar with git
    https://git-scm.com/book/en/v2/
    may be a good guide if you are not.

2.  Ensure you have all the external libraries that Ant uses in your
    lib/optional directory.  All dependencies are either provided by
    JDK 1.8.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...". 

    Also check the NOTICE file to make sure it has the correct
    Copyright year. If the year isn't right, update that file to use
    the right year and commit and push the change upstream, before
    starting any release process.

    There are certain features that require JDK 9+ version to be used
    while releasing Ant 1.10.x from master branch. Make sure JAVA_HOME
    points to a JDK installation which is minimally Java 9.

    You will need to have the snapcraft CLI tool installed in order to
    create and publish snap archives. See
    https://docs.snapcraft.io/snapcraft-overview
    Also you will need a launchpad id that is a collaborator of Ant's
    snapcraft store organization, Stefan can add you.

3.  We don't want tags for failed votes to end up on our branches so
    the release is first created from a detached head.

    Checkout the HEAD of the master branch as a detached head:

    $ git checkout master^0

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

5.  Set the version number in several files to the required new
    versions. These are:

    * manual/cover.html (version should already be correct here)
    * manual/credits.html  (version should already be correct here)
    * build.xml properties : project.version,manifest-version,pom.version
    * POM files under src/etc/poms and subdirectories
      if you've got mvn installed

      $ mvn versions:set -DnewVersion=1.10.0 -DgenerateBackupPoms=false

      inside src/etc/poms should do the trick.

    * ivy.xml in release subdirectory (version should already be correct here)
    * WHATSNEW (version should already be correct here)
    * src/etc/testcases/taskdefs/conditions/antversion.xml (version should already be correct here)
    * snap/snapcraft.yaml - change the value for "version" attribute. Plus, change the value for "grade"
      to "stable".

6.  Next bootstrap, build and run the tests.

    $ ./bootstrap.sh

    Make sure the log messages doesn't contain the message:

    "Java 9+ features won't be available in the distribution"

    If it does, then it's a sign that JAVA_HOME isn't pointing to a JDK 9+ version.
    Fix JAVA_HOME to point to a valid JDK 9+ version and redo the release steps.

    $ ./build.sh
    $ ./build.sh test
    # if you've got maven installed
    $ mvn -f src/etc/poms/pom.xml -DskipTests  package

7.  Then build the distribution. It is important that this be a clean
    build.

    # clean
    $ rm -rf bootstrap build dist distribution java-repository target ant_*.snap
    $ ./build.sh dist-lite
    $ ./dist/bin/ant -nouserlib -lib lib/optional distribution

    build.xml specifies that the code should be compiled with
    source=1.8 and target=1.8.

8.  Commit your changes, tag them, push them.

    $ git commit -m "Prepare for RC1 of version 1.10.0 of Ant" ./
    $ git tag -s -m "Tagging RC1 for version 1.10.0 of Ant" ANT_1.10.0_RC1
    $ git push --tags

9.  Ensure that the GPG key you use is inside the KEYS file in Ant's
    git repository
    <https://gitbox.apache.org/repos/asf?p=ant-antlibs-common.git;a=blob;f=KEYS;h=dc62b011b1b429bd6de913f8f2bce79b715f96db;hb=HEAD>
    - 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.

10. Sign the distribution files

    There are two aproaches, one uses Ant and a few libraries, the
    other requires you to run gnupg manually. The first version didn't
    work for Stefan when he built the first release candidate for
    1.9.7.

    a. Using the script release/signit.xml

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

    This tool can be checked out from 
    https://svn.apache.org/repos/asf/commons/sandbox/openpgp/trunk
    You have to build it using maven.

    $ mvn install

    The script assumes commons-openpgp (and bouncycastle) are in your
    local maven repository.

    You can create a property file gnupg.properties in your home directory 
    with your key id - like

    keyid=5F6B8B72

    or use -Dkeyid

    and pass your key passphrase on the command line with -Dpassword=****

    $ ./build.sh -f release/signit.xml -Dpassword=****

    b. Using gpg

    $ for i in distribution/*/*.zip distribution/*/*.gz distribution/*/*.bz2 distribution/*/*.xz; do gpg --use-agent --detach-sign --armor $i; done
    $ for i in java-repository/org/apache/ant/ant*/*/*.jar java-repository/org/apache/ant/ant*/*/*.pom; do gpg --use-agent --detach-sign --armor $i; done

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

    Use the target txt2html of docs.xml

    $ ./build.sh -f docs.xml txt2html

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

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

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

    Copy the contents of RELEASE-NOTES-1.10.0.html also into README.html

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

13. 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) SHA1 are
    generated by ivy during the upload

    to

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

    using the build file release/upload.xml - this requires Ivy

      $ ./build.sh -Dupload.user=foo -Dupload.password=secret -lib location_of_ivy_jar -f release/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

14. Create the Snap archive and publish it

    You may need to login first

      $ snapcraft login

    And then build and publish

      $ snapcraft clean
      $ snapcraft snap
      $ snapcraft upload --release=candidate ant_*.snap

    This will publish the new release snap to the latest track on the
    candidate risk level. It will be moved to stable, once the vote
    has passed.

15. Once this is committed send a release vote email on dev@ant.
    The email will typically mention :
       - the git tag for the release including commit hash,
       - 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.

16. If the vote fails, address the problems and recreate the next RC
    build.

17. Once the vote has passed, tag the last RC created with the final tag.
    It is important to tag the release under the "rel/" path since the
    Apache infrastructure for .git provides certain protections for tags
    under the "rel/" path. Releases need such protections as per Apache
    release guidelines.

    $ git tag -s -m "Tagging version 1.10.0 of Ant" rel/1.10.0 HASH_OF_LAST_RC
    $ git push --tags

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

    * commit the new release files to

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

    * Make https://dist.apache.org/repos/dist/release/ant/README.html
      point to the new RELEASE-NOTES or a copy of it.

    * 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 artifacts will be in the maven central repository.
      
19. Update the Apache Reporter System

    https://reporter.apache.org/addrelease.html?ant

20. Address the available version tags in BugZilla. Create new
    milestone 1.10.1 and version 1.10.0.

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

22. checkout the master branch, merge the tag but don't push the
    commit

    [if a release of Ant 1.9.x happened at the same time, deal with
    the 1.9.x tag on the 1.9.x branch first and merge the 1.9.x branch
    to master before proceeding here]

    $ git checkout master
    $ git merge rel/1.10.0

    Set the version number in several files to the required version of
    the next 1.10.x release. These are:

    * manual/cover.html
    * manual/credits.html
    * build.xml properties : project.version,manifest-version,pom.version

      project.version property in build.xml gets bumped to
      [newversion]alpha, for example 1.10.1alpha

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

      pom.version gets bumped to [newversion]-SNAPSHOT
      for example 1.10.1-SNAPSHOT.

    * POM files under src/etc/poms and subdirectories
      if you've got mvn installed

      $ mvn versions:set -DnewVersion=1.10.1-SNAPSHOT -DgenerateBackupPoms=false

      inside src/etc/poms should do the trick.

    * ivy.xml in release subdirectory
    * WHATSNEW (add a new section)
    * src/etc/testcases/taskdefs/conditions/antversion.xml
    * snap/snapcraft.yml (bump version to [newversion]alpha and set grade
      to devel)

    Amend the merge commit

    $ git add -u
    $ git commit -a --amend
    $ git push

23. copy the candidate snaps to stable. First figure out the revision

    $ snapcraft status ant
    $ snapcraft release ant REVISION latest/stable
    $ snapcraft release ant REVISION 1.10/stable

    where REVISION is the revision you want to promote (keep in mind that the
    REVISION isn't the version you are releasing. snapcraft uses its own separate integer
    value for the REVISION and this value is listed as the output of the previous
    "snapcraft status ant" command)

24. wait a few hours for the mirrors to catch up

25. Update the ant.apache.org site :

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

    Copy the manual of the release into the production folder - since
    the site still uses svn and Ant proper uses git there currently is
    no way to use the scm for this.

    [TODO once there is the first release of 1.10.0, we'll likely need
    to restructure the site to allow two versions of the manual to
    exist in parallel]

    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.

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

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

28. After a few days "svn rm" the older release artifacts and release
    notes from https://dist.apache.org/repos/dist/release/ant/

    "older" here means any older 1.10.x release but not the latest
    1.9.x release.

Related Information

https://www.apache.org/dev/#releases
https://commons.apache.org/releases/index.html
https://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
   * snap/snapcraft.yaml

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

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

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

    pom.version gets bumped to [newversion]-SNAPSHOT