blob: 177a9b4adc6f1bdea8dd43b4e3d44e34ee262258 [file] [log] [blame]
# Licensed to the Apache Software Foundation (ASF) under one or more
# contributor license agreements. See the NOTICE file distributed with
# this work for additional information regarding copyright ownership.
# The ASF licenses this file to You under the Apache License, Version 2.0
# (the "License"); you may not use this file except in compliance with
# the License. You may obtain a copy of the License at
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# See the License for the specific language governing permissions and
# limitations under the License.
This document is meant as a step-by-step recipe to achieve the release of
the Commons RNG component. Note that more general instructions valid
for all components, including [rng], are available on the Apache Commons
main site: at "" and
The files "settings-security.xml" and "settings.xml" are minimal examples
of files used by maven to pick up authentication credentials needed to
connect to remote servers and to cryptographically sign the artifacts.
Release preparation is done on the release manager local host in a branch.
As branches deletion is now forbidden at Apache, we will use a specific
release branch for every version.
The branch will be simply named X.Y-release, with X.Y being the version number.
The branch will be used to store the release specific parts (i.e. the pom changes with
the version number, the release date in the site and so on). Everything else and in
particular code change that will remain in the component after the release must be
committed to the master branch (or version branch). The release candidate branch will
be created from master or version branch at the start of each new candidate for
this particular release. Once the release is done, the branch will be merged back to
master, but it will never be deleted so release history will be preserved.
The example below show a typical workflow. Just after commit A in the master branch, the
X.Y-release branch is created starting from master. This is shown by the 'b' in the
second line. Then release specific commits are made on the pom and a few other
files, leading to a commit which will be tagged as RC1. This release candidate fails, and
a few corrections need to be made on master, corresponding to commits B and C. Then the
X.Y-release branch is synchronized by running a 'git merge' command on the branch.
This is shown by the 'm' in the second line. A new commit is tagged as RC2. This second
release candidate also fails, and a new correction is made on master branch, a new merge
is done on the X.Y-release branch, a new commit is tagged and a third release candidate is
create, which succeeds. Then a final tag will be added on the final commit of this branch
showing the status as released. Then the files are cleaned to prepare for next version
(pom getting again a SNAPSHOT suffix, changes.xml getting a new placeholder for changes)
and the cleaned branch is merged back to master. Once the X.Y-release branch has been merged,
it is kept for history. The release for next version will use another specific branch.
----A-------> B --> C----------> D--------------------------------------m----> <- master branch
\ \ \ /
b---> RC1 ------m---> RC2 ---m---> RC3/final release --> cleaning --X <- X.Y-release branch
This process allows:
- to never commit release candidate specific changes to the master
branch (so the pom on master always holds a SNAPSHOT version),
- to preserve future reference to the release
- to allow parallel work on master during the release
- if necessary to have multiple release managers or help on the
release as the X.Y-release branch is shared
Preliminary checks:
* All Java files must contain a license header. The "RAT" maven plugin will
generate a report indicating for which files the license is missing.
* For a "minor" release, the library must be backward-compatible. Check all
the errors reported by the "Clirr" plugin.
* Clear all "CheckStyle" warnings.
* Make sure that the construct reported by "FindBugs" are intentional.
* Mark all fixed issues as such in the bug-tracking system, and add a
corresponding entry in "src/changes/changes.xml".
As an optional step, you can test that everything works locally, i.e.
that the build process can create all the necessary artifacts.
The command
$ JAVA_HOME="__Path_to_a_JDK__" mvn"__Your_Apache_id__" -Dcommons.release.dryRun=true -Ptest-deploy -Prelease clean test site deploy
should create the artifacts in the "target/deploy" directory.
At some point when processing the above command, the GPG passphrase will be
requested; to avoid problems, the "gpg2" executable should be specified in
the "settings.xml" file (see below).
Note: If running from a remote terminal, you might need to tune the "gpg-agent"
configuration file
to contain the following statements:
pinentry-program /usr/bin/pinentry-tty
and execute
$ export GPG_TTY=$(tty)
in order to set up the environment for entering the passphrase.
When the above works, you can test the creation of the full distribution
files with the following commands:
$ ( cd dist-archive && mvn assembly:single )
The "dist-archive/target" directory will then contain those files:
At this point, you will work mainly on the X.Y-release branch.
If the X.Y-release branch does not exist because it is the first release
candidate, create it locally starting from the master branch or the version
branch and push it to Apache repository (assuming it is called origin),
remembering the binding between the local and remote origin branches:
$ git branch 1.0-release
$ git push -u origin 1.0-release
Switch to the release branch:
$ git checkout 1.0-release
If there have been changes committed in the master branch or the version
branch since the creation of the release branch, there are two cases:
if all these changes must be included in version 1.0, merge "master"
or the version branch into "1.0-release":
$ git merge master
or, if the version branch is called "RNG_1_X"
$ git merge RNG_1_X
if only part of these changes must be included in version 1.0,
cherry-pick the required commits into the "1.0-release" branch:
$ git cherry-pick commit-SHA
Update the release specific files, checking you are really working on the
1.0-release branch and *not* on the master branch.
In particular:
* Update and commit the "src/site/site.xml" file to contain the information
about the API docs of the new release.
* Estimate a release date (taking into account the release vote delay) and
insert it in the "src/changes/changes.xml" file.
* Update the "pom.xml" to contain the final version number and not a SNAPSHOT:
Assuming that the release version will be "1.0", modify the "<version>" tag to
Modify the section of "<properties>" that also refers to version numbers.
You should uncomment the "<commons.rc.version>" line and indicate the
appropriate numbering of the release candidate: This refers to how many
times you will need to repeat this whole release process until it is
accepted (by a vote):
<!-- ... -->
<!-- ... -->
The "download" page template is located at "src/site/xdoc/download_rng.xml".
This file is updated automatically by running the command:
$ mvn -Pcommons-rng-examples commons-build:download-page
The "release notes" file will be created by gathering all the changes
collected during development in the file "src/changes/changes.xml".
Create it by running:
$ mvn -Prelease-notes -Pcommons-rng-examples changes:announcement-generate
Check the file for weird line breaks, and commit the updated files to git:
$ git add src/site/site.xml \
src/changes/changes.xml \
pom.xml \
src/site/xdoc/download_rng.xml \
Check you did not forget any files:
$ git status
Commit the changes:
$ git commit -m "Release candidate."
Create a GPG signed tag that will contain the whole source of this release candidate.
First, make sure once again that the workspace is up-to-date:
$ git status
Then, assuming the first candidate, the suffix will be "RC1" (this should
be the same as in the "<properties>" in the "pom.xml"), and the command
will be:
$ git tag -u "__Your_key_id__" -s -m "RC1." RNG_1_0_RC1
If you have several GPG keys, you may prefer to use "-u keyId" to select a specific
key for signing the tag instead of "-s" which select automatically one key
from the configured e-mail address.
Check the tag GPG signature:
$ git tag -v RNG_1_0_RC1
You will get something like:
object cf4a9d70c9ac24dd7196995390171150e4e56451
type commit
tag RNG_1_0_RC1
tagger YourName <YourApacheEmail> 1418934614 +0100
followed by GPG output lines.
Remember the commit ID listed in the object line (here cf4a9d70c9ac24dd7196995390171150e4e56451),
as it is the most stable reference for traceability.
Push everything (including the tag!) on the Apache repository:
$ git push --tags
Switch to a new directory out of your regular workspace, and retrieve
the official tag from the Apache repository:
$ cd /tmp
$ git clone --branch RNG_1_0_RC1
In the command above, the --branch option accepts both branch names and tags names,
so we specify directly the tag here. Git will warn that the resulting workspace
is in 'detached HEAD' state and 'git status' commands will warn that you are not
currently on any branch. This is expected in this situation.
Check that the last commit has the id you noted in the previous step:
$ cd commons-rng
$ git log -1
If this is your first release, you might need to add your GPG encryption
key to the KEYS file. [If you have already done so, skip this section.]
Retrieve the files from the SVN repository:
$ svn co --depth=immediates \
and follow the instructions at the top of the "KEYS" file.
Create and transfer the artifacts to the Nexus server (a.k.a. "deploy").
Because the artifacts must be cryptographically signed, this step requires that
a profile named "release" exists in the maven "settings.xml" configuration file
which will contain the identifier of your GPG key (cf. sample "settings.xml"
file). You will also have to follow the instructions at to set your password
in the settings.xml file.
You can then run
$ mvn clean deploy -Prelease -Pcommons-rng-examples
which will transfer the artifacts to the Nexus repository located at
This process transfers more files than really needed in the the "staging" (i.e.
non official) maven repository. The files expected in the repository are
and their associated fingerprints
and their signatures
Nexus used to add "md5" and "sha1" checksums files to the "asc" files
(cryptographic signature). If these fingerprints on signatures are
present, they must be manually removed from Nexus staging area.
The process also transfers the complete source and binaries distributions files,
(for each module):
as well as their associated .md5 and .sha1 fingerprints and .asc signatures.
All these files are not maven artifacts but rather distribution archives: They
belong elsewhere; hence they must also been removed from the Nexus staging
As a measure of sanity check, the Nexus repository must be manually "closed"
before other people review the deliverables just created.
How to "close" the staging repository is explained at this page:
Create and upload the other distribution files to the Apache servers.
Perform a server-side copy of the README.html from the "release" area of
the Apache dist server to the "dev" area:
$ svn cp \
The modules "dist-archive" dedicated to creating the archive files.
Run the following command:
$ ( cd dist-archive && mvn assembly:single )
Go to a temporary directory and check out the "dev" area.
$ cd /tmp
$ svn checkout
$ cd rng
Edit the "README.html" file to contain the released version number.
Copy other files from the RC workspace:
$ cp path-to-the-RC-workspace/RELEASE-NOTES.txt .
$ cp path-to-the-RC-workspace/ .
$ cp path-to-the-RC-workspace/ .
$ cp path-to-the-RC-workspace/dist-archive/target/*-bin.* binaries
$ cp path-to-the-RC-workspace/dist-archive/target/*-src.* source
Currently, the commons-parent build does not create the
* signatures (".asc"),
* checksums (".md5"),
* hashes (".sha1")
of the distribution files. Hence, you have to create them "manually"!
For the signature, the command would be
$ gpg -ab file-to-sign
For the hash and checksum, see e.g. the "Digest" Perl module.
Commit to SVN:
$ svn add \ \ \
README.html \
binaries/* \
$ svn commit -m "Distribution files for Commons RNG v1.0 (RC1)."
As the web site staging area is shared among all commons components and therefore
could be published before the vote ends, it is not recommended to use the standard
staging area for the release candidate. So you will just archive the site and
transfer it to your apache personal area for review.
Here is how to do this using "lftp" to initiate the sftp transfer. "lftp" supports
a mirror command for recursive transfers; don't forget the -R flag for uploading
instead of downloading the site.
If you haven't setup your login on you will need to go to
login and copy the contents of your
file to "SSH Key (authorized_keys line)".
Then run these commands:
$ mvn clean -Pcommons-rng-examples site site:stage
$ cd target
$ mv staging commons-rng-1.0-RC1-site
$ lftp s
lftp> cd public_html
lftp> mirror -R commons-rng-1.0-RC1-site
lftp> bye
Call to vote by sending a message to the "dev" ML with subject
"[VOTE][RC1] Release Commons RNG 1.0". You can use the following example as
a starting point, replacing the URLs with the appropriate ones:
This is a [VOTE] for releasing Apache Commons RNG 1.0 (from RC6).
Tag name:
RNG_1_0_RC6 (signature can be checked from git using 'git tag -v')
Tag URL:;a=commit;h=4581a4520315657a4219b37c81f5db80e4a4e43c
Commit ID the tag points at:
Distribution files (committed at revision 17284):
Distribution files hashes (SHA1):
c5e70a523160ed848194eeba0efa2b14d23c7a61 commons-rng-1.0-bin.tar.gz
ef56543c8882a0e4771de83ecf8b3be190f122cf commons-rng-1.0-src.tar.gz
KEYS file to check signatures:
Maven artifacts:
Please select one of the following options:
[ ] +1 Release it.
[ ] +0 Go ahead; I don't care.
[ ] -0 There are a few minor glitches: ...
[ ] -1 No, do not release it because ...
This vote will be open for at least 72 hours, i.e. until 2016-12-10T00:00:00Z
(this is UTC time).
If some blocking problems have been found in the release deliverables, cancel
the vote by sending a "[CANCEL][VOTE]" message to the "dev" ML.
After correcting the problems, you'll likely have to start again from step 3,
4 or 5.
After at least 72 hours have elapsed, send a "[VOTE][RESULT]" mail to
summarize the outcome of the vote. This should tally the votes cast,
and state which are binding (PMC members). The vote needs at least three +1's
from PMC members to pass.
The distribution files must be moved from the development area to the release
area of the Apache dist server.
Checkout the official distribution repository:
$ svn co
Copy the files from the checkout of the repository that was voted on:
$ cd rng
$ rsync -Cavz path-to-RC-dev/rng/ .
Check (and possibly "svn add") files.
$ svn commit -m "Release Commons RNG v1.0 (from RC6)."
Register the release at
Release (a.k.a. "promote") the artifacts on the Nexus server, as shown here:
Publish the web site. This is done by first committing the web site to the
staging area, and then by publishing the staging area (which is shared among
all commons components).
In order to commit the web site to the staging area, look at the subversion
workspace that was automatically checked out during the 'mvn site' command in
folder site-content. Note that svn commits in the site-content directory are
immediately synced with the live site and so your changes should show up in a
few minutes once you commit the new site. You can also check out the site
directly by yourself elsewhere:
$ svn checkout site-content
Remove all files there (except .svn folder) and move all the files from the site.
$ cd site-content
$ rm -rf *
$ cp -pR ../target/commons-rng-1.0-RC1-site/* .
Check for new or deleted files:
$ svn status
and "svn add" or "svn del" them if necessary.
Commit the new contents of the web site:
$ svn commit -m "Commons RNG v1.0 was released (from RC6). Web site update"
The Javadoc for several versions is kept available on the website, under the
"javadocs" directory.
There is a huge number of files that never change, so they are not retrieved by
default in the working copy when running 'svn checkout'.
The Javadoc must therefore be copied manually using server side copy from the
"apidocs" directory after release, in order for the links to former versions
to work. This is done as follows:
$ export RNG_WEB_SITE_SVN_REVISION=1002658
$ svnmucc -U \
cp $RNG_WEB_SITE_SVN_REVISION commons-rng-client-api/apidocs \
commons-rng-client-api/javadocs/api-$RNG_RELEASE_VERSION \
cp $RNG_WEB_SITE_SVN_REVISION commons-rng-core/apidocs \
commons-rng-core/javadocs/api-$RNG_RELEASE_VERSION \
cp $RNG_WEB_SITE_SVN_REVISION commons-rng-simple/apidocs \
commons-rng-simple/javadocs/api-$RNG_RELEASE_VERSION \
cp $RNG_WEB_SITE_SVN_REVISION commons-rng-sampling/apidocs \
commons-rng-sampling/javadocs/api-$RNG_RELEASE_VERSION \
cp $RNG_WEB_SITE_SVN_REVISION commons-rng-jmh/apidocs \
commons-rng-jmh/javadocs/api-$RNG_RELEASE_VERSION \
cp $RNG_WEB_SITE_SVN_REVISION commons-rng-examples/apidocs \
commons-rng-examples/javadocs/api-$RNG_RELEASE_VERSION \
-m "Commons RNG: Copying $RNG_RELEASE_VERSION apidocs to versioned directories for the long-term links."
Now wait a few minutes for the live site to fully sync and then check
to make sure that everything looks correct.
Put the official final tag to point at the same commit as the last release candidate tag:
$ git tag -u "__Your_key_id__" -s -m "RC6 becomes v1.0 official release." RNG_1_0 cf4a9d70c9ac24dd7196995390171150e4e56451
$ git push --tags
Switch back to the "master" branch.
We now prepare for the next round of development (here we assume that the
next version will be 1.1).
Edit "doap_rng.rdf" to add the just released version date.
It is located at
in the SVN repository.
Retrieve files from the "1.0-release branch" (so that the web site will
contain up-to-date information):
$ git checkout 1.0-release src/site/xdoc/download_rng.xml
$ git checkout 1.0-release src/changes/changes.xml
Edit "src/changes/changes.xml" to add a new section for the next release,
setting the release date and description to "TBD".
Then commit them.
Edit every "pom.xml" file (i.e. for each module) to contain
Double-check that the "pom.xml" files *really* have a "-SNAPSHOT" suffix
in the "<version>" property.
Then commit them.
Push everything to the Apache repository.
Allow for the web site mirrors to be updated (possibly several hours); then
send (from your apache account) a release announcement to the following ML:
If you don't have it setup already you can follow these instructions to send
email from your apache account :
You can use the following message as a template:
The Apache Commons Team is pleased to announce the availability of
version 1.0 of "Apache Commons RNG".
Apache Commons RNG provides Java implementations of pseudo-random
numbers generators.
The release notes can be reviewed at
Distribution packages can be downloaded from
When downloading, please verify signatures using the KEYS file
available at
Maven artifacts are also available in the central Maven repository:
The Apache Commons Team