<!-- | |
~ 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. | |
--> | |
<document xmlns="http://maven.apache.org/XDOC/2.0" | |
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" | |
xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd"> | |
<properties> | |
<title>Axis2 Release Process</title> | |
</properties> | |
<body> | |
<h1>Release Process</h1> | |
<macro name="toc"/> | |
<section name="Release process overview"> | |
<subsection name="Cutting a branch"> | |
<ul> | |
<li>When a release is ready to go, release manager (RM) puts | |
forward a release plan as per standard Apache process, including | |
dates. This gets VOTEd on by the committers. During this period the | |
trunk is still the only relevant source base.</li> | |
<li>As soon as a release is approved (or even before), RM should | |
add the new version into JIRA as a target.</li> | |
<li>At the point where we would normally do the "code freeze" for a | |
release, the RM cuts a branch named for the release. This branch is | |
where the release candidates and releases will happen.</li> | |
<li>Ideally a release branch is only around for a week or maybe two | |
before the release happens.</li> | |
<li>The only things that should EVER get checked into the release | |
branch are - 1) bug fixes targeted at the release, 2) | |
release-specific updates (documentation, SNAPSHOT removal, etc). In | |
particular new functionality does not go here unless it is a | |
solution to a JIRA report targeted at the release.</li> | |
<li>Normal development continues on the trunk.</li> | |
</ul> | |
</subsection> | |
<subsection name="Dependencies and branches"> | |
<ul> | |
<li>The trunk should always be "cutting edge" and as such should | |
usually be pointing at SNAPSHOT versions of all dependencies. This | |
allows for continuous integration with our partner projects.</li> | |
<li>Soon after a release branch is cut, the RM is responsible for | |
removing ALL dependencies on SNAPSHOT versions and replacing them | |
with officially released versions. This change happens only on the | |
release branch.</li> | |
</ul> | |
</subsection> | |
<subsection name="Managing change and issue resolution with a release branch"> | |
<ul> | |
<li>The RM goes through JIRA issues and sets "fix for" to point to | |
both "NIGHTLY" and the new branched release number for the fixes | |
that are targeted for the release after the branch is cut.</li> | |
<li>In general, the assignee/coder fixes JIRA issues or makes other | |
changes *on the trunk*. If the JIRA issue is targeted at the | |
release, or upon coder's discretion, they then merge the fix over | |
to the release branch.</li> | |
<li>This way the trunk is ALWAYS up-to-date, and we don't have to | |
worry about losing fixes that have only been made on the release | |
branch.</li> | |
<li>When the assignee resolves an issue, they confirm it's been | |
fixed in both branches, if appropriate.</li> | |
</ul> | |
</subsection> | |
<subsection name="Checking changes into the branch"> | |
<ul> | |
<li>If bug fixes are needed later for a release which has long | |
since happened (to fix user issues, etc), those fixes generally | |
should also happen on the trunk first assuming the problem still | |
exists on the trunk.</li> | |
<li>There are only two cases where we would ever check anything | |
into the branch without first checking it into the trunk. 1) | |
Release specific items (release number references, release notes, | |
removal of SNAPSHOTs), and 2) if the trunk has moved on in some | |
incompatible way.</li> | |
</ul> | |
</subsection> | |
</section> | |
<section name="Performing a release"> | |
<p><strong>Note:</strong> performing the release requires at least Maven 2.1.0. The recommended version is 2.2.1.</p> | |
<subsection name="Preparation"> | |
<p>Verify that the code meets the basic requirements for being releasable:</p> | |
<ol> | |
<li>Check the consistency between the metadata in <tt>pom.xml</tt> and <tt>modules/parent/pom.xml</tt>. | |
Since the root and parent POMs are different, some of the metadata is duplicated and needs to be synchronized | |
manually. This includes the mailing list addresses, issue tracker information, SCM location, etc.</li> | |
<li>Check that the set of legal (<tt>legal/*.LICENSE</tt>) files corresponds to the set of third party | |
JARs included in the binary distribution.</li> | |
<li>Check that the <tt>apache-release</tt> profile works correctly and produces the required distributions. | |
The profile can be executed as follows: | |
<pre>mvn clean install -Papache-release -Dmaven.test.skip=true</pre></li> | |
<li>Check that the source distribution is buildable.</li> | |
<li>Check that the source tree is buildable with an empty local Maven repository.</li> | |
</ol> | |
<p>If any problems are detected, they should be fixed on the trunk (except for issues specific to the | |
release branch) and then merged to the release branch.</p> | |
<p>Next update the relevant documents for the new release:</p> | |
<ol> | |
<li>Update the <tt>release-notes.html</tt> file on the release branch (since the content of this file is replaced | |
with every release, there is no need to keep it in sync with the trunk, except if the template changes).</li> | |
<li>Update the <tt>src/site/xdoc/index.xml</tt> file with a description of the release and add an entry for | |
the release in <tt>src/site/xdoc/download.xml</tt>. To avoid extra work for the RM doing the next major release, | |
these changes should be done on the trunk first and then merged to the release branch. | |
If the release is a maintenance release, then the previous release from that branch must be prepared | |
for archiving by changing the links in the download page. This is necessary to conform to the | |
<a href="http://www.apache.org/dev/release.html#when-to-archive">release archiving policy</a>. If the release | |
is a major release, then this should be done with the release from the oldest branch, unless it is expected | |
that users will still continue to download and use that release.</li> | |
</ol> | |
</subsection> | |
<subsection name="Pre-requisites"> | |
<p>The following things are required to perform the actual release:</p> | |
<ul> | |
<li>A PGP key that conforms to the <a href="http://www.apache.org/dev/release-signing.html">requirements for | |
Apache release signing</a>. To make the release process easier, the passphrase for the code signing key should | |
be configured in <tt>${user.home}/.m2/settings.xml</tt>: | |
<pre><![CDATA[<settings> | |
... | |
<profiles> | |
<profile> | |
<id>apache-release</id> | |
<properties> | |
<gpg.passphrase><!-- key passphrase --></gpg.passphrase> | |
</properties> | |
</profile> | |
</profiles> | |
... | |
</settings>]]></pre></li> | |
<li>The release process uses a Nexus staging repository. Every committer should have access to the corresponding | |
staging profile in Nexus. To validate this, login to <a href="https://repository.apache.org">repository.apache.org</a> | |
and check that you can see the <tt>org.apache.axis2</tt> staging profile. The credentials used to deploy to Nexus | |
should be added to <tt>settings.xml</tt>: | |
<pre><![CDATA[<servers> | |
... | |
<server> | |
<id>apache.releases.https</id> | |
<username><!-- ASF username --></username> | |
<password><!-- ASF LDAP password --></password> | |
</server> | |
... | |
</servers>]]></pre></li> | |
</ul> | |
</subsection> | |
<subsection name="Release"> | |
<p>In order to prepare the release artifacts for vote, execute the following steps:</p> | |
<ol> | |
<li>Update the release date in <tt>release-notes.html</tt>, <tt>src/site/xdoc/index.xml</tt> and | |
<tt>src/site/xdoc/download.xml</tt>. Since it is not possible to predict the exact date when the | |
release is officially announced, this should be the date when the release tag is created.</li> | |
<li>Temporarily disable the Hudson build(s) for Axis2, in order to avoid accidental deployment of the release | |
candidate to the local repository of a Hudson executor if the release process fails somewhere in the middle and/or | |
a Hudson build starts at the wrong moment.</li> | |
<li>Start the release process using the following command: | |
<pre>mvn release:prepare -Peverything</pre> | |
When asked for a tag name, use the following format: <tt>vX.Y.Z</tt>. The <tt>everything</tt> profile | |
makes sure that the version numbers of all Maven modules are incremented properly. | |
The execution of the <tt>release:prepare</tt> goal may fail for users in | |
locations that use the EU Subversion server. If this happens, | |
wait for a minute (so that the EU server can catch up with its master) and simply rerun the command. | |
It will continue where the error occurred.</li> | |
<li>Perform the release using the following command: | |
<pre>mvn release:perform</pre></li> | |
<li>Login to Nexus and close the staging repository. For more details about this step, see | |
<a href="https://docs.sonatype.org/display/Repository/Closing+a+Staging+Repository">here</a>.</li> | |
<li>Deploy the distributions to your <tt>public_html</tt> area on <tt>people.apache.org</tt>. | |
The <tt>release:perform</tt> goal should have produced all the necessary files in the | |
<tt>target/checkout/target/axis2-<version>-dists</tt> folder. Please preserve the directory structure and | |
file names because they exactly match the requirements for deployment to <tt>www.apache.org</tt> | |
(see below).</li> | |
<li>Generate and deploy the Maven site to your <tt>public_html</tt> area on <tt>people.apache.org</tt> | |
(either by building the site locally and transfer the files to <tt>people.apache.org</tt>, or by | |
checking out the release tag and building the site directly on <tt>people.apache.org</tt>).</li> | |
<li>Start the release vote by sending a mail to <tt>java-dev@axis.apache.org</tt>. | |
The mail should mention the following things: | |
<ul> | |
<li>The list of issues solved in the release (by linking to the relevant JIRA view).</li> | |
<li>A link to the Nexus staging repository.</li> | |
<li>The URL on <tt>people.apache.org</tt> where the distributions can be downloaded.</li> | |
<li>A link to the preview of the Maven site.</li> | |
</ul> | |
</li> | |
<li>Reenable the Hudson build(s).</li> | |
</ol> | |
<p>If the vote passes, execute the following steps:</p> | |
<ol> | |
<li>Promote the artifacts in the staging repository. See | |
<a href="https://docs.sonatype.org/display/Repository/Releasing+a+Staging+Repository">here</a> | |
for detailed instructions for this step.</li> | |
<li>Login to <tt>people.apache.org</tt> and copy the distributions (including the checksums and | |
signatures) to <tt>/www/www.apache.org/dist/axis/axis2/java/core/</tt>. If you followed the | |
steps described above, then you should already have everything that is needed in your <tt>public_html</tt> | |
folder and you only need to copy the <tt>X.Y.Z</tt> folder to the right location. Please execute the | |
copy with umask 0002 and check that the files and directories have the right permissions (write access for the | |
<tt>axis</tt> group).</li> | |
<li>Check out the current Axis2 site from <a href="https://svn.apache.org/repos/asf/axis/axis2/java/core/site/">https://svn.apache.org/repos/asf/axis/axis2/java/core/site/</a> | |
and synchronize it with the site for the new release. The site should have been generated during the | |
release build and can be found in the <tt>target/checkout/target/site</tt>. Alternatively you can | |
check out the release tag and rebuild the site using <tt>mvn site</tt>, or extract it from the | |
documents distribution. Axiom has a script (see <tt>etc/syncsite.py</tt>) that can be used to | |
synchronize the site in Subversion. It takes care of executing the relevant <tt>svn add</tt> | |
and <tt>svn remove</tt> commands on the local working copy of the site.</li> | |
<li>Login to <tt>people.apache.org</tt> and update the local working copy of the site: | |
<pre>umask 0002 | |
cd /www/axis.apache.org/axis2/java/core | |
svn update</pre></li> | |
</ol> | |
<p>It may take several hours before everything has been synchronized. Before proceeding, check that</p> | |
<ul> | |
<li>the Maven artifacts for the release are available from the Maven central repository;</li> | |
<li>the Maven site has been synchronized;</li> | |
<li>the distributions can be downloaded from the mirror sites.</li> | |
</ul> | |
<p>Once everything is in place, send announcements to <tt>java-user@axis.apache.org</tt> (with copy to | |
<tt>java-dev@axis.apache.org</tt>) and <tt>announce@apache.org</tt>. Since the two lists have different conventions, | |
audiences and moderation policies, it is recommended to send the announcement separately to the two lists. | |
Note that mail to <tt>announce@apache.org</tt> must be sent from an <tt>apache.org</tt> address and will | |
always be moderated. The announcement sent to <tt>announce@apache.org</tt> also should include a general description | |
of Axis2, because not everybody subscribed to that list knows about the project.</p> | |
</subsection> | |
<subsection name="Post-release actions"> | |
<ol> | |
<li>Update the DOAP file (<tt>etc/doap_Axis2.rdf</tt>) and add a new entry for the release.</li> | |
<li>Update the status of the release version in JIRA.</li> | |
<li>Remove archived releases from <tt>/www/www.apache.org/dist/axis</tt> on <tt>people.apache.org</tt>.</li> | |
</ol> | |
</subsection> | |
</section> | |
</body> | |
</document> |