| <!-- | |
| ~ 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> |