asciidoc/dev/makerelease.adoc - ant-ivy - Git at Google

 ////
    Licensed to the Apache Software Foundation (ASF) under one
    or more contributor license agreements.  See the NOTICE file
    distributed with this work for additional information
    regarding copyright ownership.  The ASF licenses this file
    to you under the Apache License, Version 2.0 (the
    "License"); you may not use this file except in compliance
    with the License.  You may obtain a copy of the License at

      https://www.apache.org/licenses/LICENSE-2.0

    Unless required by applicable law or agreed to in writing,
    software distributed under the License is distributed on an
    "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    KIND, either express or implied.  See the License for the
    specific language governing permissions and limitations
    under the License.
 ////

 == Making a release

 === Requirements

 Requirements for making a release are similar to the requirements for building from source, except that Apache Ant 1.9+ is 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:
 `asciidoc/release-notes.adoc`

 ==== 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:

 [source,shell]
 ----
 git checkout master
 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:

 [source,shell]
 ----
 ant -f build-release.xml release-xsd
 ----

 And commit your changes in the branch:

 [source,shell]
 ----
 git add asciidoc/ivy.xsd
 git commit -m "release the ivy.xsd"
 ----

 ==== 4. Launch the release script

 [source,shell]
 ----
 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.

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

 ==== 6. Sign the artifacts

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

 Here is a simple way to sign the files using gnupg:

 [source,shell]
 ----
 gpg --armor --output file.zip.asc --detach-sig file.zip
 ----

 Here is a ruby script you can use to sign the files:

 [source,ruby]
 ----
 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.

 ==== 7. Prepare the Eclipse update site

 To be able to test the release within IvyDE, it can be deployed in the IvyDE update site. See link:https://ant.apache.org/ivy/ivyde/history/trunk/dev/updatesite.html[that page] to know how to process.

 ==== 8. Publish the release candidate

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

 The following command lines should do the job:

 NOTE: Make sure to use the right version number in the commit message.

 [source,shell]
 ----
 svn checkout -N https://dist.apache.org/repos/dist/dev/ant/ivy build/distrib/dist
 svn add build/distrib/dist/*
 svn commit build/distrib/dist -m 'Ivy 2.4.0 distribution'
 ----

 ==== 9. Publish the Maven artifact to Nexus

 Having your GPG key ID, its password, your apache ID and the associated password, just launch Ant and enter the information as required:

 [source,shell]
 ----
 ant -f build-release.xml upload-nexus
 ----

 Once uploaded, log in https://repository.apache.org/ with your preferred web browser (use your Apache ID).

 You should find there an __open__ repository with the name of the form `orgapacheant-XXXX`. It should contain the Maven artifacts: the pom, the jar, the sources, the javadocs and the sha and asc files.

 Now __close__ the staging repository, with the description "Ivy 2.0.0-beta1". Closing means you finished the upload and some automatic checks will run. You can see them in the __Activity__ tab of the repository.

 Once the checks passed, you can find in the __Summary__ the URL of the staging repository. It will something like: https://repository.apache.org/content/repositories/orgapacheant-XXXX/

 ==== 10. Create a signed tag

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

 NOTE: Use the right version number for the tag. For example, if you released 2.5.0 of Ivy, then the tag name should be 2.5.0

 [source,shell]
 ----
 git tag -s 2.0.0-beta1 -m 'Release Ivy 2.0.0-beta1'
 ----

 And push the changes to the ASF repo

 [source,shell]
 ----
 git push --tags
 ----

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

 [source]
 ----
 Subject: [VOTE] Ivy ${version} Release

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

 The git tag of this release is: https://gitbox.apache.org/repos/asf?p=ant-ivy.git;a=tag;h=refs/tags/${version} with the sha1 ${githash-of-tag}

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

 The staging Maven repository is available there: https://repository.apache.org/content/repositories/orgapacheant-XXXX

 The Eclipse updatesite has been build there: https://dist.apache.org/repos/dist/dev/ant/ivyde/updatesite/ivy-${version}/

 Do you vote for the release of these binaries?

 [ ] Yes
 [ ] No

 Regards,

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

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

 [source,shell]
 ----
 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 disappear from the main dist but will still be available via the link:https://archive.apache.org/dist/ant/ivy/[archive]. To do so, just use the `svn rm` command against the artifacts or folders to remove.

 ==== 13. Promote the Maven staging repository

 Go log in https://repository.apache.org/ with your preferred web browser (use your Apache ID).

 Select the appropriate `orgapacheant-XXXX` repository and select the __Release__ action.

 ==== 14. 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 link:https://www.gimp.org/[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:

 . edit the toc.json file in the site component of Ivy 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.
 +
 [source,json]
 ----
 {
    "title":"2.0.0-beta1",
    "url":"http://ant.apache.org/ivy/history/2.0.0-beta1/index.html"
 }
 ----

 . from the distribution just released, install the doc into the site
 +
 [source, shell]
 ----
 ant install-doc -Dhistory.version=2.5.0-rc1 -Divy-dist.zip.url=https://dist.apache.org/repos/dist/release/ant/ivy/2.5.0-rc1/apache-ivy-2.5.0-rc1-bin.zip
 ----

 Now let's generate the website with the new toc:
 [source,shell]
 ----
 ant /all generate-site
 ----

 You should verify that the site generated in the production directory is OK. You can open the files with your preferred web browser like it was deployed.

 And once your happy with it, commit the changes in the source directory, and in the production directory 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:

 [source,shell]
 ----
 svn add --force sources
 ----

 ==== 15. 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 link:https://ant.apache.org/ivy/ivyde/history/trunk/dev/updatesite.html[that page].

 ==== 16. Announce

 Announce the release on the dev@ant.apache.org, ivy-user@ant.apache.org, user@ant.apache.org and announce@apache.org mailing lists. Note that announce@apache.org only accepts emails sent with an @apache.org address.

 Suggested template:

 [source]
 ----
 Subject: [Announce] Release of Apache Ivy ${version}

 The Apache Ivy project is pleased to announce its ${version} release.

 Apache Ivy is a tool for managing (recording, tracking, resolving and
 reporting) project dependencies, characterized by flexibility,
 configurability, and tight integration with Apache Ant.

 Key features of this ${version} release are:

 XXXX INCLUDE THE PARAGRAPH FROM THE RELEASE NOTES XXXX

 XXXX SUGGESTED PARAGRAPH FOR RC
 As a release candidate version, we strongly encourage the use of this version for
 testing and validation. From now on, features are frozen until final ${version} version,
 only bug fixes will be applied before ${version}. If no outstanding bugs are reported
 with this release candidate, it will promoted to ${version} about three weeks after this
 release candidate.

 Issues should be reported to:
 https://issues.apache.org/jira/browse/IVY

 Download the release at:
 https://ant.apache.org/ivy/download.cgi

 More information can be found on the Ivy website:
 https://ant.apache.org/ivy/

 Regards,
 ${me}
 ----

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

 ==== 18. Merge your modifications back to the master 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.

 ==== 19. Prepare next release

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

 If the version just release is a final one (not an alpha, beta or rc), the list of changes should be emptied in doc/release-notes.html, and update there the next expected version. The announcement in the file should also be changed accordingly to the next expected version.

 Release the version in link:https://issues.apache.org/jira/browse/IVY[jira], and create a new unreleased version for the next planned version.
	////
	Licensed to the Apache Software Foundation (ASF) under one
	or more contributor license agreements. See the NOTICE file
	distributed with this work for additional information
	regarding copyright ownership. The ASF licenses this file
	to you under the Apache License, Version 2.0 (the
	"License"); you may not use this file except in compliance
	with the License. You may obtain a copy of the License at

	https://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing,
	software distributed under the License is distributed on an
	"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
	KIND, either express or implied. See the License for the
	specific language governing permissions and limitations
	under the License.
	////

	== Making a release

	=== Requirements

	Requirements for making a release are similar to the requirements for building from source, except that Apache Ant 1.9+ is 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:
	`asciidoc/release-notes.adoc`

	==== 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:

	[source,shell]
	----
	git checkout master
	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:

	[source,shell]
	----
	ant -f build-release.xml release-xsd
	----

	And commit your changes in the branch:

	[source,shell]
	----
	git add asciidoc/ivy.xsd
	git commit -m "release the ivy.xsd"
	----

	==== 4. Launch the release script

	[source,shell]
	----
	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.

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

	==== 6. Sign the artifacts

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

	Here is a simple way to sign the files using gnupg:

	[source,shell]
	----
	gpg --armor --output file.zip.asc --detach-sig file.zip
	----

	Here is a ruby script you can use to sign the files:

	[source,ruby]
	----
	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.

	==== 7. Prepare the Eclipse update site

	To be able to test the release within IvyDE, it can be deployed in the IvyDE update site. See link:https://ant.apache.org/ivy/ivyde/history/trunk/dev/updatesite.html[that page] to know how to process.

	==== 8. Publish the release candidate

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

	The following command lines should do the job:

	NOTE: Make sure to use the right version number in the commit message.

	[source,shell]
	----
	svn checkout -N https://dist.apache.org/repos/dist/dev/ant/ivy build/distrib/dist
	svn add build/distrib/dist/*
	svn commit build/distrib/dist -m 'Ivy 2.4.0 distribution'
	----

	==== 9. Publish the Maven artifact to Nexus

	Having your GPG key ID, its password, your apache ID and the associated password, just launch Ant and enter the information as required:

	[source,shell]
	----
	ant -f build-release.xml upload-nexus
	----

	Once uploaded, log in https://repository.apache.org/ with your preferred web browser (use your Apache ID).

	You should find there an __open__ repository with the name of the form `orgapacheant-XXXX`. It should contain the Maven artifacts: the pom, the jar, the sources, the javadocs and the sha and asc files.

	Now __close__ the staging repository, with the description "Ivy 2.0.0-beta1". Closing means you finished the upload and some automatic checks will run. You can see them in the __Activity__ tab of the repository.

	Once the checks passed, you can find in the __Summary__ the URL of the staging repository. It will something like: https://repository.apache.org/content/repositories/orgapacheant-XXXX/

	==== 10. Create a signed tag

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

	NOTE: Use the right version number for the tag. For example, if you released 2.5.0 of Ivy, then the tag name should be 2.5.0

	[source,shell]
	----
	git tag -s 2.0.0-beta1 -m 'Release Ivy 2.0.0-beta1'
	----

	And push the changes to the ASF repo

	[source,shell]
	----
	git push --tags
	----

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

	[source]
	----
	Subject: [VOTE] Ivy ${version} Release

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

	The git tag of this release is: https://gitbox.apache.org/repos/asf?p=ant-ivy.git;a=tag;h=refs/tags/${version} with the sha1 ${githash-of-tag}

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

	The staging Maven repository is available there: https://repository.apache.org/content/repositories/orgapacheant-XXXX

	The Eclipse updatesite has been build there: https://dist.apache.org/repos/dist/dev/ant/ivyde/updatesite/ivy-${version}/

	Do you vote for the release of these binaries?

	[ ] Yes
	[ ] No

	Regards,

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

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

	[source,shell]
	----
	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 disappear from the main dist but will still be available via the link:https://archive.apache.org/dist/ant/ivy/[archive]. To do so, just use the `svn rm` command against the artifacts or folders to remove.

	==== 13. Promote the Maven staging repository

	Go log in https://repository.apache.org/ with your preferred web browser (use your Apache ID).

	Select the appropriate `orgapacheant-XXXX` repository and select the __Release__ action.

	==== 14. 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 link:https://www.gimp.org/[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:

	. edit the toc.json file in the site component of Ivy 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.
	+
	[source,json]
	----
	{
	"title":"2.0.0-beta1",
	"url":"http://ant.apache.org/ivy/history/2.0.0-beta1/index.html"
	}
	----

	. from the distribution just released, install the doc into the site
	+
	[source, shell]
	----
	ant install-doc -Dhistory.version=2.5.0-rc1 -Divy-dist.zip.url=https://dist.apache.org/repos/dist/release/ant/ivy/2.5.0-rc1/apache-ivy-2.5.0-rc1-bin.zip
	----

	Now let's generate the website with the new toc:
	[source,shell]
	----
	ant /all generate-site
	----

	You should verify that the site generated in the production directory is OK. You can open the files with your preferred web browser like it was deployed.

	And once your happy with it, commit the changes in the source directory, and in the production directory 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:

	[source,shell]
	----
	svn add --force sources
	----

	==== 15. 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 link:https://ant.apache.org/ivy/ivyde/history/trunk/dev/updatesite.html[that page].

	==== 16. Announce

	Announce the release on the dev@ant.apache.org, ivy-user@ant.apache.org, user@ant.apache.org and announce@apache.org mailing lists. Note that announce@apache.org only accepts emails sent with an @apache.org address.

	Suggested template:

	[source]
	----
	Subject: [Announce] Release of Apache Ivy ${version}

	The Apache Ivy project is pleased to announce its ${version} release.

	Apache Ivy is a tool for managing (recording, tracking, resolving and
	reporting) project dependencies, characterized by flexibility,
	configurability, and tight integration with Apache Ant.

	Key features of this ${version} release are:

	XXXX INCLUDE THE PARAGRAPH FROM THE RELEASE NOTES XXXX

	XXXX SUGGESTED PARAGRAPH FOR RC
	As a release candidate version, we strongly encourage the use of this version for
	testing and validation. From now on, features are frozen until final ${version} version,
	only bug fixes will be applied before ${version}. If no outstanding bugs are reported
	with this release candidate, it will promoted to ${version} about three weeks after this
	release candidate.

	Issues should be reported to:
	https://issues.apache.org/jira/browse/IVY

	Download the release at:
	https://ant.apache.org/ivy/download.cgi

	More information can be found on the Ivy website:
	https://ant.apache.org/ivy/

	Regards,
	${me}
	----

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

	==== 18. Merge your modifications back to the master 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.

	==== 19. Prepare next release

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

	If the version just release is a final one (not an alpha, beta or rc), the list of changes should be emptied in doc/release-notes.html, and update there the next expected version. The announcement in the file should also be changed accordingly to the next expected version.

	Release the version in link:https://issues.apache.org/jira/browse/IVY[jira], and create a new unreleased version for the next planned version.