New release guidelines

This document provides a mixture of information, advice and examples of best practices for releasing versions of Apache Juneau.

The instructions provided here are consistent with, but not a replacement for the ASF Release Guidelines.

1 - Intro

The Apache Juneau project uses the Nexus installation at the Apache Software Foundation to stage Maven artifacts before the release and later publish them; the POM in the root project contains all the necessary configuration. This guide covers deploying to Nexus using Maven. For alternatives see the ASF wide documentation. If this is the first time you are publishing to the ASF's Nexus instance you'll need to prepare your development environment.

Juneau components are expected to use Maven to build the jar/zip files. The version of Maven used is assumed to be Maven 3 throughout. At a minimum, Juneau releases must include full source distributions packaged in zip archives.

This document assumes that the release is being prepared on a linux/unix system, and that steps are being executed from the command-line. The principles are the same, however, for a release prepared on other operating systems.

These instructions assume you are taking on the role of release manager. This implies you are at least one of the developers.

Note: If you're using macOS, you'll want to install wget.

Note: Yellow blocks are code blocks that can be executed as-is UNLESS you see red text indicating values that need to be replaced.

2 - Preparation

2.1 - Determine version number

Consult the versioning guidelines and check that the current level of compatibility is suitable for the proposed version number.

2.2 - Propose email to dev@juneau

Send an email to the dev@juneau mailing list informing the community you plan on creating a new release. The message can be simple:

To: dev@juneau.apache.org
Subject: [PROPOSE] Release Apache Juneau 9.x.x RCx

Hi everyone,

I'm going to create a new release of Juneau because <state short reason why>.

If I do not hear any objections within the next 24 hours, I'm going to go ahead and start the process.

The release will be called 9.x.x-RCx. The next release will be set to 7.x.y.

3 - Creating a release candidate

3.1 - Create new release in JIRA

Log into JIRA and create the new version (e.g. 7.0.1). Change the Release date on the current version to today.

Generate the release notes for the current release as plain text. Click on the current release and click the Release Notes button. Click the Configure Release Notes button to select plain text. Copy the contents of this file to the root RELEASE-NOTES.txt file and commit the change.

3.2 - Update Release Notes section in overview.html

We maintain externally-consumable new-and-noteworthy information for all our releases in our javadocs.

Using the release notes above as a guide, create release notes in the Release Notes section of the /docs/src/javadoc/overview.html document. Use the previous release as a guideline.

3.3 - Update LICENSE and NOTICE files

Check the contents of the LICENSE and NOTICE files in the root directory.

Ensure that the LICENSE files contain the latest information specified in the Apache Licenses page.

Check that the years in the copyright statement in the NOTICE file are correct. The notice file should contain the following:

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

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

Developer documentation on how to apply the Apache License can be found in Applying the Apache License, Version 2.0 and ASF Source Header and Copyright Notice Policy.

3.4 - Run release script

If you've already successfully performed a release, you can run the automated Python script to perform the release. If you do not wish to use the script, skip to section 3.5 - Prepare your build machine.

The release script is located at:

• scripts/release.py

Run the script from the juneau root directory. It will walk you through the entire process.

If successful, you can skip to section 4 - Voting.

3.5 - Prepare your build machine

Run the following commands to set environment variables that will be used throughout this page.
Set X_RELEASE to the version you plan on release and X_STAGING to the staging directory to use on your machine:

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

Run the following commands:

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

Make sure you're running at least Java 17 and Maven 3:

java -version
mvn -version

Note: If you're not running Java 17+, you'll get errors when trying to generate the Javadocs.

3.6 - Update KEYS file if necessary

Check that the KEYS file contains your correct key and fingerprint. If not, then follow the instructions in this section.

You need to have gpg and preferably a GPG Agent installed on the machine you will build the release on. This needs to be configured with your GPG release key.

Find your PGP fingerprint:

gpg --fingerprint $X_EMAIL

You should see something like the following:

jamesbognar-ltm:dist-release-juneau james.bognar$ gpg --fingerprint jamesbognar@apache.org
pub rsa2048 2016-09-21 [SC]
      59E1 A375 4EF6 0E6F CE42 ABFE 3629 2BD2 BA7D 3A86
uid           [ultimate] James Bognar <jamesbognar@apache.org>
sub rsa2048 2016-09-21 [E]

Your key should list your @apache.org email address. Also check your key has not expired - you can use gpg --edit-key and gpg --send-key to update.

The public key must first be uploaded to a public keyserver. To do this, take the last 8 digits from the hex fingerprint and upload them with the following command:

gpg --keyserver pgp.mit.edu --send-key BA7D3A86

Edit your details on id.apache.org to provide your OpenPGP Public Key Primary Fingerprint, e.g.:

59E1 A375 4EF6 0E6F CE42 ABFE 3629 2BD2 BA7D 3A86

4 - Voting

Once the release candidate has been created and uploaded, a vote must be held on the dev@juneau mailing list. The vote must be open for at least 72 hours and requires a minimum of 3 binding +1 votes from PMC members.

The release script will generate a vote email for you. Send this email to dev@juneau.apache.org.

5 - Verifying the release

Before voting, it's important to verify the release artifacts. The release script includes automated verification steps, but you should also manually verify:

1. Download the source distribution
2. Verify the PGP signatures
3. Verify the SHA-512 checksums
4. Build the project from source
5. Run the test suite

6 - After a successful vote

If the vote passes and it's been agreed on dev@juneau, then:

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

6.1 - Tag the release in Git

Copy the final tag:

git tag juneau-7.0.0 juneau-7.0.0-RC1
git push --tags

6.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.

svn mv https://dist.apache.org/repos/dist/dev/juneau/source/juneau-7.0.0-RC1 \
      https://dist.apache.org/repos/dist/release/juneau/source/juneau-7.0.0 \
      -m "Releasing apache juneau-7.0.0"
svn mv https://dist.apache.org/repos/dist/dev/juneau/binaries/juneau-7.0.0-RC1 \
      https://dist.apache.org/repos/dist/release/juneau/binaries/juneau-7.0.0 \
      -m "Releasing apache juneau-7.0.0"

6.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.

6.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.

6.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/

svn rm https://dist.apache.org/repos/dist/release/juneau/source/juneau-6.9.9/
svn rm https://dist.apache.org/repos/dist/release/juneau/binaries/juneau-6.9.9/

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

6.6 - Create announcements

Announce the availability of the new release.

Please remember to give a brief description of your component.

To: announce@apache.org, dev@juneau.apache.org
Subject: [ANNOUNCEMENT] Apache Juneau 9.x.x Released

Hello all,

The Apache Juneau team is proud to announce the release of Juneau 9.x.x.

Apache Juneau is...
- A toolkit for marshalling POJOs to a variety of content types using a common framework.
- A REST server API for creating Swagger-based self-documenting REST interfaces using POJOs.
- A REST client API for interacting with REST interfaces using POJOs.
- A remote proxy API built on top of REST.
- A sophisticated INI config file API.
- A REST microservice API that combines all the features above for creating lightweight standalone REST interfaces that start up in milliseconds.

<A description of latest updates>

The release is available here (don't forget to verify the signatures):
xxx

Release notes can be found here:
xxx

We welcome your help and feedback. For more information on the project and how to get involved, visit the project website at
http://juneau.apache.org/

Send this mail from your @apache.org account. Please spell check the document!

Wait to send the release announcement until you have verified that:

1. The release artifacts are available on the mirrors.
2. The component website including the updated download page has been updated on the public site http://juneau.apache.org/proper/juneau.
3. If the component publishes maven artifacts, these artifacts have been replicated to the central maven repo at repo.maven.apache.org.
   (Clear your local repo of the release artifacts and either activate the clirr report with the updated version info or update a local project with a dependency to the new release version to get maven to try to download the release artifacts. Or just access repo using a web browser.)

7 - Updating Website

The website contents are located in GitHub: https://github.com/apache/juneau-website

Checkout the contents of this repo to the same git folder of the juneau project (e.g. /juneau and /juneau-website should be in the same parent git folder).

Generate the Javadocs for the new version by doing the following:

1. Make sure the version is set correctly in the root pom.xml (should already be done at this point).
2. Run the following command in the /juneau folder to generate the Javadocs and add them to the website: scripts/build-docs.py
3. Verify that a new folder is created at docs/static/javadocs/x.x.x containing the newly-generated javadocs.

Update the downloads page and regenerate templates.

1. Update the juneau-website/templates/downloads.html to reflect the newest release.
   1. Change Current release section.
   2. Add new entry to Older releases section.
2. Update the settings in juneau-website.properties to reflect new versions.
3. Run the juneau-website.sh script to regenerate the templated files.

After completion, commit and push the changes to the master branch. The website should be updated immediately.