2016/04/10 - Apache Wookie has been retired.

For more information, please explore the Attic.

Release Process

This document is an overview of the release process for Apache Wookie. Wookie uses a series of ant scripts coupled together with Apache Ivy to allow automatic building of the code into its various release artifacts. It can also be used to automatically sign binaries and deploy artifacts to the Nexus Repository.

Make sure the Release Setup steps have been performed.

What exactly do we build and release?

You should familiarize yourself with the ant scripts in the project as they are used to create the artifacts. We will go over the specific tasks for generating them in more detail later.

Note the following 3 artifacts that are to be generated. Eventually these should be made available to download from http://www.apache.org/dist/wookie/

  1. A source release (apache-wookie-VERSION-src.zip) (and also a tar.gz version)
    • this is for users who wish to download the code and build it themselves
  2. A standalone release (apache-wookie-VERSION-standalone.zip) (and also a tar.gz version)
    • this is aimed at first time/casual users and incorparates a preconfigured Jetty and Derby DB to work out of the box
  3. A WAR release (apache-wookie-VERSION-war.zip) (and also a tar.gz version)
    • this is aimed towards users who have an existing server setup (their own tomcat/mysql system for example) and want to deploy it alongside their own existing web applications. The bundled documentation is geared towards configuring it for tomcat/mysql but it also includes scripts for other databases.

Additionally there are 3 Nexus artifacts to generate. Eventually these should be made available from the Nexus Repository.

  1. A Nexus artifact of the wookie connector subproject (wookie-java-connector-VERSION.jar)
    • this is for users who want to incorporate the connector part of wookie only as a jar via maven
  2. A Nexus artifact of the wookie parser subproject (wookie-parser-VERSION.jar)
    • this is for users who want to incorporate the w3c widget parser part of wookie only as a jar via maven
  3. A Nexus artifact of the wookie WAR (wookie-VERSION.war)
    • this is for users who want to include a self contained version of the wookie.war in their own projects via maven. (the difference between this and #3 is that this one is configured & bundled with Derby DB.)

Steps to making a release

1. Resolve Outstanding JIRA issues marked against this planned release

  1. Analyse open issues
  2. Issues should be FIXED and verified to ensure they are truly fixed and thus marked as verified
  3. Alternatively, in some cases open issues can be moved to the next planned release
  4. No open issues should remain against this intended release before continuing
    • The only exception to this is if an issue directly addresses the build process, such as "create build for release" type issue.

2. Communicate with committers regarding new release

Send an email to dev@wookie.apache.org and start a vote to discuss whether everybody agrees it is okay to go ahead and make a release. Ideally we'd want a +3 from the committers, but this is not always possible.

  1. Check the following files found at the root of the trunk. (They are bundled with all the builds, except in the case of LICENSE and NOTICE, which are build specific)

    1. README - this is usually the first file a user will read when they download either the source or binary versions of wookie. This file usually will not need to be updated very often, but as it points to other files and explains some of the different builds, it should be checked for accuracy.
    2. RELEASE_NOTES - this must be updated with the list of issues addressed since the last release.
      This can be obtained from the wookie JIRA by selecting all issues addressed for this planned version.
    3. UPGRADING - this must be updated if there were any significant changes made to wookie since the last release. Examples of this are - changes to the database which means that users may have to manually migrate data using scripts or where a major overhaul of the user interface OR API means users would have to change/update their current practices for using those parts of wookie
    4. NOTICE - this should be checked to make sure any new components added to wookie since the last release are mentioned. Note: the actual licences for these go into the LICENSE file.
    5. NEW_AND_NOTEWORTHY - this should be checked and updated to point out and mention any new features in wookie since the last release, that are deemed significant.
    6. BUILDING - this describes how to build wookie from the source. This should be checked for accuracy, but will probably not change very often.
    7. LICENSE - this file contains references to all the licenses of the third party and contributed libaries and code used in wookie.
      Any new libraries and code added since the last release must have their licences added here. The main exception here is an existing Apache Software Foundation library, which does not need to be included.

  2. Check the licences and notices found under /trunk/etc/release/ (Note: some of the builds have specific LICENCE and NOTICE files)

    1. /trunk/etc/release/maven/subprojects/LICENCE. This licence file is bundled with all the maven artifacts (except the maven WAR artifact) and should only contain the apache license. (It is found in in the /META-INF folder of a generated .jar file)
    2. /trunk/etc/release/maven/subprojects/NOTICE. This notice file is bundled with all the maven artifacts (except the maven WAR artifact) and should only contain the apache license references. (It is found in in the /META-INF folder of a generated .jar file)
    3. /trunk/etc/release/maven/war/LICENSE. This license file is bundled with the maven WAR artifact only. (It is found in in the /META-INF folder of a generated .war file).
    4. /trunk/etc/release/maven/war/NOTICE. This notice file is bundled with the maven WAR artifact only. (It is found in in the /META-INF folder of a generated .war file).
    5. /trunk/etc/release/standalone/LICENSE. This license file is bundled with the standalone build only. (It is found at the root of the generated standalone build)
    6. /trunk/etc/release/standalone/NOTICE. This notice file is bundled with the standalone build only. (It is found at the root of the generated standalone build)
    7. /trunk/etc/release/standalone/STANDALONE_BUILD_NOTES. This should not change very often, but a quick read through is recommended to make sure nothing has changed. (It is found at the root of the generated standalone build)
    8. /trunk/etc/release/war/LICENSE. This license file is bundled with the war build only. (It is found at the root of the generated war build)
    9. /trunk/etc/release/war/NOTICE. This notice file is bundled with the war build only. (It is found at the root of the generated war build)
    10. /trunk/etc/release/war/WAR_BUILD_NOTES. This should not change very often, but a quick read through is recommended to make sure nothing has changed. (It is found at the root of the generated war build)

4. Check all files for license headers

Use the Release Audit Tool (RAT) report to find any missing license headers. Fix any missing entries.

5. Update all references to SNAPSHOT in the properties files and update the pom-templates

  1. Find the version reference in the following files. Update it in each case removing the '-SNAPSHOT' at the end, so that it reads for example '0.12.0'. Note that in the top-level ivy.xml there are actually three references you need to change, including the dependencies on the Connector and Parser.

    • /build.properties
    • /ivy.xml
    • /connector/java/build.properties
    • /connector/java/ivy.xml
    • /modules/jcr/build.properties
    • /modules/jcr/ivy.xml
    • /parser/java/build.properties
    • /parser/java/ivy.xml
    • /src/widgetserver.properties
    • /etc/release/runsignatures.bat
    • /etc/release/runsignatures.sh

  2. Update the 3 pom-template.xml files so that the scm values reference the tag version to be created

    • /pom-template.xml

    Find...

     <scm>
    <connection>scm:svn:http://svn.apache.org/repos/asf/wookie/trunk</connection>
    <developerConnection>scm:svn:https://svn.apache.org/repos/asf/wookie/trunk/</developerConnection>
    <url>http://svn.apache.org/viewvc/wookie/trunk/</url>
 </scm>

    ...and update it (with correct version number) to read...

    <scm>
    <connection>scm:svn:http://svn.apache.org/repos/asf/wookie/tags/${project.version}</connection>
    <developerConnection>scm:svn:https://svn.apache.org/repos/asf/wookie/tags/${project.version}/</developerConnection>
    <url>http://svn.apache.org/viewvc/wookie/tags/${project.version}/</url>
</scm>

    Where ${project.version} is going to be your tag name.

    Do the same with the following two files...

    • /connector/java/pom-template.xml
    • /parser/java/pom-template.xml

  3. Commit your changes back to svn.

6. Inform committers of temporary code freeze

Send an email to dev@wookie.apache.org informing that you are about to tag the trunk. (just in case there are commits while you are doing it. It only takes a minute to tag it, so not a long freeze.)

7. Create a tag of the current trunk state.

  1. Ensure you have checked out a clean copy of the trunk from svn.

  2. If using the command line:

    1. Run the following command, replacing the version number as appropriate

    svn copy https://svn.apache.org/repos/asf/wookie/trunk/ https://svn.apache.or g/repos/asf/wookie/tags/0.14.0 -m "Wookie release 0.14.0"

  3. If using Eclipse:

    1. select the wookie root folder and right click. Choose team -> Tag...
    2. A dialog appears.
    3. In the Tag: box enter the release version number i.e. '0.12.0'
      • use the same version here as you entered in step (5.2) when updating the pom-template files
    4. In the Comment box enter something sensible i.e. 'wookie release 0.12.0'
    5. Click ok to create the tag.
    6. If you tick the "Start working in the tag" box, the tag will be created and your local copy will update to the tagged version
    7. Verify the tag was created correctly & in the right place.
      • In the Eclipse SVN Repository Exploring view you can navigate to svn.apache.org/repos/asf/wookie/tags/ and make sure the tag exists.

8. Roll version number forward in all properties files in the trunk.

  1. If you haven't already, switch back to the trunk.
  2. Find all the files listed in step (#5.1) above.
  3. Update all the entries to the next (minor) version-SNAPSHOT - i.e. 0.12.1-SNAPSHOT
  4. Update the 3 pom-template.xml files in step (#5.2) above so that they point back at the trunk again
  5. Commit your changes
  6. Once a release candidate has been successfully voted and released, it is recommended to repeat the steps here (8) but roll the version nmuber to the next version proper (e.g. from 0.12.1 to 0.13.0)

9. Inform commiters that you have finished

Send an email to dev@wookie.apache.org informing that you have tagged the trunk for the build and that the trunk has now rolled to the next version. (which also means the freeze has been lifted)

10. Run the build script

  1. Switch back to the created tag version.

    svn switch https://svn.apache.org/repos/asf/wookie/tags/0.14.0

  2. Run the ant task 'build-release-all' found in the root build.xml file

    • either use eclipse to run it or use 'ant build-release-all' on the command line at the wookie root folder

  3. This should generate a new folder at the root of wookie called 'release' containing the following structure...

    release
    ${project.version}
          binary
                standalone
                      apache-wookie-${project.version}-standalone.tar.gz
                      apache-wookie-${project.version}-standalone.zip
                      rat-report.txt
                war
                      apache-wookie-${project.version}-war.tar.gz
                      apache-wookie-${project.version}-war.zip
                      rat-report.txt
          source
                apache-wookie-${project.version}-src.tar.gz
                apache-wookie-${project.version}-src.zip
                rat-report.txt
          runsignatures.bat

  4. The rat-report.txt files are for your reference and can be removed when checked.

  5. Open a command prompt and run the 'runsignatures.bat' file
    • (AUTHOR NOTE: we need to either also supply a .sh version of this or better still automate it)
    • This creates the ASC signatures, MD5 and SHA files needed for file verification
    • This will only work if you have already followed the steps outlined in the Release Setup
  6. Manually check the ASC, MD5 and SHA files are correct
    • The generated ASC files are automatically checked when you run the 'runsignatures.bat' (see how in the file), but the SHA and MD5 are not
    • These can be checked using openssl at the command prompt, for example...
      • 'openssl sha512 ' - should generate same key on screen as found in the buildname.zip.sha file
      • 'openssl md5 ' - should generate same key on screen as found in the buildname.zip.md5 file
  7. Open each build artifact and test that it...
    • contains the correct NOTICE & LICENSE files where appropriate
    • the source builds will build from the command prompt, using 'ant compile-core'
    • the standalone builds will run when you click it's startup script (May need to add executable permissions on mac/linux)
    • examine the WAR build for integrity (also ideally drop the WAR file into a preconfigured tomcat/mysql instance on your machine to make sure it deploys/works okay)
  8. Don't forget you need to switch back to trunk

11. Upload the artifacts to https://dist.apache.org/repos/dist/dev/wookie/

Since Wookie became a TLP we have moved away from the old method of publishing release candidates to people.apache.org. We now use the https://dist.apache.org/repos/dist/dev/wookie/ subversion area to manage these. Releases once successfully voted on are moved to the https://dist.apache.org/repos/dist/release/wookie/ area. See here for more information.

  1. Make sure you delete the 3 rat-report.txt files (otherwise the next stage will upload them)
  2. From the 'wookie/release' folder copy the ${project.version} folder to your eclipse project which points to the RC subversion area (https://dist.apache.org/repos/dist/dev/wookie/)
  3. Check and make sure that all the binaries are present and that there are no extra resources, other than what was generated by the build script in (10) (No unzipped tar.gz files for example)
  4. Commit the new binaries to svn.
    • (You can alternatively use the svn command line tool, rather than eclipse if you wish)
  5. Verify they are downloadable from https://dist.apache.org/repos/dist/dev/wookie/

12. Upload the Nexus release artifacts

  1. If you use eclipse to run your ant tasks then right click the /build.xml

    • choose run as -> ant build...
    • highlight the "Main" tab and in the "Arguments" panel add the following
      -Duser.name="My Name" -Dupload.user=your_apache_userid -Dupload.password=your_svn_password -Dpgp.password=your_pgp_password -Dpgp.keyId=your_pgp_keyid

    (substituting your details where applicable)

    • click apply.
    • To check/preview the Nexus artifacts locally first run 'ant publish-local' found in the root build.xml file
    • this publishes all artifacts (parser, connector and self contained WAR) locally only and can be found under ${user.home}.m2\repository\org\apache\wookie
    • Once again check to make sure the correct LICENSE and NOTICE files appear in each /META-INF folder found within each archive

    • When you are happy the generated files are okay, either run the following ant task at the command prompt to deploy to Nexus...

      ant publish-maven-release-artifacts publish-subproject-artifacts-to-release-repo -Duser.name="My Name" -Dupload.user=your_apache_userid -Dupload.user=your_apache_userid -Dupload.password=your_svn_password -Dpgp.password=your_pgp_password -Dpgp.keyId=your_pgp_keyid

    or if you have completed step (1.) above, simply right click the root build.xml and choose to run 'publish-maven-release-artifacts' and 'publish-subproject-artifacts-to-release-repo' (AUTHOR NOTE: we need to merge these ant tasks into 1 call)

  2. Verify the staged artifacts in the Nexus repository

    • https://repository.apache.org/index.html
    • Staging repositories (under Build Promotion) --> Name column --> org.apache.wookie
    • Navigate through the artifact tree and make sure that all javadoc, sources, tests, jars, ... have .asc (GPG signature) and .md5 files.
    • See http://people.apache.org/~henkp/repo/faq.html and http://www.apache.org/dev/release-signing.html#openpgp-ascii-detach-sig

  3. Close the Nexus staging repository

    • https://repository.apache.org/index.html
    • Staging repositories (under Build Promotion) --> Name column --> org.apache.wookie
    • click checkbox for the open staging repo (org.apache.wookie-XXX) and press Close in the menu bar.

13. Put the release candidate up for a vote on the dev@wookie.apache.org list

  1. Create a VOTE email thread on dev@wookie.apache.org to record votes as replies, like this
  2. Create a DISCUSS email thread on dev@wookie.apache.org for any vote questions, this

  3. Perform a review of the release and cast your vote. See the following for more details on Apache releases

    http://www.apache.org/dev/release.html

  4. A -1 vote does not necessarily mean that the vote must be redone, however it is usually a good idea to rollback the release if a -1 vote is received.

    • See - Recovering from a vetoed release

  5. After the vote has been open for at least 72 hours, has at least three +1 PMC votes and no -1 votes, then post the results to the vote thread

    • reply to the initial email and prepend to the original subject "[RESULT]"
    • Include a list of everyone who voted +1, 0 or -1.

14. Finalizing a release

  1. Promote the staged nexus artifacts
    • https://repository.apache.org/index.html
    • Staging repositories (under Build Promotion) --> Name column --> org.apache.wookie
    • click checkbox of the closed staging repo (org.apache.wookie-***) and select Release.

  2. Move the release artifacts over to the distribution area

    • (Author note - I cant find a way to do this in eclipse so use the command line tool instead)

    • The artifacts need to be moved from the RC area to the RELEASES area. Open a command prompt and use...

      svn move -m "Apache Wookie ${project.version} RELEASE" https://dist.apache.org/repos/dist/dev/wookie/${project.version} https://dist.apache.org/repos/dist/release/wookie/

    (replacing the version name accordingly)

    (Note: You will be prompted for a Password. If the username is not your apache userid, you might have to press enter once so that you are prompted for your apache username, rather than your local one)

    • verify the folder and contents copied across okay.

  3. Update the staged website

    • Update the downloads page and source page to add new version using the mirrored URLs
    • Add New and Noteworthy to docs/releases
    • Add entry to News about the new release
    • Modify the URL for the prior release to the archived URL for the release

  4. Publish the website

    • Wait 24hrs after committing releases for mirrors to replicate
    • Publish updates to the download page

15. Update JIRA

  1. Update the JIRA versions page to close all issues, mark the version as "released", and set the date to the date that the release was approved. You may also need to make a new release entry for the next release.

16. Announcing the release

  1. Make a news announcement on the Wookie News page.
  2. Make an announcement about the release on the following lists
    • dev@wookie.apache.org
    • user@wookie.apache.org
    • announce@apache.org

17. Recovering from a vetoed release

  1. Reply to the initial vote email and prepend to the original subject -

    [CANCELED]

  2. Delete the svn tag you created in step (7) above. Either use eclipse to do this or via command prompt

    $ svn del https://svn.apache.org/repos/asf/wookie/tags/${project.version} -m "deleting tag from rolled back release"

  3. Delete the build artifacts in the RC area

    $ svn del https://dist.apache.org/repos/dist/dev/wookie/${project.version} -m "deleting release candidate from rolled back release"

  4. Drop the nexus staging repo

    • https://repository.apache.org/index.html
    • Enterprise --> Staging
    • Staging tab --> Name column --> org.apache.wookie -Right click on the closed staging repo (org.apache.wookie-XXX) and select Drop.

  5. Make the required updates that caused the vote to be canceled during the next release cycle