New release guidelines

This document provides:

Apache Juneau
Copyright 2016-{this-year} The Apache Software Foundation

This product includes software developed at
The Apache Software Foundation (http://www.apache.org/).

export X_VERSION=7.0.0
export X_NEXT_VERSION=7.0.1-SNAPSHOT
export X_RELEASE=juneau-7.0.0-RC1
export X_STAGING=~/tmp/dist-release-juneau
export X_USERNAME=<your apache username>
export X_EMAIL=you@apache.org

export X_VERSION=7.0.0
export X_NEXT_VERSION=7.0.1-SNAPSHOT
export X_RELEASE=juneau-7.0.0-RC1
export X_STAGING=~/tmp/dist-release-juneau
export X_USERNAME=<your apache username>
export X_EMAIL=you@apache.org

cd ~/.m2
mv repository repository-old
rm -rf repository-old & 
rm -rf $X_STAGING
mkdir -p $X_STAGING
mkdir $X_STAGING/git
cd $X_STAGING/git
git clone https://gitbox.apache.org/repos/asf/juneau.git
git clone https://gitbox.apache.org/repos/asf/juneau-website.git
cd juneau
git config user.name $X_USERNAME
git config user.email $X_EMAIL

gpg --list-sigs "$X_EMAIL" >> KEYS && gpg -armor --export "$X_EMAIL" >> KEYS

Now we'll make sure they build normally, pass all the tests and complete with BUILD SUCCESS:

From the project root, generate the javadocs and make sure there are no errors or warnings:

Find the following zip files and make sure they deploy correctly in a fresh Eclipse workspace:

• juneau/juneau-microservice/juneau-microservice-template/target/my-microservice-<version>.bin.zip
• juneau/juneau-examples/juneau-examples-rest/target/juneau-examples-rest-<version>.bin.zip
  
• juneau/juneau-examples/juneau-examples-rest-springboot/target/juneau-examples-rest-springboot-<version>.bin.zip
  

When releasing a stable version, Maven will deploy to Apache's Maven repository, a Nexus instance. Here, a staging repository will be automatically created.

Ensure you can log in to the Nexus instance before performing a release.

To provide the Nexus credentials, edit your ~/.m2/settings.xml to include your apache.org committer credentials for the servers apache.snapshots.https and apache.releases.https:

<?xml version="1.0" encoding="UTF-8"?>
<settings xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.1.0 http://maven.apache.org/xsd/settings-1.1.0.xsd" xmlns="http://maven.apache.org/SETTINGS/1.1.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
  <servers>
    <server>
      <id>apache.snapshots.https</id>
      <username>johndoe</username>
      <password>fishsoup</password>
    </server>
    <server>
      <id>apache.releases.https</id>
      <username>johndoe</username>
      <password>fishsoup</password>
    </server>
  </servers>
</settings>

To check you have the correct credentials set up for write-access to Apache's Maven repository, you can deploy the current SNAPSHOT:

3.9 - Prepare release candidate

The contents of the binary distribution is configured in the assembly descriptor juneau-distrib/src/assembly/bin.xml.  Make sure that all (and only) files that should be included in the binary distribution are included in the fileset elements of the descriptor.  We use the Maven release plugin to release candidates as it ensures a consistent release process.

Run the following command:

Note: Maven will use gpg multiple times to tag and sign the artifacts - so you might want to install and configure a GPG Agent to avoid repeatedly providing your GPG passphrase.

If the preparation was successful, then you should now be able to do:

This will check out the tag, build it, then sign and deploy the packaged source code and compiled JARs to http://repository.apache.org.

3.11 - Locate the staging repository

On Apache's Nexus instance, locate the staging repository for the code you just released.  It should be called something like orgapachejuneau-1000. 

Check the Updated time stamp and click to verify its Content.  

Important - When all artifacts to be deployed are in the staging repository, tick the box next to it and click Close.

DO NOT CLICK RELEASE YET - the release candidate must pass [VOTE] emails on dev@juneau before we release.

Once closing has finished (check with Refresh), browse to the URL of the staging repository which should be something like https://repository.apache.org/content/repositories/orgapachejuneau-1000.

Set the following environment variable to match the staging repository:

3.12 - Uploading to dist.apache.org

The release candidate source code, checksums and signatures should be uploaded to the dev area of dist.apache.org using svn - which we'll check out to a new folder.

cd $X_STAGING
rm -rf dist 
svn co https://dist.apache.org/repos/dist/dev/juneau dist
svn rm dist/source/*
svn rm dist/binaries/*
mkdir dist/source/$X_RELEASE
mkdir dist/binaries/$X_RELEASE 
cd $X_STAGING/dist/source/$X_RELEASE
wget -e robots=off --recursive --no-parent --no-directories -A "*-source-release*" https://repository.apache.org/content/repositories/$X_REPO/org/apache/juneau/
mv juneau-${X_VERSION}-source-release.zip apache-juneau-${X_VERSION}-src.zip
mv juneau-${X_VERSION}-source-release.zip.asc apache-juneau-${X_VERSION}-src.zip.asc
mv juneau-${X_VERSION}-source-release.zip.md5 apache-juneau-${X_VERSION}-src.zip.md5
gpg --print-md SHA512 apache-juneau-${X_VERSION}-src.zip > apache-juneau-${X_VERSION}-src.zip.sha512
rm *.sha1
cd $X_STAGING/dist/binaries/$X_RELEASE
wget -e robots=off --recursive --no-parent --no-directories -A "juneau-distrib*-bin.zip*" https://repository.apache.org/content/repositories/$X_REPO/org/apache/juneau/
mv juneau-distrib-${X_VERSION}-bin.zip apache-juneau-${X_VERSION}-bin.zip
mv juneau-distrib-${X_VERSION}-bin.zip.asc apache-juneau-${X_VERSION}-bin.zip.asc
mv juneau-distrib-${X_VERSION}-bin.zip.md5 apache-juneau-${X_VERSION}-bin.zip.md5
gpg --print-md SHA512 apache-juneau-${X_VERSION}-bin.zip > apache-juneau-${X_VERSION}-bin.zip.sha512
rm *.sha1
cd $X_STAGING/dist
svn add source/$X_RELEASE
svn add binaries/$X_RELEASE
svn commit -m "$X_RELEASE"

Now verify that the files are available on https://dist.apache.org/repos/dist/dev/juneau - you might need to refresh your browser.

4 - Voting

Any Apache release must be approved through a vote of the project's PMC.  

The [VOTE] threads should be open for at least 72 hours each, allowing time for sufficient review and catering for differences in holidays and time zones.

Including 24 hours grace period for the download mirrors to update. (For urgent security fixes it might be advisable to do concurrent votes).

Anyone in the community can participate in the review and vote, not just PMC members or committers.  Only votes from PMC members are binding.

4.1 - Vote email to dev@juneau

To start the release vote, modify the below example and send to dev@juneau.  Remember [VOTE] in the subject line and change the version number and the checksums to match the release candidate.

4.2 - Tallying the vote

After at least 72 hours, count the votes in the [VOTE] thread. 

To close the vote thread, send a [RESULT][VOTE] email to dev@juneau, e.g.

List PMC votes first, then other votes.

If the vote has not passed (less than +3, or more negative than positive) then you will need to pull the release candidate and start over after addressing the concerns.

If there are any -1 or 0 votes, then those concerns should be addressed.  Often it can be sufficient to just track these in Jira as scheduled for the next release - while other times the concern could be grave enough to pull the release (e.g. doesn't compile). Given sufficient votes, as a Release Manager you get to decide if the concerns (including your own) are blocking or not.

5 - Validation

Download and extract the apache-juneau-x.x.x-src.zip and apache-juneau-x.x.x-src.zip files from https://dist.apache.org/repos/dist/dev/juneau/

Make sure the source zip contains the following:

• LICENSE
• NOTICE
• RELEASE-NOTES.txt

The bin file should contain the following artifacts:

• projects

  • my-springboot-microservice-x.x.x.zip

  • my-jetty-microservice-x.x.x.zip

  • juneau-examples-rest-springboot-x.x.x.zip

  • juneau-examples-rest-jetty-x.x.x.zip

  • juneau-examples-core-x.x.x.zip

• osgi
  

  • org.apache.juneau.svl_x.x.x.jar

  • org.apache.juneau.rest.server.springboot_x.x.x.jar

  • org.apache.juneau.rest.server.jaxrs_x.x.x.jar

  • org.apache.juneau.rest.server_x.x.x.jar

  • org.apache.juneau.rest.client_x.x.x.jar

  • org.apache.juneau.microservice.jetty_x.x.x.jar

  • org.apache.juneau.microservice.core_x.x.x.jar

  • org.apache.juneau.marshall.rdf_x.x.x.jar

  • org.apache.juneau.marshall_x.x.x.jar

  • org.apache.juneau.dto_x.x.x.jar

  • org.apache.juneau.config_x.x.x.jar

• lib

  • juneau-svl-x.x.x.jar

  • juneau-rest-server-springboot-x.x.x.jar

  • juneau-rest-server-jaxrs-x.x.x.jar

  • juneau-rest-server-x.x.x.jar

  • juneau-rest-client-x.x.x.jar

  • juneau-microservice-jetty-x.x.x.jar

  • juneau-microservice-core-x.x.x.jar

  • juneau-marshall-rdf-x.x.x.jar

  • juneau-marshall-x.x.x.jar

  • juneau-dto-x.x.x.jar

  • juneau-config-x.x.x.jar

• juneau-all-x.x.x.jar

Examine the contents of each inner jar file.  They should all have the following files with the correct content:

• META-INF/LICENSE
• META-INF/NOTICE

Each of the project zip files should be importable into Eclipse without compilation errors.  Try running the launchers to make sure the REST interfaces come up correctly.

6 - Dropping a release candidate

If a release candidate is to be dropped, e.g. it fails the [VOTE] or you cancel earlier, then:

In Nexus, tick the staging repository and Drop.

Delete the old tag:

Roll back the SNAPSHOT version number:

In your dist checkout, svn rm the dropped RC folders:

Raise JIRA issues for the reasons that caused the RC to be dropped.

7 - Distributing

Once a [VOTE] [RESULT] email has been agreed on dev@juneau, then:

• Tag the release in Git.
• Promote the release candidate to a release
• Update download page
• Send announcement email

7.1 - Tag the release in Git

Copy the final tag.

7.2 - Moving to release area

Use full URL svn mv to move the accepted release candidate to the release folder structure on dist.apache.org, e.g. https://dist.apache.org/repos/dist/release/juneau/source/ but remember to remove the -RC1 part from the folder name.

7.3 - Releasing Maven repository

Tick the correct staging repository (perhaps do a quick check of an SHA1 sum against the vote email), then click Release. It should then propagate to Apache's release Maven repository and eventually mirrored to Maven Central.

7.4 - Update download page

Wait 24 hours for the download mirrors to pick up the new release from dist.apache.org, otherwise eager users (or users who just happened to want to download that day) may get 404 Not Found errors.

Update (or make) the corresponding pages under downloads.html including the correct version number for the Maven dependencies and the release dates.

Download links should be using the mirror redirector https://www.apache.org/dyn/closer.cgi, e.g. https://www.apache.org/dyn/closer.cgi/juneau/source/juneau-7.0.0/juneau-7.0.0-source-release.zip

The asc/md5/sha1 links should go directly to https://www.apache.org/dist/ - e.g. https://www.apache.org/dist/juneau/source/juneau-7.0.0/juneau-7.0.0-source-release.zip.asc (important bit: https)

Remove the staged release from Nexus.

7.5 - Removing old versions

After the download page has been published, the download mirrors have synchronized and the new version is live you must remove the old versions from https://dist.apache.org/repos/dist/release/juneau/source/

Older versions are archived under http://archive.apache.org/dist/juneau/source/ but won't appear on the download mirrors.

7.6 - Create announcements