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 - 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.yaml (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