| <!-- |
| 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 |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"> |
| <html> |
| <head> |
| <meta http-equiv="CONTENT-TYPE" content="text/html; charset=UTF-8"> |
| <title>JDO Release Process</title> |
| </head> |
| <body lang="en-US"> |
| <ul> |
| <li><a href="#procoverview">Overview of the process</a></li> |
| <li><a href="#procdetail">Detailed process steps</a></li> |
| <li><a href="#site">Site updates</a></li> |
| <li><a href="#postrelease">Post release modifications and |
| documentation</a></li> |
| </ul> |
| <h1>How to Release an Apache JDO Distribution</h1> |
| <p> 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. </p> |
| <p> The process is performed by a release manager with cooperation |
| from testers in the community. </p> |
| <a name="procoverview"></a> |
| <h2>Overview of the process</h2> |
| <p> The community first decides on the name of the release. The |
| format of the name is <i>spec-number</i>.<i>major</i>.<i>minor</i>. |
| A trailing <i>minor</i> number with a zero value is right |
| trimmed, so there might be a 2.0.1 but not a 2.0.0. </p> |
| <p> 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. </p> |
| <p> 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. </p> |
| <p> The release manager follows the Apache process detailed below |
| to build and deploy a release. </p> |
| <p> The release manager calls for the community to test the release. |
| <p> The community tests the release. If necessary, cycle until all |
| issues are resolved. </p> |
| <p> The release manager closes the staged repository</p> |
| <p> The release manager calls for a vote to release by sending a |
| message to the community and forwarding the message to the pmc. </p> |
| <p> The community votes on the release. If necessary, cycle until |
| issues are resolved. </p> |
| <p> The release manager notifies the pmc of the successful vote |
| outcome. Note that a successful vote includes three +1 votes from |
| PMC members. </p> |
| <p> The release manager notifies the worldwide community of the |
| availability of the release. </p> |
| <p> The release manager updates the JDO web sites |
| (http://db.apache.org/jdo/index.html, http://java.sun.com/jdo/). </p> |
| <p> 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. </p> |
| <a name="procdetail"></a> |
| <h2>Detailed process steps</h2> |
| <p> </p> |
| <ol> |
| <li>You might want to run <a href="http://creadur.apache.org/rat">Apache Rat</a> |
| to check the sources for any lisence issues. |
| <pre>mvn apache-rat:check</pre> |
| <li>Create a branch from the trunk and increment the spec or major |
| number. For example, create a 3.1 branch from the trunk. |
| <pre>cd jdo |
| svn copy https://svn.apache.org/repos/asf/db/jdo/trunk \ |
| https://svn.apache.org/repos/asf/db/jdo/branches/3.1 |
| </pre> |
| </li> |
| <li>In trunk, update version numbers in the following files in |
| preparation for the next release: |
| <dl> |
| <dt>trunk/README.html </dt> |
| <dd>File names and version references in the Overview section |
| </dd> |
| <dt>trunk/tck/RunRules.html </dt> |
| <dd>Update version number and date</dd> |
| </dl> |
| Use the maven version plug-in to update version numbers in the |
| pom.xml files at the root and subproject levels. |
| </li> |
| <li>If needed, update the dependency to the RI, DataNucleus, in |
| the tck pom.xml.</li> |
| <li>If needed, apply patches from the trunk or branches to the new |
| branch.</li> |
| <li>Update version numbers where necessary in projects to be |
| released, if these changes haven't been made previously. Check |
| the following files: |
| <dl> |
| <dt>branches/<i>version</i>/README.html </dt> |
| <dd>File names and version references in the Overview section |
| (for a major release only.) |
| </dd> |
| <dt>branches/<i>version</i>/tck/RunRules.html </dt> |
| <dd>Update version number</dd> |
| </dl> |
| </li> |
| <li>Check the scm settings in the pom.xml files in the new branch and |
| make sure they refer the new branch (instead of the trunk). |
| </li> |
| <li>Follow the instructions at <a href="http://www.apache.org/dev/publishing-maven-artifacts.html"> |
| Publishing Maven Artifacts</a> to set up your development environment. |
| </li> |
| <li>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.<b><br> |
| Do not check these in to SVN</b> </li> |
| <li>Build the distribution with the following command: |
| <pre> |
| mvn clean install -Papache-release |
| </pre> |
| This creates the .jar and .pom files |
| in the target directory of each subproject. |
| Be prepared to enter your key passcode when prompted. This happens multiple times. |
| </li> |
| <li>Run <a href="http://creadur.apache.org/rat">Apache Rat</a> on the release. </li> |
| </li> |
| <li> |
| Do a dry run prepare and deployment of a snapshot release. |
| You might want to do this in a fresh workspace, since you cannot have local modifications |
| when preparing a release. The files in lib/ext and lib/jdori count as local modifications. |
| Be prepared to enter your key passcode when prompted. This happens multiple times. |
| <pre> |
| mvn release:prepare -Papache-release -DautoVersionSubmodules=true -DdryRun=true -Dresume=false |
| |
| mvn deploy -Papache-release |
| </pre> |
| Check the artifacts at <a href="https://repository.apache.org/content/repositories/snapshots/"> |
| the Maven release repository</a> |
| </li> |
| <li> |
| Prepare and release the artifacts. There are interoperability issues with the maven release plugin and cygwin, so if on Windows, use a Windows command window for this step and the following one. |
| <pre> |
| mvn release:clean -Papache-release |
| mvn release:prepare -Papache-release |
| </pre> |
| Note: If you're located in Europe then release:prepare may fail with 'Unable to tag SCM' and ' svn: No such revision X '. Wait 10 seconds and run mvn release:prepare again. |
| </li> |
| <li> |
| Stage the release for a vote. |
| <pre> |
| mvn release:perform -Papache-release |
| </pre> |
| </li> |
| <li>Go to <a href="https://repository.apache.org/index.html">the Nexus repository</a>, |
| login with your apache account, click on Staging Repositories in the menu on the left |
| and close the staged repository. Press the refresh button to see the new status 'closed'. |
| See <a href="http://books.sonatype.com/nexus-book/reference/staging-repositories.html"> |
| 11.4.1. Closing an Open Repository</a> for details. |
| </li> |
| <li>Send an announcement to test the release to the |
| jdo-dev@db.apache.org alias. If problems are found, fix and |
| repeat.</li> |
| <li>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.</li> |
| <li>After testing and voting is complete, |
| follow the instructions at |
| <a href="http://books.sonatype.com/nexus-book/reference/staging-repositories.html"> |
| 11.4.3. Releasing a Staging Repository</a> |
| to release the artifacts. |
| </li> |
| <li>Update the distribution repository at http://apache.org/dist/db/jdo/ |
| by adding the new release directory to the svnpubsub directory. |
| Check out the repository at |
| https://dist.apache.org/repos/dist/release/db/jdo and add the |
| new release with all artifacts under the new directory. Make sure |
| that the key used to sign the artifacts is included in the KEYS file. |
| Committing the new directory will trigger an update to the mirrors. |
| </li> |
| <li>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.</li> |
| <li>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 that 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 ***</li> |
| </ol> |
| <a name="site"></a> |
| <h2>Site updates</h2> |
| <ol> |
| <li>Update the Apache JDO web site to point the downloads page to |
| the release. |
| <ol> |
| <li>In site/src/site/xdoc/releases create release-<i>N.n</i>.xml. Edit the |
| release numbers and the link to the release notes. You will |
| need to change the '&'s in the URL to "&amp;"</li> |
| <li>In site/src/site/resources/releases create release-<i>N.n</i>.cgi. The .cgi |
| file contents are identical to the other .cgi files in the |
| release directory; only the file name differs.</li> |
| <li>Edit site/src/site/xdoc/downloads.xml to link to the new release |
| page .cgi document.</li> |
| <li>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.</li> |
| <li>Add the new files to the subversion repository. |
| <pre>svn add site/src/site/xdoc/releases/release-<i>N.n</i>.xml |
| svn add site/docs/releases/release-<i>N.n</i>.html |
| svn add site/src/site/resources/releases/release-<i>N.n</i>.cgi |
| svn add site/docs/releases/release-<i>N.n</i>.cgi |
| </pre> |
| </li> |
| <li>Set the svn properties svn:eol-style to native and |
| svn:executable to true for the .cgi files.</li> |
| </ol> |
| </li> |
| <li>Change the link to RunRules on the <a href="http://db.apache.org/jdo/tck.html">TCK</a> |
| page to link to the RunRules.html file of the latest release.</li> |
| <li>Update the news list on the site home page to announce the new |
| release.</li> |
| <li>Update the specification page to link to the new specification |
| pdf document. If the release has been approved by the JCP, link |
| to the documentation page of the JCP web site. |
| If the release has not been approved by the JCP, |
| link to the .pdf in the JDO source repository.</li> |
| <li>Add the javadoc for the release to the site. |
| <ol> |
| <li>Make a new directory under site/docs for the release, e.g. |
| api2.1. We'll call it <i>docsdir</i>.</li> |
| <li>Download the javadoc artifact from the repository and copy it to <i>docsdir</i>.</li> |
| <li>Unzip it in <i>docsdir</i>.</li> |
| <li>Do svn add on <i>docsdir</i>.</li> |
| <li>Edit xdocs/javadoc.xml and add links to the new javadoc.</li> |
| </ol> |
| </li> |
| <li> Build and test. Follow the instructions in site/HOWTO to push |
| the site changes to the Apache web site.</li> |
| </ol> |
| <a name="postrelease"></a> |
| <h2>Post release modifications and documentation</h2> |
| 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. |
| <ol> |
| <li>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. </li> |
| <li>Merge bug fixes or other modifications into the new branch. </li> |
| <li> 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. </li> |
| <li> Link to this README in the web interface to svn from the .cgi |
| download page and from http://db.apache.org/jdo/tck.html. </li> |
| </ol> |
| </body> |
| </html> |
