ReleaseInstructions - ant - Git at Google

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

 2.  We used until Ant 1.6 to create branches, for instance ANT_16_BRANCH
     to allow parallel development on master and on the current branch.
     Given the slow development speed we've reached with 1.9.x this
     doesn't seem to be necessary anymore.

     For more information on performing branching and merging, please visit
     http://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell


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

 4.  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...".

 5.  Create a branch just for the release, even if you've decided to
     not work with long lived branches in step 2.  This branch can be
     removed after the release.

     Switch to that branch.

     $ git checkout -b prepare_Ant_1.9.5

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

 7.  Next bootstrap, build and run the tests.  Then build the
     distribution on the branch. It is important that this be a clean
     build. Tag this with a tag ANT_195_RC1.

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

     git tag -s -m "Tagging RC1 for version 1.9.5 of Ant" ANT_195_RC1
     git push --tags

 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 git repository
     <https://git-wip-us.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.

 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.5" (from the default txt2html)

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

     Copy the file RELEASE-NOTES-1.9.5.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 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.

 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 on the master branch.

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

 15. Once the vote has passed, tag the last RC created with the final tag

     $ git tag -s -m "Tagging version 1.9.5 of Ant" ANT_195 HASH_OF_LAST_RC
     $ git push --tags

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

     * commit the new release files 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.

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

 17. Address the available version tags in BugZilla. Create a new version 1.9.6.
     Assign all existing 1.9.5 bugs to 1.9.6.
     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.5 bugs.

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

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

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

	2. We used until Ant 1.6 to create branches, for instance ANT_16_BRANCH
	to allow parallel development on master and on the current branch.
	Given the slow development speed we've reached with 1.9.x this
	doesn't seem to be necessary anymore.

	For more information on performing branching and merging, please visit
	http://git-scm.com/book/en/v2/Git-Branching-Branches-in-a-Nutshell


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

	4. 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...".

	5. Create a branch just for the release, even if you've decided to
	not work with long lived branches in step 2. This branch can be
	removed after the release.

	Switch to that branch.

	$ git checkout -b prepare_Ant_1.9.5

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

	7. Next bootstrap, build and run the tests. Then build the
	distribution on the branch. It is important that this be a clean
	build. Tag this with a tag ANT_195_RC1.

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

	git tag -s -m "Tagging RC1 for version 1.9.5 of Ant" ANT_195_RC1
	git push --tags

	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 git repository
	<https://git-wip-us.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.

	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.5" (from the default txt2html)

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

	Copy the file RELEASE-NOTES-1.9.5.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 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.

	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 on the master branch.

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

	15. Once the vote has passed, tag the last RC created with the final tag

	$ git tag -s -m "Tagging version 1.9.5 of Ant" ANT_195 HASH_OF_LAST_RC
	$ git push --tags

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

	* commit the new release files 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.

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

	17. Address the available version tags in BugZilla. Create a new version 1.9.6.
	Assign all existing 1.9.5 bugs to 1.9.6.
	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.5 bugs.

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

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

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