Making a release


Making a release

Requirements

Requirements for making a release are similar to the requirements for building from source, except that JDK 1.6+ and Apache Ant 1.9+ are required.

Procedure

1. Check the files which needs to be updated for the release.

On the master, check that files which require update for the release are up to date.
This includes particularly:
RELEASE_NOTES
CHANGES
README

2. Check out a clean copy of the branch

Run the following git command to checkout the branch, revert any change and remove untracked and ignored files:
git checkout 2.0.x
git reset --hard
git clean -d -x -f

3. Add Ivy xsd file.

You need to store the current ivy xml schema in the documentation, so that it will later be accessible on public web site. To do so, run the following command in the directory in which you checked out the release branch:
ant -f build-release.xml release-xsd

4. Add release note page in the documentation.

Open the file doc/index.html with your favorite browser, and click on the plus button in the upper right. Choose "Release Notes" as title, and "release-notes" as page id.

Then edit the page (hit the first button at the upper right), and copy the content of the RELEASE_NOTES file. You can also add the announcement for the release if it's already ready.

Move the page up in the TOC using the arrow button in the toolbar at the upper right, so that it's the first child page under the "Documentation" page.

If you take the time to make the content of the release notes more "xooki compliant" (by removing unnecessary end of lines and adding h2 h3 and h4 tags), the page could then look like something like that:
http://ant.apache.org/ivy/history/2.0.0-alpha-1.html

And commit your changes:
git add doc/ivy.xsd
git add doc/release-notes.html
git commit -m "update templates, add release notes and ivy.xsd in documentation."

5. Launch the release script

ant -f build-release.xml release
The status should be release only for final releases, and milestone for any other intermediate release.
If the release script is successful, release artifacts will be waiting for you in the build/distrib directory.

6. Verify the release

Check that all zips can be opened correctly, and that running 'ant' after unzipping the source distribution works properly.
You can also do a smoke test with the generated ivy.jar, to see if it is able to resolve properly a basic module (for instance you can run some tutorials provided in the src/example directory in all distributions).

7. Sign and upload the artifacts

It's now time to sign the release artifacts and upload them to a location accessible by other Apache commiters.

Here is a simple way to sign the files using gnupg:
gpg --armor --output file.zip.asc --detach-sig file.zip
Here is a ruby script you can use to sign the files:
require 'find'

Find.find('build/distrib') do |f|
`gpg --armor --output #{f}.asc --detach-sig #{f}` if File.file?(f) && ['.zip', '.gz', '.jar', '.pom'].include?(File.extname(f))
end
Be prepared to enter your passphrase several times if you use this script, gpg will ask for your passphrase for each file to sign.

8. Prepare the Eclipse update site

To be able to test the release within IvyDE, it can be deployed in the IvyDE update site. See that page to know how to process.

9. Create the tag

As soon as you are happy with the artifacts to be released, it is time to tag the release
git tag 2.0.0-beta1

Publish the release candidate

All artifacts in build/distrib except the maven2 folder needs to be published on the 'dist' svn of the ASF, in the dev part.

The artifacts should be pushed in that svn folder: https://dist.apache.org/repos/dist/dev/ant/ivy/$VERSION

10. Call for a vote to approve the release

Cast a vote to approve the release on the dev@ant.apache.org mailing list.

Here is an example:
Subject: [VOTE] Ivy ${version} Release

I have built a release candidate for Ivy ${version}

The svn tag of this release is: https://svn.apache.org/repos/asf/ant/ivy/core/tags/${version}@${svn-rev-of-the-tag}

The artifacts has been published to: https://dist.apache.org/repos/dist/dev/ant/ivy/$VERSION@${svn-rev-of-the-check-in}

Do you vote for the release of these binaries?

[ ] Yes
[ ] No

Regards,

${me}, Ivy ${version} release manager

11. Publish the release

If the release is approved, it's now time to make it public. The artifacts in the dev part needs to be moved into the release one:
$ svn mv https://dist.apache.org/repos/dist/dev/ant/ivy/$VERSION https://dist.apache.org/repos/dist/release/ant/ivy/$VERSION
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.

12. Update the web site

It's time to update the download image used on the home page and the download page. Use site/images/ivy-dl.xcf as a basis if you have gimp installed. Then you can update the home page to refer to this image, and add a news item announcing the new version. Update also the download page with the new image and update the links to the download location (using a search/replace on the html source is recommended for this).

The just release documentation should be added to the site. To do so, you need to:
  1. edit the toc.json file in the site component of Ivy
  2. and add a piece of json with a title and an url; note that the version in the url must be the same as the tag in the git repo.
    {
    "title":"2.0.0-beta1",
    "url":"http://ant.apache.org/ivy/history/2.0.0-beta1/index.html"
    }
  3. generate the part of the site for the new version:
  4. ant checkout-history -Dhistory.version=2.0.0-beta1
    ant generate-history -Dhistory.version=2.0.0-beta1
  5. if the 'latest-milestone' needs to be update too, run:
  6. ant checkout-history -Dhistory.version=2.0.0-beta1 -Dtarget.history.folder=latest-milestone
    
Now let's generate the website with the new toc:
ant /all generate-site
You should verify that the site generated in the production directory is OK. You can open the files with your prefered web browser like it was deployed.

And once your happy with it, commit the changes in the source directory, and in the production directoy to get it actually deployed via svnpubsub.

Tip: lot's of files might need to be 'added' to svn. An handy command to add any file which is not yet under version control is the following one:
svn add --force sources

13. Deploy the Eclipse updatesite

If the Eclipse update site has already been prepared to include that new Ivy release, it is now needed to be deployed. Then follow the deployment instruction on that page.

14. Announce

Announce the release on the dev@ant.a.o, ivy-user@ant.a.o, user@ant.apache.org and announce@apache.org mailing lists.
You can also announce the release on popular web sites, like freshmeat.net (xavier is the owner of the Ivy project on freshmeat), javalobby.org, theserverside.com, dzone.com, ...

15. Update this doc

If you feel like anything is missing or misleading in this release doc, update it as soon as you encounter the problem.

16. Merge your modifications back to the trunk if necessary.

Modifications on the template files do not need to be merged, but if you had troubles during your release you may want to merge your fixes back to the trunk.

17. Prepare next release

Update the file version.properties with the version of the next release so that anyone building from the trunk will obtain jar with the correct version number.

Release the version in jira, and create a new unreleased version for the next planned version.