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>[email protected]</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>[email protected]</tt> (with copy to
- <tt>[email protected]</tt>) and
<tt>[email protected]</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>[email protected]</tt> must be sent
from an <tt>apache.org</tt> address and will
- always be moderated. The announcement sent to
<tt>[email protected]</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 `[email protected]`.
+ 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 `[email protected]`
(with copy to
+`[email protected]`) and `[email protected]`. 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 `[email protected]` must be sent from an `apache.org`
address and will
+always be moderated. The announcement sent to `[email protected]` 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`.
