Release Process

Prerequisites

Before creating a release, ensure that:

GIT and Deployment Credentials

To successfully create a release, you will need to update your Gradle settings with the credentials for your git user and the deployment user. These credentials are stored in the Gradle configuration file ~/.gradle/gradle.properties:

apacheDeployUserName=hlship
apacheDeployPassword=...

signing.keyId=7CC19136
signing.secretKeyRingFile=.../.gnupg/secring.gpg
signing.password=...

apacheArchivesFolder=.../tapestry-dev

You can find your keyId using gpg --list-keys.

 The apacheArchivesFolder should be the full path to your dev archives workspace. The build will copy files to this folder; see further notes below.

Release Steps

1. Generate the Release

  1. Update your workspace to the release branch
    1. For current work, the release branch is master
    2. When creating bug fix releases for older releases, the branch will match the release, e.g., 5.3
  2. Run the build using gradle generateRelease
    1. This will create, sign, and upload JAR files and other artifacts to the Nexus repository
    2. It will also create, sign, and copy the source, binary, and documentation archives to your dev archives workspace
  3. Tag the release in Git, then push the changes up to the Apache repository:
    1. git tag 5.x
    2. git push --tags
  4. Login to Nexus and close the automatically created staging repository

2. Commit the Archives

  1. The build will have copied archive files to your dist workspace
  2. svn add the new files
  3. svn commit to copy the files up to Apache (this is slow)
    1. Use the full version number as the commit message, e.g., 5.4-beta-26
  4. You can verify the files via the web: https://dist.apache.org/repos/dist/dev/tapestry

3. Bump the Version Number

  1. Update build.gradle to increment the version number
  2. Increment the minor version number (inside the tapestryVersion method, near the top of the file)
  3. Commit and push the changes

4. Send Vote

  1. Send vote email
  2. Wait 3 days
  3. The vote is successful if there are at least three +1's and more +1 than -1
  4. Only PMC members may cast binding votes

5. Update JIRA and generate release notes 

  1. Use the Manage Versions page in JIRA to add a new version (this is often not necessary as it is often created by someone earlier)
  2. Release the version, moving outstanding issues to the next version
  3. Generate HTML Release Notes
    1. Visit the TAP5 Versions pages in JIRA
    2. Choose the correct version number
    3. Click "Release Notes" (upper right corner of the page)
    4. Create a new Confluence child page of Release Notes (it may already exist)
    5. Update with text about any unusual aspects of the upgrade (especially, non-backwards compatible changes)
    6. Paste the HTML release notes content into the new page (you'll have to use the {html} macro)
    7. Rename the "Bug" heading to "Bugs Fixed", "Improvement" to "Improvements Made", "New Feature" to "New Features Added"
    8. Update Release Notes index page to point to the new page

6. Release the Maven Artifacts

  1. Login to Nexus and release the version's repository
    1. Enter "Apache Tapestry 5.x" (adjust as necessary) for the message
    2. The version will disappear from the list of repositories after releasing it
  2. Releasing will ultimately get the artifacts up to the central Maven repository

7. Release the Archives

  1. Copy the release archives files (including checksums and GPG signatures) to the release archives workspace
  2. Change to the release archives workspace
  3. svn add andsvn commit, as with the dev archives workspace

8. Release the Javadocs

  1. Run the "aggregateJavadoc" gradle task
  2. Copy the resulting files from build/documentation/javadocs/* to a version-numbered subdirectory of your site content workspace (see Prerequisites at the top of this page)
  3. svn commit those new javadoc files
  4. Update the "current" symbolic link under the content directory to point to new version-numbered directory. For example, if "current" is a symbolic link to "5.4" and you want to change it to "5.5", do this:
    • rm current
    • ln -s 5.5 current
    • svn commit -m "Updated javadocs current symbolic link" current

9. Wait

  • You must wait at least 24 hours for the archives and artifacts to be distributed to the Apache mirrors and to the central Maven repository

10. Update Documentation

  1. Update the release number listed in the following pages in the Confluence wiki:
    1. Download page
    2. (Optional) Tutorial Creating The Skeleton Application page: Tapestry version number in the archetype
    3. (Optional) Getting Started page: Tapestry version number in the archetype
  2. Change to the site content workspace
  3. svn update to get any recent changes
  4. Edit archetype-catalog.xml to add or update a new entry for the release
  5. Update the release number and date inside doap.rdf  (this is a description file for the project)
  6. svn commit

11. Blog & Tweet

  1. Write a blog post in Confluence announcing the release.
  2. Send an email to the users mailing list announcing the release.
  3. Send out a tweet (using the ApacheTapestry Twitter account) announcing the release.

Done!



A template for the vote e-mail:

I've created and uploaded a release of Tapestry 5.x, ready to be voted upon.

The source, binary, and documentation archives have been uploaded to:

    https://dist.apache.org/repos/dist/dev/tapestry

and the Maven artifacts staged to:

    https://repository.apache.org/content/repositories/staging/org/apache/tapestry/

Please examine these files to determine if the new release, 5.x, is ready.

I've also created a 5.x tag in Git:

    https://git-wip-us.apache.org/repos/asf?p=tapestry-5.git;a=log;h=refs/tags/5.x

Vote will run for three days and requires majority approval from
the PMC: At least 3 binding +1 votes and more positive than
negative binding votes.

On a successful vote, I'll release the Maven artifacts, the archives,
and make the necessary updates to JIRA and the Tapestry site.

Only votes cast by Tapestry PMC members are binding, but input
from the community is highly valued. Please indicate whether your
vote is binding or not after your full name (as it will appear in
the end-of-vote summary).

The release manager often embellishes this template with extra detail.

It's also a nice touch to append a text version of the JIRA release notes as well.