How to Release an Apache JDO Distribution
A distribution of JDO is built from a branch of svn. It is
copied into a release directory, from which it is staged and
tested prior to release. Once released, it is propagated to mirror
servers around the world.
The process is performed by a release manager with cooperation
from testers in the community.
Overview of the process
The community first decides on the name of the release. The
format of the name is spec-number.major.minor.
A trailing minor number with a zero value is right
trimmed, so there might be a 2.0.1 but not a 2.0.0.
Interim releases prior to final release are identified by a
suffix on the release number. Common suffixes include: -alpha,
-beta, -beta2, -rc1, -rc2. Generally, the suffixes are part of the
release plan, and the contents of each suffix release are agreed
by the community. There might be significant changes in
functionality between the suffix releases. Each suffix release
goes through the process documented here.
The release manager makes a branch from the trunk (for a major
release) or from another branch (for a minor release) to create a
branch with the source of the distribution.
The release manager modifies the branch to change dependencies
from SNAPSHOT to projects in the release.
The release manager builds and tests the components of the
release and checks the release build into svn.
The release manager publishes the release on a staging area of
the apache server and calls for the community to test the release.
The community tests the release. If necessary, cycle until all
issues are resolved.
The release manager calls for a vote to release by sending a
message to the community and forwarding the message to the pmc.
The community votes on the release. If necessary, cycle until
issues are resolved.
The release manager notifies the pmc of the successful vote
outcome. Note that a successful vote includes three +1 votes from
PMC members.
The release manager distributes the release, which is then
copied to mirror sites worldwide.
The release manager notifies the worldwide community of the
availability of the release.
The release manager updates the JDO web sites
(http://db.apache.org/jdo/index.html, http://java.sun.com/jdo/).
If bugs are found or test challenges are sustained after the
release is approved and distributed, the release manager creates a
new branch to address the bugs found.
Detailed process steps
- Create a branch from the trunk and increment the spec or major
number. For example, create a 3.1 branch from the trunk.
cd jdo
svn copy https://svn.apache.org/repos/asf/db/jdo/trunk \
https://svn.apache.org/repos/asf/db/jdo/branches/3.1
- In trunk, update version numbers in the following files in
preparation for the next release:
- trunk/project.properties
- Change value of currentVersion
- trunk/README.html
- File names and version references in the Overview section
- trunk/JDO3.MF
- Update Specification-Version and Bundle-Version
- trunk/api/project.xml
- Update currentVersion
- trunk/tck/RunRules.html
- Update version number
- In the pending release branch (jdo/branches/xxx), remove the
projects and files that are not being released.
pushd branches/2.n
svn rm api11 btree fostore20 query20 runtime20 ri11 tck11 JDO11.MF
svn commit -m "Remove projects and files that are not being released"
- If needed, update the dependency to the RI, DataNucleus, in
the tck project.xml.
- If needed, apply patches from the trunk or branches to the new
branch.
- Update version numbers where necessary in projects to be
released, if these changes haven't been made previously. Check
the following files:
- branches//project.properties
- Change value of currentVersion
- branches//README.html
- File names and version references in the Overview section
- branches//JDO30.MF
- Update Specification-Version and Bundle-Version
- branches/api/project.xml
- Update currentVersion
- trunk/tck/RunRules.html
- Update version number and release date
- Update the details in branches//api/m2_repo_maven_metadata.xml
to include the version being released.
- Copy the JNDI implementation jars (providerutil.jar and
fscontext.jar) to the branch lib/ext directory. This is needed
to test the tck before distributing it.
Do not check these in to SVN
- Manually install vdoclet:qdox:current:jar artifacts to your
local Maven 1 repository. They can be found at http://repo1.maven.org/maven2/vdoclet/qdox/current/.
Make sure to download qdox-current.jar to
~/.maven/repository/vdoclet/jars.
- Build the distribution. This creates .gz files and .zip files
in the target/distributions directory of each project. It also
creates the .jar and .pom files. It then copies the release
artifacts to the releases/2.n/dist directory. The dist directory
is in a format that can be copied directly to the apache dist
directory for distribution. It contains two subdirectories; db
contains downloadable artifacts and java-repository contains
artifacts that are automatically pulled to maven repositories. Note:
Failure possibly due to insufficient heap space was fixed by
setting the environment variable MAVEN_OPTS="-Xmx1024m
-Xms1024m -XX:MaxPermSize=512m"
pushd branches/3.n
maven jdo3.build
maven jdo3.dist
popd
- Run RAT, which is at http://incubator.apache.org/rat/,
on the release.
- Sign the artifacts. You must have a gpg key in order to
perform this step. The sign-directory script is checked into
jdo/bin. Edit this script to refer to your own environment (do
not check it in). If you're on Windows, your best bet is to run
this script via a cygwin bash shell.
bin/sign-directory releases/3.n/dist/
- Push the artifacts to the staging area on the apache server.
scp -r releases/2.n/dist username@people.apache.org:~/public_html
- ssh to people.apache.org and change to the public_html
directory. Make sure that all the copied directories have
executable permission. If not change the permission for each:
chmod a+x dir
- Test the release from the staging area.
- Send an announcement to test the release to the
jdo-dev@db.apache.org alias. If problems are found, fix and
repeat.
- Send an announcement to vote on the release to the
jdo-dev@db.apache.org alias. The message subject line contains
[VOTE]. Forward the [VOTE] message to private@db.apache.org.
Iterate until you get a successful vote. Mail the results of the
vote to jdo-dev@db.apache.org, cc: general@db.apache.org, and
include [VOTE] [RESULTS] in the subject line.
- After testing and voting is complete, push the artifacts to
the Apache web. Mirrors automatically pick up Apache artifacts
from /www/www.apache.org/dist.
ssh people.apache.org
cp -r public_html/jdoversion/dist/db /www/www.apache.org/dist
cp -r public_html/jdoversion/dist/m1-ibiblio-rsync-repository/* /www/people.apache.org/repo/m1-ibiblio-rsync-repository
cp -r public_html/jdoversion/dist/m2-ibiblio-rsync-repository/* /www/people.apache.org/repo/m2-ibiblio-rsync-repository
NOTE!! Be sure that there is no slash at the end of the
directory you are copying from; otherwise the files will be put
in the wrong target directory.
- Ask one of the Apache repository folks to push the
m1-ibiblio-rsync-repository since this repository is no longer
automatically synchronized. Send a message to
repository@apache.org to push the new artifacts.
- Check the distribution into svn
svn add releases/2.n
svn commit -m "Create release 2.n" releases/2.n
- To get the Maven2 repo populated with Maven1 jars ask
repository@apache.org to push the release
- If the release is a bug fix release to a maintenance release,
update README.txt in the parent branch, adding the following
line: "This release has been deprecated. Please use version
2.x.y.", with a link to the svn web interface for that version.
- After updating the site (below), announce the release to the
Apache community via email to announce@apache.org This must be
sent from an @apache.org email address. *** Be aware the by
sending to this address you will be bombarded with piles of
emails from people with "I'm out of the Office" as if you really
cared ***
Site updates
- Update the Apache JDO web site to point the downloads page to
the release.
- In site/xdocs/releases create release-2.n.xml. Edit the
release numbers and the link to the release notes. You will
need to change the '&'s in the URL to "&"
- In site/xdocs/releases create release-2.n.cgi. The .cgi
file contents are identical to the other .cgi files in the
release directory; only the file name differs.
- Edit site/xdocs/downloads.xml to link to the new release
page .cgi document.
- Build and test as described in the site/HOWTO document.
Note that the cgi page will not be active until it is on the
server, so can't really be tested.
- Add the new files to the subversion repository.
svn add xdocs/releases/release-2.n.html
svn add docs/releases/release-2.n.html
svn add xocs/releases/release-2.n.cgi
svn add docs/releases/release-2.n.cgi
- Set the svn properties svn:eol-style to native and
svn:executable to true for the .cgi files.
- Change the link to RunRules on the TCK page to link
to the RunRules.html file of the latest release.
- Update the news list on the site home page to announce the new
release.
- Add the javadoc for the release to the site.
- Make a new directory under site/docs for the release, e.g.
api2.1. We'll call it docsdir.
- Copy the apidocs directory from the release branch
target/docs directory to docsdir.
- Make a zip file of the apidocs tree and put it in docsdir.
- Do svn add on docsdir.
- Edit xdocs/javadoc.xml and add links to the new javadoc.
- Build and test. Follow the instructions in site/HOWTO to push
the site changes to the Apache web site.
Post release modifications and documentation
Follow this procedure if a significant bug is found or if the TCK
must be modified because a test challenge is found to be valid.
- Create a new branch from the release branch, incrementing the
minor number. For example, create a branch named 2.1.1, from the
2.1 branch.
- Merge bug fixes or other modifications into the new branch.
- In the new branch, modify trunk/README.txt to include a
section on bug fixes since the 2.1 release, and to suggest
checking out the source from a bug-fix branch to get the fixes
listed.
- Link to this README in the web interface to svn from the .cgi
download page and from http://db.apache.org/jdo/tck.html.