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. The spec-number is either 1 for JDO 1 or 2 for JDO 2. The major number would change for a specification revision approved by the JCP via specification maintenance review. The minor number can be used for changes that do not need a maintenance review and do not change the interfaces. 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 or from another branch. If you are creating a major or spec maintenance release, e.g. 2.0, 2.1, create a 2.n branch from the trunk. If creating an bug-fix release, e.g. 2.0.1.3, create a branch from the 2.0.1 or 2.0.1.2 branch and apply updates to it.
```
cd jdo
svn copy https://svn.apache.org/repos/asf/db/jdo/trunk \
https://svn.apache.org/repos/asf/db/jdo/branches/2.0
```

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"

Update dependencies in projects to be released.
```
For each project.xml in the branch:
sed /-SNAPSHOT//gcd 
popd
```
If needed, update the dependency to JPOX in the tck20 project.xml. If needed, apply patches from the trunk or branches to the new branch.
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. cp trunk/lib/ext/* branches/2.n/lib/ext
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. Note: Failure possibly due to insufficient heap space was fixed by setting the environment variable MAVEN_OPTS="-Xmx1024m -Xms1024m -XX:MaxPermSize=512m"
```
pushd branches/2.n
maven tck2.default
maven tck2.dist
popd
```
Test the release in the branch.
```
pushd branches/2.n/tck20
maven installSchema
maven runtck.jdori
popd
```
Also run RAT on the release: http://code.google.com/p/arat/
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). bin/sign-directory releases/2.n/dist/jdo2.n-rcm

Push the artifacts to the staging area on the apache server.

scp -r releases/2.n/dist username@people.apache.org:~/public_html

Make sure that all the directories have executable permission:
```
chmod a+x dir
```
Test the release from the staging area. 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 pmc@db.apache.org. Iterate until you get a successful vote. Mail the results of the vote to jdo-dev@db.apache.org, bcc: 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/dist /www/www.apache.org
```

Check the distribution into svn

svn add releases/2.n
svn commit "JDO-XXX create release 2.n" releases/2.n

After updating the site (below), announce the release to the Apache community via email to announce@general.apache.org

Site updates

Update the Apache JDO web site to point the downloads page to the release.
1. In site/xdocs/releases create release-2.n.html.
2. In site/docs/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.
3. Edit site/xdocs/downloads.xml to link to the new release page .cgi document.
4. Set the svn properties svn:eol-style to native and svn:executable to true for the .cgi files.
5. Build and test as described in the site/HOWTO document.
6. 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 docs/releases/release-2.n.cgi 
svn commit
```
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. Build, test, and push as described in HOWTO.
Add the javadoc for the release to the site.
1. Make a new directory under site for the release, e.g. api2.1. Call it docsdir.
2. Copy the apidocs directory from the release branch target directory to docsdir.
3. Make a zip file of the apidocs tree and put it in docsdir.
4. Do svn add on docsdir.
5. Edit xdocs/javadoc.xml and add links to the new javadoc.
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
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.