Creating a Release

This page documents the steps to create a release.

Please note this section is for committers only.

Prerequisites

Before creating a release ensure you have setup your own public OpenGPG key signature for signing the distribution.

An OpenGPG key can be generated using GnuPG. There is also a Windows port available.

Before starting the release ensure that you have your public key appended to the KEYS file and that the key is published to a public key server such as MIT. More info can be found here: http://www.apache.org/dev/release-signing.html.

Building Distribution

Update to the latest SVN revision:
```
svn update
```
Alternatively do a clean checkout as described on the page Source Code.
Upgrade Click to the next version which consists of the following steps:
- Ensure these files have the correct version: documentation/header.html, framework/src/click-control.properties, build/build.properties, examples/src/click-page.properties, documentation/xdocs/src/docbook/click/click-book.xml and documentation/docs/click-cheat-sheet.pdf.
- Ensure third-party library versions are correct. Check the following files: build/build.xml, examples/build.xml, documentation/docs/developer-guide/building.html.
- Add upgraded libraries to documentation/docs/roadmap-changes.html
Finalize website:
- Finalize documentation/docs/click.html and add news about the upcoming release.
- Finalize documentation/docs/roadmap-changes.html and ensure that the release date is correct.
- Update downloads.html and ensure the release date is correct.
Build documentation:
- Navigate to the folder /documentation/xdocs and download the list of third-party documentation dependencies:
```
ant get-deps
```
- Build the documentation in PDF and HTML formats:
```
ant all
```
Navigate to the /build folder and download the list of third-party library dependencies:
```
ant get-deps
```
Run checkstyle to ensure source code adheres to the coding standard:
```
ant checkstyle
```
Test the release and ensure there are no failures:
```
ant test-all
```
Build the Click distribution:
```
ant build-distribution
```
This step also creates MD5 and SHA1 hashes of the .zip file which must be published together with the distribution.
Deploy the examples to a Servlet container (e.g. Tomcat) and test click-examples.
Digitally sign the distribution click-X.X.X.zip. If you have more than 1 GPG Key, use the -u argument to specify the KEY name.
```
gpg --armor --output click-X.X.X.zip.asc --detach-sig click-X.X.X.zip
```
Upload the distribution to your account at people.apache.org under the folder /home/USER/public_html/click/click/X.X.X/dist, where USER is your Apache user name and X.X.X is the version number of Click.
The following files must be uploaded:
- click-X.X.X.zip
- click-X.X.X.zip.md5
- click-X.X.X.zip.sha1
- click-X.X.X.zip.asc
Make sure the uploaded files have the right permissions (664) and belong to the 'click' group to ensure that other members have proper access to these files. If not execute the following commands to ensure file and directory permissions are correct:
```
ssh people.apache.org
cd ~/public_html/click/click/X.X.X/dist
find . -type d | xargs chmod 775
find . -type f | xargs chmod 664
chgrp -R click *
```
Verify the digital signatures at people.apache.org to ensure nothing went wrong with the upload.
Please note if this is the first time you verify your key at people.apache.org, you'll need to import your public key first.
Assuming your public key ID is 'B51329CB' and your key is available from the public key server 'pgp.mit.edu', the following command will import the key on people.apache.org:
```
ssh people.apache.org
gpg --keyserver pgp.mit.edu --recv-keys B51329CB
```
Next verify the signature with the following command:
```
ssh people.apache.org
cd ~/public_html/click/click/X.X.X/dist
gpg --verify click-X.X.X.zip.asc click-X.X.X.zip
```

Voting

Each release must be voted by the PMC on the click-dev mailing list.

Vote threads are indicated by starting the subject line with [VOTE].

For a vote to pass at least three +1 votes are needed.

Votes are normally run for 72 hours. When starting the vote, indicate the date and time the vote period ends.

When the vote period ends, tally up the votes and report the final result to the mailing list.

Publishing the Release

Tag the new release, e.g. click-2.0.1

svn copy https://svn.apache.org/repos/asf/click/trunk/click https://svn.apache.org/repos/asf/click/tags/click-X.X.X -m "tag X.X.X"

Releases are published at people.apache.org under the folder:
/www/www.apache.org/dist/click/click/X.X.X
First login at apache:
```
ssh people.apache.org
```
Then make sure your umask is set to 002. If not, enter the following command:
```
umask 002
```
In order to publish the release you can copy the files from your /public_html account to the apache distribution folder, for example:
```
cp -r ~/public_html/click/click/X.X.X/dist/ /www/www.apache.org/dist/click/click/X.X.X
```

Publishing Maven Bundles

Before publishing the artifacts, ensure the following settings are present in your Maven settings file "~/.m2/settings.xml":

<settings>
    <servers>
      <server>
        <id>apache.releases</id>
        <username>APACHE_USERNAME</username>
        <directoryPermissions>775</directoryPermissions>
        <filePermissions>644</filePermissions>
    </server>
  </servers>
</settings>

Ensure the version and dependencies of the following files are up to date: build/click.pom, build/click-extras.pom, build/click-mock.pom, build-nodeps.pom.
Build the Maven artifacts:
```
ant build-maven-bundles
```

The maven sign-and-deploy command does not sign POM files, so you will have to do this manually. From the maven-upload folder execute the following commands:

cd maven-upload
gpg --armor --output click/click-X.X.X.pom.asc --detach-sig click/click-X.X.X.pom
gpg --armor --output click-extras/click-extras-X.X.X.pom.asc --detach-sig click-extras/click-extras-X.X.X.pom
gpg --armor --output click-mock/click-mock-X.X.X.pom.asc --detach-sig click-mock/click-mock-X.X.X.pom
gpg --armor --output click-nodeps/click-nodeps-X.X.X.pom.asc --detach-sig click-nodeps/click-nodeps-X.X.X.pom

The signed poms will have to be manually uploaded after the artifacts have been deployed. More on this in the next section.

Maven snapshots must be uploaded to: /home/USER/public_html/click/click/X.X.X/maven2 (USER should be replaced with your home dir on people.apache.org) while releases must be uploaded to: /www/people.apache.org/repo/m2-ibiblio-rsync-repository.

Please note the mvn gpg:sign-and-deploy-file command will both sign and upload the maven artifacts to the server. You will be prompted for your GPG passphrase.

For snapshots execute the following commands from the maven-upload folder: (If you have more than 1 GPG Key, use the keyname attribute to specify the KEY name.)

cd maven-upload
mvn gpg:sign-and-deploy-file -DpomFile=click/click-X.X.X.pom -Dfile=click/click-X.X.X.jar -Durl=scp://people.apache.org:/home/USER/public_html/click/click/X.X.X/maven2 -DrepositoryId=apache.releases
mvn gpg:sign-and-deploy-file -DpomFile=click-extras/click-extras-X.X.X.pom -Dfile=click-extras/click-extras-X.X.X.jar -Durl=scp://people.apache.org:/home/USER/public_html/click/click/X.X.X/maven2 -DrepositoryId=apache.releases
mvn gpg:sign-and-deploy-file -DpomFile=click-nodeps/click-nodeps-X.X.X.pom -Dfile=click-nodeps/click-nodeps-X.X.X.jar -Durl=scp://people.apache.org:/home/USER/public_html/click/click/X.X.X/maven2 -DrepositoryId=apache.releases
mvn gpg:sign-and-deploy-file -DpomFile=click-mock/click-mock-X.X.X.pom -Dfile=click-mock/click-mock-X.X.X.jar -Durl=scp://people.apache.org:/home/USER/public_html/click/click/X.X.X/maven2 -DrepositoryId=apache.releases

For the commands above remember to replace USER with your Apache username and X.X.X with the Click version.

For releases execute the following commands from the maven-upload folder: (If you have more than 1 GPG Key, use the keyname attribute to specify the KEY name.)

cd maven-upload
mvn gpg:sign-and-deploy-file -DpomFile=click/click-X.X.X.pom -Dfile=click/click-X.X.X.jar -Durl=scp://people.apache.org:/www/people.apache.org/repo/m2-ibiblio-rsync-repository -DrepositoryId=apache.releases
mvn gpg:sign-and-deploy-file -DpomFile=click-extras/click-extras-X.X.X.pom -Dfile=click-extras/click-extras-X.X.X.jar -Durl=scp://people.apache.org:/www/people.apache.org/repo/m2-ibiblio-rsync-repository -DrepositoryId=apache.releases
mvn gpg:sign-and-deploy-file -DpomFile=click-nodeps/click-nodeps-X.X.X.pom -Dfile=click-nodeps/click-nodeps-X.X.X.jar -Durl=scp://people.apache.org:/www/people.apache.org/repo/m2-ibiblio-rsync-repository -DrepositoryId=apache.releases
mvn gpg:sign-and-deploy-file -DpomFile=click-mock/click-mock-X.X.X.pom -Dfile=click-mock/click-mock-X.X.X.jar -Durl=scp://people.apache.org:/www/people.apache.org/repo/m2-ibiblio-rsync-repository -DrepositoryId=apache.releases

The sign-and-deploy-file command creates a number of unnecessary artifacts that can be deleted. The artifacts that can be deleted are:
```
click-X.X.X.jar.asc.md5
click-X.X.X.jar.asc.sha1
```

Next upload the POM signature files to each artifact folder. The following POM's must be uploaded to their respective folders: (this step must be done for both snapshots and releases)

click-X.X.X.pom.asc         ->  /www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/click/click/X.X.X/
click-extras-X.X.X.pom.asc  ->  /www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/click/click-extras/X.X.X/
click-mock-X.X.X.pom.asc    ->  /www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/click/click-mock/X.X.X/
click-nodeps-X.X.X.pom.asc  ->  /www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/click/click-nodeps/X.X.X/

Once the artifacts and POM signatures have been uploaded, execute the following commands to ensure the file, directory permissions and group is correct. Note that because of a bug in "maven deploy", all maven-metadata.xml* files must have their permissions set to 664. (this step must be done for both snapshots and releases)
```
ssh people.apache.org
cd /www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/click/
#cd public_html/click/click/X.X.X/maven2
find . ! -perm 775 -type d -user ${USER} -exec chmod 775 {} \;
find . ! -perm 664 -iname maven-metadata.xml* -user ${USER} -exec chmod 664 {} \;
find . ! -perm 644 ! -iname maven-metadata.xml* -type f -user ${USER} -exec chmod 644 {} \;
```

Once the artifacts are uploaded you need to verify the signatures: (this step must be done for both snapshots and releases)

ssh people.apache.org
cd /www/people.apache.org/repo/m2-ibiblio-rsync-repository/org/apache/click/
#cd public_html/click/click/X.X.X/maven2/org/apache/click

gpg --verify click/X.X.X/click-X.X.X.jar.asc click/X.X.X/click-X.X.X.jar
gpg --verify click/X.X.X/click-X.X.X.pom.asc click/X.X.X/click-X.X.X.pom

gpg --verify click-extras/X.X.X/click-extras-X.X.X.jar.asc click-extras/X.X.X/click-extras-X.X.X.jar
gpg --verify click-extras/X.X.X/click-extras-X.X.X.pom.asc click-extras/X.X.X/click-extras-X.X.X.pom

gpg --verify click-nodeps/X.X.X/click-nodeps-X.X.X.jar.asc click-nodeps/X.X.X/click-nodeps-X.X.X.jar
gpg --verify click-nodeps/X.X.X/click-nodeps-X.X.X.pom.asc click-nodeps/X.X.X/click-nodeps-X.X.X.pom

gpg --verify click-mock/X.X.X/click-mock-X.X.X.jar.asc click-mock/X.X.X/click-mock-X.X.X.jar
gpg --verify click-mock/X.X.X/click-mock-X.X.X.pom.asc click-mock/X.X.X/click-mock-X.X.X.pom

Post release

The following tasks should be completed once the release is out:

Upload the web site to people.apache.org under the folder /www/click.apache.org/.
You can either upload the website from your local machine or checkout and sync the site on the people.apache.org server. For example:
```
ssh people.apache.org
mkdir temp
cd temp
svn co http://svn.apache.org/repos/asf/click/trunk/click/
cd click/build
ant get-deps
ant build-distribution
cd ../documentation/xdocs/
ant get-deps
ant all
rsync -avz --exclude ".svn" --exclude "xdocs" ~/temp/click/documentation/ /www/click.apache.org/
```
Make sure the website files and folders have the right permissions (664) and belong to the 'click' group to ensure that other members have proper access to these files. If not execute the following commands to ensure file and directory permissions are correct:
```
ssh people.apache.org
cd /www/click.apache.org/
find . -type d | xargs chmod 775
find . -type f | xargs chmod 664
chgrp -R click *
```
Update the DOAP file (/documentation/doap/click.rdf) and ensure the new release is added. Commit the changes to ensure the DOAP file is picked up by Apache processes.
Email release announcement to the user and dev mailing lists.
Upgrade Click to the next version. The following files must be updated: documentation/header.html, framework/src/click-control.properties, build/build.properties, examples/src/click-page.properties, documentation/xdocs/src/docbook/click/click-book.xml and documentation/docs/click-cheat-sheet.pdf.