...
- This document contains 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.
Table of Contents |
---|
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.
If you're using macOS, you'll want to install wget.
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:
Round Rectangle | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
To: dev@juneau.apache.org [PROPOSE] Release Apache Juneau 79.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 79.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 /juneau-doc/src/main/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:
Round Rectangle | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
Apache Juneau This product includes software developed at |
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 shell 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 consists of the following files:
- juneau-release-env.sh
- juneau-release.sh
Update the contents of the juneau-release-env.sh to match the values for the new release:
Round Rectangle | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
Make sure not to check in this changed file!
Next, run the juneau-release.sh file 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:
Round Rectangle | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
Run the following commands:
Round Rectangle | ||||||||
---|---|---|---|---|---|---|---|---|
| ||||||||
|
Make sure you're running re running at least Java 8 17 and Maven 3:
|
If you're not running Java 8, you'll get a "javadoc: error - invalid flag: -Xdoclint:none" 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:
|
You should see something like the following...
|
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:
|
Edit your details on id.apache.org to provide your OpenPGP Public Key Primary Fingerprint, e.g.:
|
The following is outdated:
(people.apache.org will fetch your public key from the key servers - you may need to allow some hours if you are adding a new key)
Verify that the people.apache.org juneau.asc file now includes the correct key fingerprint (scroll through or test with gpg --import), and update on dist:
|
Instead, you can use the Signing Releases guide and run:
gpg --list-sigs "$X_EMAIL" >> KEYS && gpg -armor --export "$X_EMAIL" >> KEYS
3.7 - Verify build
Now we'll make sure they build normally, pass all the tests and complete with BUILD SUCCESS:
...
To: dev@juneau.apache.org [VOTE] Release Apache Juneau 79.x.x RCx I am pleased to be calling this vote for the source release of Apache Juneau 79.x.x RCx. The binaries are available at: https://dist.apache.org/repos/dist/dev/juneau/binaries/juneau-79.x.x-RCx/ The release candidate to be voted over is available at: SHA-512 checksums: aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa apache-juneau-79.x.x-bin.zip Build the release candidate using: mvn clean install The release candidate is signed with a GPG key available at: A staged Maven repository is available for review at: The Git commit for this release is... Please vote on releasing this package as: This vote will be open until 04-May-2016 1:30pm and passes if a majority of at least three +1 Apache Juneau PMC votes are cast. Anyone can participate in testing and voting, not just committers, please feel free to try out the release candidate and provide your votes. |
...
[RESULT][VOTE] Release Apache Juneau 79.x.x RCx Voting for Apache Juneau 79.x.x is now closed. The release has passed with the following tally: Person 1 (PMC) |
...
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 [ANNOUNCEMENT] Apache Juneau 79.x.x Released Hello all, The Apache Juneau team is proud to announce the release of Juneau 79.x.x. Apache Juneau is...
<A description of latest updates> The release is available here (don't forget to verify the signatures): Release notes can be found here: We welcome your help and feedback. For more information on the project and how to get involved, visit the project website at |
Send this mail from your @apache.org account. Please spell check the document!
Wait to send the release announcement until you have verified that
- The release artifacts are available on the mirrors.
- The component website including the updated download page has been updated on the public site http://juneau.apache.org/proper/juneau.
- 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.)
8 - 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:
- Make sure JUNEAU_VERSION is set to the new version in /juneau/juneau-env.sh. (should already be done at this point)
- In the juneau-doc/docs folder, copy-and-replace all instance of "<juneauVersion>last-version</juneauVersion>" with "<juneauVersion>current-version</juneauVersion>" (e.g. "<juneauVersion>9.0.0</juneauVersion>" with "<juneauVersion>9.0.1</juneauVersion>").
- In the juneau-doc/docs folder, copy-and-replace all instance of "<juneauVersionNext>current-version</juneauVersionNext>" with "<juneauVersionNext>next-version</juneauVersionNext>" (e.g. "<juneauVersionNext>9.0.1</juneauVersionNext>" with "<juneauVersionNext>9.0.2</juneauVersionNext>".
- Run the following command in the /juneau folder to generate the Javadocs and add them to the website: ./juneau-build-javadoc.sh
- Verify that a new folder is created at juneau-website/content/site/apidocs-x.x.x containing the newly-generated javadocs.
Update the downloads page and regenerate templates.
- Update the juneau-website/templates/downloads.html to reflect the newest release.
- Change Current release section.
- Add new entry to Older releases section.
- Update the settings in juneau-website.properties to reflect new versions.
- 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.