You are viewing a plain text version of this content. The canonical link for it is here.
Posted to java-commits@axis.apache.org by ve...@apache.org on 2015/12/27 23:27:22 UTC
svn commit: r1721855 - in /axis/axis2/java/core/trunk/src/site:
markdown/release-process.md xdoc/release-process.xml
Author: veithen
Date: Sun Dec 27 22:27:22 2015
New Revision: 1721855
URL: http://svn.apache.org/viewvc?rev=1721855&view=rev
Log:
Migrate the release process documentation to Markdown.
Added:
axis/axis2/java/core/trunk/src/site/markdown/release-process.md
- copied, changed from r1721278, axis/axis2/java/core/trunk/src/site/xdoc/release-process.xml
Removed:
axis/axis2/java/core/trunk/src/site/xdoc/release-process.xml
Copied: axis/axis2/java/core/trunk/src/site/markdown/release-process.md (from r1721278, axis/axis2/java/core/trunk/src/site/xdoc/release-process.xml)
URL: http://svn.apache.org/viewvc/axis/axis2/java/core/trunk/src/site/markdown/release-process.md?p2=axis/axis2/java/core/trunk/src/site/markdown/release-process.md&p1=axis/axis2/java/core/trunk/src/site/xdoc/release-process.xml&r1=1721278&r2=1721855&rev=1721855&view=diff
==============================================================================
--- axis/axis2/java/core/trunk/src/site/xdoc/release-process.xml (original)
+++ axis/axis2/java/core/trunk/src/site/markdown/release-process.md Sun Dec 27 22:27:22 2015
@@ -1,238 +1,262 @@
-<!--
- ~ 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/site/axis2/java/core/">https://svn.apache.org/repos/asf/axis/site/axis2/java/core/</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.
- The live Web site is updated automatically by svnpubsub once the changes have been committed to SVN.</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>
+<!--
+ ~ 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.
+ -->
+
+Release Process
+===============
+
+Release process overview
+------------------------
+
+### Cutting a branch
+
+* 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.
+
+* As soon as a release is approved (or even before), RM should
+ add the new version into JIRA as a target.
+
+* 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.
+
+* Ideally a release branch is only around for a week or maybe two
+ before the release happens.
+
+* 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.
+
+* Normal development continues on the trunk.
+
+### Dependencies and branches
+
+* 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.
+
+* 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.
+
+### Managing change and issue resolution with a release branch
+
+* 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.
+
+* 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.
+
+* 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.
+
+* When the assignee resolves an issue, they confirm it's been
+ fixed in both branches, if appropriate.
+
+### Checking changes into the branch
+
+* 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.
+
+* 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.
+
+Performing a release
+--------------------
+
+**Note:** performing the release requires at least Maven 2.1.0. The recommended version is 2.2.1.
+
+### Preparation
+
+Verify that the code meets the basic requirements for being releasable:
+
+1. Check the consistency between the metadata in `pom.xml` and `modules/parent/pom.xml`.
+ 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.
+
+2. Check that the set of legal (`legal/*.LICENSE`) files corresponds to the set of third party
+ JARs included in the binary distribution.
+
+3. Check that the `apache-release` profile works correctly and produces the required distributions.
+ The profile can be executed as follows:
+
+ mvn clean install -Papache-release -Dmaven.test.skip=true
+
+4. Check that the source distribution is buildable.
+
+5. Check that the source tree is buildable with an empty local Maven repository.
+
+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.
+
+Next update the relevant documents for the new release:
+
+1. Update the `release-notes.html` 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).
+
+2. Update the `src/site/xdoc/index.xml` file with a description of the release and add an entry for
+ the release in `src/site/xdoc/download.xml`. 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
+ [release archiving policy](http://www.apache.org/dev/release.html#when-to-archive). 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.
+
+### Pre-requisites
+
+The following things are required to perform the actual release:
+
+* A PGP key that conforms to the [requirements for Apache release signing](http://www.apache.org/dev/release-signing.html).
+ To make the release process easier, the passphrase for the code signing key should
+ be configured in `${user.home}/.m2/settings.xml`:
+
+ <settings>
+ ...
+ <profiles>
+ <profile>
+ <id>apache-release</id>
+ <properties>
+ <gpg.passphrase><!-- key passphrase --></gpg.passphrase>
+ </properties>
+ </profile>
+ </profiles>
+ ...
+ </settings>
+
+* 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 [repository.apache.org](https://repository.apache.org)
+ and check that you can see the `org.apache.axis2` staging profile. The credentials used to deploy to Nexus
+ should be added to `settings.xml`:
+
+ <servers>
+ ...
+ <server>
+ <id>apache.releases.https</id>
+ <username><!-- ASF username --></username>
+ <password><!-- ASF LDAP password --></password>
+ </server>
+ ...
+ </servers>
+
+### Release
+
+In order to prepare the release artifacts for vote, execute the following steps:
+
+1. Update the release date in `release-notes.html`, `src/site/xdoc/index.xml` and
+ `src/site/xdoc/download.xml`. 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.
+
+2. 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.
+
+3. Start the release process using the following command:
+
+ mvn release:prepare -Peverything
+
+ When asked for a tag name, use the following format: `vX.Y.Z`. The `everything` profile
+ makes sure that the version numbers of all Maven modules are incremented properly.
+ The execution of the `release:prepare` 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.
+
+4. Perform the release using the following command:
+
+ mvn release:perform
+
+5. Login to Nexus and close the staging repository. For more details about this step, see
+ [here](https://docs.sonatype.org/display/Repository/Closing+a+Staging+Repository).
+
+6. Deploy the distributions to your `public_html` area on `people.apache.org`.
+ The `release:perform` goal should have produced all the necessary files in the
+ `target/checkout/target/axis2-<version>-dists` folder. Please preserve the directory structure and
+ file names because they exactly match the requirements for deployment to `www.apache.org`
+ (see below).
+
+7. Generate and deploy the Maven site to your `public_html` area on `people.apache.org`
+ (either by building the site locally and transfer the files to `people.apache.org`, or by
+ checking out the release tag and building the site directly on `people.apache.org`).
+
+8. Start the release vote by sending a mail to `java-dev@axis.apache.org`.
+ The mail should mention the following things:
+
+ * The list of issues solved in the release (by linking to the relevant JIRA view).
+ * A link to the Nexus staging repository.
+ * The URL on `people.apache.org` where the distributions can be downloaded.
+ * A link to the preview of the Maven site.
+
+9. Reenable the Hudson build(s).
+
+If the vote passes, execute the following steps:
+
+1. Promote the artifacts in the staging repository. See
+ [here](https://docs.sonatype.org/display/Repository/Releasing+a+Staging+Repository)
+ for detailed instructions for this step.
+
+2. Login to `people.apache.org` and copy the distributions (including the checksums and
+ signatures) to `/www/www.apache.org/dist/axis/axis2/java/core/`. If you followed the
+ steps described above, then you should already have everything that is needed in your `public_html`
+ folder and you only need to copy the `X.Y.Z` 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
+ `axis` group).
+
+3. Check out the current Axis2 site from <https://svn.apache.org/repos/asf/axis/site/axis2/java/core/>
+ 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 `target/checkout/target/site`. Alternatively you can
+ check out the release tag and rebuild the site using `mvn site`, or extract it from the
+ documents distribution. Axiom has a script (see `etc/syncsite.py`) that can be used to
+ synchronize the site in Subversion. It takes care of executing the relevant `svn add`
+ and `svn remove` commands on the local working copy of the site.
+ The live Web site is updated automatically by svnpubsub once the changes have been committed to SVN.
+
+It may take several hours before everything has been synchronized. Before proceeding, check that
+
+* the Maven artifacts for the release are available from the Maven central repository;
+* the Maven site has been synchronized;
+* the distributions can be downloaded from the mirror sites.
+
+Once everything is in place, send announcements to `java-user@axis.apache.org` (with copy to
+`java-dev@axis.apache.org`) and `announce@apache.org`. 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 `announce@apache.org` must be sent from an `apache.org` address and will
+always be moderated. The announcement sent to `announce@apache.org` also should include a general description
+of Axis2, because not everybody subscribed to that list knows about the project.
+
+### Post-release actions
+
+1. Update the DOAP file (`etc/doap_Axis2.rdf`) and add a new entry for the release.
+
+2. Update the status of the release version in JIRA.
+
+3. Remove archived releases from `/www/www.apache.org/dist/axis` on `people.apache.org`.