This is an automated email from the ASF dual-hosted git repository.
veithen pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/ws-axiom.git
The following commit(s) were added to refs/heads/master by this push:
new 3499e7a8a Convert the release process documentation to markdown
3499e7a8a is described below
commit 3499e7a8aa565d87ac5e4a6d17fd72e71afe04d2
Author: Andreas Veithen-Knowles <[email protected]>
AuthorDate: Sat Feb 21 09:28:44 2026 +0000
Convert the release process documentation to markdown
---
devguide/src/docbkx/devguide.xml | 396 ---------------------------------------
docs/release-process.md | 209 +++++++++++++++++++++
2 files changed, 209 insertions(+), 396 deletions(-)
diff --git a/devguide/src/docbkx/devguide.xml b/devguide/src/docbkx/devguide.xml
index 04c9f1838..ae77513df 100644
--- a/devguide/src/docbkx/devguide.xml
+++ b/devguide/src/docbkx/devguide.xml
@@ -403,402 +403,6 @@
javax.xml.stream.XMLOutputFactory=com.bea.xml.stream.XMLOutputFactoryBase</progr
</section>
</chapter>
- <chapter>
- <title>Release process</title>
- <section>
- <title>Release preparation</title>
- <para>
- The following items should be checked before starting the
release process:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Check that the generated Javadoc contains the
appropriate set of packages, i.e. only the public API.
- This excludes classes from
<filename>axiom-impl</filename> and <filename>axiom-dom</filename> as well as
classes
- related to unit tests.
- </para>
- </listitem>
- <listitem>
- <para>
- Check that all dependencies and plugins are available
from standard
- repositories. To do this, clean the local repository
and execute
- <command>mvn clean install</command> followed by
<command>mvn site</command>.
- </para>
- </listitem>
- <listitem>
- <para>
- Check that the set of license files in the
<filename>legal</filename> directory
- is complete and accurate (by checking that in the
binary distribution, there is a license file
- for every third party JAR in the
<filename>lib</filename> folder).
- </para>
- </listitem>
- <listitem>
- <para>
- Check that the Maven site conforms to the latest
version of the
- <link
xlink:href="http://apache.org/foundation/marks/pmcs";>Apache Project
- Branding Guidelines</link>.
- </para>
- </listitem>
- <listitem>
- <para>
- Check that the <literal>apache-release</literal>
profile can be executed properly.
- To do this, issue the following command:
- </para>
- <screen>mvn clean install -Papache-release
-DskipTests=true</screen>
- <para>
- You may also execute a dry run of the release process:
- </para>
- <screen>mvn release:prepare -DdryRun=true</screen>
- <para>
- After this, you need to clean up using the following
command:
- </para>
- <screen>mvn release:clean</screen>
- </listitem>
- <listitem>
- <para>
- Check that the Maven site can be generated and
deployed successfully, and that it has
- the expected content.
- </para>
- </listitem>
- <listitem>
- <para>
- Complete the release note
(<filename>src/site/markdown/release-notes/<replaceable>version</replaceable>.md</filename>).
- It should include a description of the major
- changes in the release as well as a list of resolved
JIRA issues.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Prerequisites</title>
- <para>
- The following things are required to perform the actual
release:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- A PGP key that conforms to the <link
xlink:href="http://www.apache.org/dev/release-signing.html";>requirement
- for Apache release signing</link>. To make the release
process easier, the passphrase for the
- code signing key should be configured in
<filename>${user.home}/.m2/settings.xml</filename>:
- </para>
-<screen><![CDATA[<settings>
- ...
- <profiles>
- <profile>
- <id>apache-release</id>
- <properties>
- <gpg.passphrase><!-- KEY PASSPHRASE --></gpg.passphrase>
- </properties>
- </profile>
- </profiles>
- ...
-</settings>]]></screen>
- </listitem>
- <listitem>
- <para>
- 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
<literal>repository.apache.org</literal> and check that
- you can see the <literal>org.apache.ws</literal>
staging profile. The credentials used to deploy to Nexus
- should be added to <filename>settings.xml</filename>:
- </para>
-<screen><![CDATA[<servers>
- ...
- <server>
- <id>apache.releases.https</id>
- <username><!-- ASF username --></username>
- <password><!-- ASF LDAP password --></password>
- </server>
- ...
-</servers>]]></screen>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>Release</title>
- <para>
- In order to prepare the release artifacts for vote, execute
the following steps:
- </para>
- <procedure>
- <step>
- <para>
- If necessary, update the copyright date in the top
level <filename>NOTICE</filename> file.
- </para>
- </step>
- <step>
- <para>
- Start the release process with the following command -
use 'mvn release:rollback' to undo and be aware that in the main pom.xml there
is an apache parent that defines some plugin versions. See <link
xlink:href="https://maven.apache.org/pom/asf"/>
- </para>
- <screen>mvn release:prepare</screen>
- <para>
- When asked for the "SCM release tag or label", keep
the default value
- (<literal>x.y.z</literal>).
- </para>
- <para>
- The above command will create a tag in Subversion and
increment the version
- number of the trunk to the next development version.
It will also create
- a <filename>release.properties</filename> file that
will be used in the next step.
- </para>
- </step>
- <step>
- <para>
- Perform the release using the following command:
- </para>
- <screen>mvn release:perform</screen>
- <para>
- This will upload the release artifacts to the Nexus
staging repository.
- </para>
- </step>
- <step>
- <para>
- Log in to the Nexus repository (<link
xlink:href="https://repository.apache.org/"/>
- and close the staging repository. The name of the
staging profile is
- <literal>org.apache.ws</literal>. See <link
xlink:href="https://maven.apache.org/developers/release/maven-project-release-procedure.html"/>
- for a more thorough description of this step.
- </para>
- </step>
- <step>
- <para>
- Execute the
<filename>target/checkout/etc/dist.py</filename> script to upload the source
and binary distributions to
- the development area of the <link
xlink:href="https://dist.apache.org/repos/dist/"/> repository.
- </para>
- <para>
- If not yet done, export your public key and append it
to <link
xlink:href="https://dist.apache.org/repos/dist/release/ws/axiom/KEYS"/>.
- The command to export a public key is as follows:
- </para>
- <screen>gpg --armor --export
<replaceable>key_id</replaceable></screen>
- <para>
- If you have multiple keys, you can define a
~/.gnupg/gpg.conf file for a default. Note that while 'gpg --list-keys' will
show your public keys, using maven-release-plugin with the command
'release:perform' below requires 'gpg --list-secret-keys' to have a valid entry
that matches your public key, in order to create 'asc' files that are used to
verify the release artifcats. 'release:prepare' creates the sha512 checksum
files.
- </para>
- <para>
- The created artifacts i.e. zip files can be checked
with, for example, sha512sum 'axiom-2.0.0-bin.zip' which should match the
generated sha512 files. In that example, use 'gpg --verify
axiom-2.0.0-bin.zip.asc axiom-2.0.0-bin.zip.asc to verify the artifacts were
signed correctly.
- </para>
- </step>
- <step>
- <para>
- Delete <link
xlink:href="https://svn.apache.org/repos/asf/webservices/website/axiom-staging/"/>
if it exists.
- Create a new staging area for the site:
- </para>
-<screen>svn copy \
- https://svn.apache.org/repos/asf/webservices/website/axiom \
- https://svn.apache.org/repos/asf/webservices/website/axiom-staging</screen>
- <tip>
- <para>
- This step can be skipped if the staging area has
already been created earlier (e.g. to test a snapshot version of the site).
- </para>
- </tip>
- </step>
- <step>
- <para>
- Change to the <filename>target/checkout</filename>
directory and prepare the site using the following commands:
- </para>
-<screen>mvn site-deploy
-mvn scm-publish:publish-scm -Dscmpublish.skipCheckin=true</screen>
- <para>
- The staging area will be checked out to
<filename>target/scmpublish-checkout</filename> (relative to
- <filename>target/checkout</filename>). Do a sanity
check on the changes and then commit them.
- </para>
- </step>
- <step>
- <para>
- Start the release vote by sending a mail to
<literal>[email protected]</literal>.
- The mail should mention the following things:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The list of issues solved in the release (by
linking to the relevant
- JIRA view).
- </para>
- </listitem>
- <listitem>
- <para>
- The location of the Nexus staging repository.
- </para>
- </listitem>
- <listitem>
- <para>
- The link to the source and binary
distributions:
-
<literal>https://dist.apache.org/repos/dist/dev/ws/axiom/<replaceable>version</replaceable></literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- A link to the preview of the Maven site: <link
xlink:href="http://ws.apache.org/axiom-staging/"/>.
- </para>
- </listitem>
- </itemizedlist>
- </step>
- </procedure>
- <para>
- If the vote passes, execute the following steps:
- </para>
- <procedure>
- <step>
- <para>
- Promote the artifacts in the staging repository. See
- <link
xlink:href="https://central.sonatype.org/publish/release/#close-and-drop-or-release-your-staging-repository"/>
- for detailed instructions for this step.
- </para>
- </step>
- <step>
- <para>
- Publish the distributions:
- </para>
-<screen>svn mv
https://dist.apache.org/repos/dist/dev/ws/axiom/<replaceable>version</replaceable>
\
- https://dist.apache.org/repos/dist/release/ws/axiom/</screen>
- <para>
- <replaceable>version</replaceable> is the release
version, e.g. <literal>1.2.9</literal>.
- </para>
- </step>
- <step>
- <para>
- Publish the site:
- </para>
-<screen>svn co --depth=immediates
https://svn.apache.org/repos/asf/webservices/website ws-site
-cd ws-site
-svn rm axiom
-svn mv axiom-staging axiom
-svn commit</screen>
- </step>
- </procedure>
- <para>
- It may take several hours before all the updates have been
synchronized to the relevant
- ASF systems. Before proceeding, check that
- </para>
- <itemizedlist>
- <listitem>
- <para>
- the Maven artifacts for the release are available from
the Maven central repository;
- </para>
- </listitem>
- <listitem>
- <para>
- the Maven site has been synchronized to <link
xlink:href="http://ws.apache.org/axiom/"/>;
- </para>
- </listitem>
- <listitem>
- <para>
- the binary and source distributions can be downloaded
from <link xlink:href="http://ws.apache.org/axiom/download.html"/>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Once everything is in place, send announcements to
<literal>[email protected]</literal>
- and <literal>[email protected]</literal>. Since the two
lists have different conventions, audiences
- and moderation policies, to send the announcement separately
to the two lists.
- </para>
- <para>
- Sample announcement:
- </para>
- <blockquote>
- <para>
- Apache Axiom Team is pleased to announce the release of
Axiom x.y.z. The release is available
- for download at:
- </para>
- <para>
- http://ws.apache.org/axiom/download.cgi
- </para>
- <para>
- Apache Axiom is a StAX-based, XML Infoset compliant object
model which supports on-demand building
- of the object tree. It supports a novel "pull-through"
model which allows one to turn off the tree
- building and directly access the underlying pull event
stream. It also has built in support for
- XML Optimized Packaging (XOP) and MTOM, the combination of
which allows XML to carry binary
- data efficiently and in a transparent manner. The
combination of these is an easy to use API
- with a very high performant architecture!
- </para>
- <para>
- Developed as part of Apache Axis2, Apache Axiom is the
core of Apache Axis2. However, it is a
- pure standalone XML Infoset model with novel features and
can be used independently of Apache Axis2.
- </para>
- <para>
- Highlights in this release:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- ...
- </para>
- </listitem>
- <listitem>
- <para>
- ...
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Resolved JIRA issues:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- [WSCOMMONS-513] Behavior of insertSiblingAfter and
insertSiblingBefore is not well defined for orphan nodes
- </para>
- </listitem>
- <listitem>
- <para>
- [WSCOMMONS-488] The sequence of events produced by
OMStAXWrapper with inlineMTOM=false is inconsistent
- </para>
- </listitem>
- </itemizedlist>
- </blockquote>
- <para>
- For <literal>[email protected]</literal>, the subject
(<quote>Axiom x.y.z released</quote>) should be
- prefixed with <quote>[ANN][Axiom]</quote>, while for
<literal>[email protected]</literal>
- <quote>[ANN]</quote> is enough. Note that mail to
<literal>[email protected]</literal> must be
- sent from an <literal>apache.org</literal> address.
- </para>
- </section>
- <section>
- <title>Post-release actions</title>
- <itemizedlist>
- <listitem>
- <para>
- Update the DOAP file (see
<filename>etc/axiom.rdf</filename>) and add a new entry
- for the release.
- </para>
- </listitem>
- <listitem>
- <para>
- Update the status of the release version in the AXIOM
project in JIRA.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove archived releases from <link
xlink:href="https://dist.apache.org/repos/dist/release/ws/axiom/"/>.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section>
- <title>References</title>
- <para>
- The following documents are useful when preparing and
executing the release:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <link
xlink:href="http://www.apache.org/legal/src-headers.html";>ASF Source Header and
Copyright Notice Policy</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link
xlink:href="http://apache.org/foundation/marks/pmcs";>Apache Project Branding
Guidelines</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link
xlink:href="http://projects.apache.org/doap.html";>DOAP Files</link>
- </para>
- </listitem>
- <listitem>
- <para>
- <link
xlink:href="http://www.apache.org/dev/release-publishing.html";>Publishing
Releases</link>
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </chapter>
-
<appendix>
<title>Appendix</title>
<section xml:id="install.ibm.jdk">
diff --git a/docs/release-process.md b/docs/release-process.md
new file mode 100644
index 000000000..d395b1926
--- /dev/null
+++ b/docs/release-process.md
@@ -0,0 +1,209 @@
+# Release process
+
+## Release preparation
+
+The following items should be checked before starting the release process:
+
+- Check that the generated Javadoc contains the appropriate set of packages,
i.e. only the public API. This excludes classes from `axiom-impl` and
`axiom-dom` as well as classes related to unit tests.
+
+- Check that all dependencies and plugins are available from standard
repositories. To do this, clean the local repository and execute `mvn clean
install` followed by `mvn site`.
+
+- Check that the set of license files in the `legal` directory is complete
and accurate (by checking that in the binary distribution, there is a license
file for every third party JAR in the `lib` folder).
+
+- Check that the Maven site conforms to the latest version of the [Apache
Project Branding Guidelines](http://apache.org/foundation/marks/pmcs).
+
+- Check that the `apache-release` profile can be executed properly. To do
this, issue the following command:
+
+ ```sh
+ mvn clean install -Papache-release -DskipTests=true
+ ```
+
+ You may also execute a dry run of the release process:
+
+ ```sh
+ mvn release:prepare -DdryRun=true
+ ```
+
+ After this, you need to clean up using the following command:
+
+ ```sh
+ mvn release:clean
+ ```
+
+- Check that the Maven site can be generated and deployed successfully, and
that it has the expected content.
+
+- Complete the release note
(`src/site/markdown/release-notes/<version>.md`). It should include a
description of the major changes in the release as well as a list of resolved
JIRA issues.
+
+## Prerequisites
+
+The following things are required to perform the actual release:
+
+- A PGP key that conforms to the [requirement 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`:
+
+ ```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` and check that you can see the
`org.apache.ws` staging profile. The credentials used to deploy to Nexus should
be added to `settings.xml`:
+
+ ```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. If necessary, update the copyright date in the top level `NOTICE` file.
+
+2. Start the release process with the following command - use `mvn
release:rollback` to undo and be aware that in the main `pom.xml` there is an
apache parent that defines some plugin versions. See
<https://maven.apache.org/pom/asf>
+
+ ```sh
+ mvn release:prepare
+ ```
+
+ When asked for the "SCM release tag or label", keep the default value
(`x.y.z`).
+
+ The above command will create a tag in Subversion and increment the
version number of the trunk to the next development version. It will also
create a `release.properties` file that will be used in the next step.
+
+3. Perform the release using the following command:
+
+ ```sh
+ mvn release:perform
+ ```
+
+ This will upload the release artifacts to the Nexus staging repository.
+
+4. Log in to the Nexus repository (<https://repository.apache.org/>) and
close the staging repository. The name of the staging profile is
`org.apache.ws`. See
<https://maven.apache.org/developers/release/maven-project-release-procedure.html>
for a more thorough description of this step.
+
+5. Execute the `target/checkout/etc/dist.py` script to upload the source and
binary distributions to the development area of the
<https://dist.apache.org/repos/dist/> repository.
+
+ If not yet done, export your public key and append it to
<https://dist.apache.org/repos/dist/release/ws/axiom/KEYS>. The command to
export a public key is as follows:
+
+ ```sh
+ gpg --armor --export <key_id>
+ ```
+
+ If you have multiple keys, you can define a `~/.gnupg/gpg.conf` file for a
default. Note that while `gpg --list-keys` will show your public keys, using
maven-release-plugin with the command `release:perform` below requires `gpg
--list-secret-keys` to have a valid entry that matches your public key, in
order to create `asc` files that are used to verify the release artifcats.
`release:prepare` creates the sha512 checksum files.
+
+ The created artifacts i.e. zip files can be checked with, for example,
`sha512sum 'axiom-2.0.0-bin.zip'` which should match the generated sha512
files. In that example, use `gpg --verify axiom-2.0.0-bin.zip.asc
axiom-2.0.0-bin.zip.asc` to verify the artifacts were signed correctly.
+
+6. Delete
<https://svn.apache.org/repos/asf/webservices/website/axiom-staging/> if it
exists. Create a new staging area for the site:
+
+ ```sh
+ svn copy \
+ https://svn.apache.org/repos/asf/webservices/website/axiom \
+ https://svn.apache.org/repos/asf/webservices/website/axiom-staging
+ ```
+
+ This step can be skipped if the staging area has already been created
earlier (e.g. to test a snapshot version of the site).
+
+7. Change to the `target/checkout` directory and prepare the site using the
following commands:
+
+ ```sh
+ mvn site-deploy
+ mvn scm-publish:publish-scm -Dscmpublish.skipCheckin=true
+ ```
+
+ The staging area will be checked out to `target/scmpublish-checkout`
(relative to `target/checkout`). Do a sanity check on the changes and then
commit them.
+
+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).
+ - The location of the Nexus staging repository.
+ - The link to the source and binary distributions:
`https://dist.apache.org/repos/dist/dev/ws/axiom/<version>`.
+ - A link to the preview of the Maven site:
<http://ws.apache.org/axiom-staging/>.
+
+If the vote passes, execute the following steps:
+
+1. Promote the artifacts in the staging repository. See
<https://central.sonatype.org/publish/release/#close-and-drop-or-release-your-staging-repository>
for detailed instructions for this step.
+
+2. Publish the distributions:
+
+ ```sh
+ svn mv https://dist.apache.org/repos/dist/dev/ws/axiom/<version> \
+ https://dist.apache.org/repos/dist/release/ws/axiom/
+ ```
+
+ `<version>` is the release version, e.g. `1.2.9`.
+
+3. Publish the site:
+
+ ```sh
+ svn co --depth=immediates
https://svn.apache.org/repos/asf/webservices/website ws-site
+ cd ws-site
+ svn rm axiom
+ svn mv axiom-staging axiom
+ svn commit
+ ```
+
+It may take several hours before all the updates have been synchronized to the
relevant ASF systems. Before proceeding, check that:
+
+- the Maven artifacts for the release are available from the Maven central
repository;
+- the Maven site has been synchronized to <http://ws.apache.org/axiom/>;
+- the binary and source distributions can be downloaded from
<http://ws.apache.org/axiom/download.html>.
+
+Once everything is in place, send announcements to `[email protected]` and
`[email protected]`. Since the two lists have different conventions,
audiences and moderation policies, to send the announcement separately to the
two lists.
+
+Sample announcement:
+
+> Apache Axiom Team is pleased to announce the release of Axiom x.y.z. The
release is available
+> for download at:
+>
+> http://ws.apache.org/axiom/download.cgi
+>
+> Apache Axiom is a StAX-based, XML Infoset compliant object model which
supports on-demand building
+> of the object tree. It supports a novel "pull-through" model which allows
one to turn off the tree
+> building and directly access the underlying pull event stream. It also has
built in support for
+> XML Optimized Packaging (XOP) and MTOM, the combination of which allows XML
to carry binary
+> data efficiently and in a transparent manner. The combination of these is an
easy to use API
+> with a very high performant architecture!
+>
+> Developed as part of Apache Axis2, Apache Axiom is the core of Apache Axis2.
However, it is a
+> pure standalone XML Infoset model with novel features and can be used
independently of Apache Axis2.
+>
+> Highlights in this release:
+>
+> - ...
+> - ...
+>
+> Resolved JIRA issues:
+>
+> - [WSCOMMONS-513] Behavior of insertSiblingAfter and insertSiblingBefore is
not well defined for orphan nodes
+> - [WSCOMMONS-488] The sequence of events produced by OMStAXWrapper with
inlineMTOM=false is inconsistent
+
+For `[email protected]`, the subject ("Axiom x.y.z released") should be
prefixed with "[ANN][Axiom]", while for `[email protected]` "[ANN]" is
enough. Note that mail to `[email protected]` must be sent from an
`apache.org` address.
+
+## Post-release actions
+
+- Update the DOAP file (see `etc/axiom.rdf`) and add a new entry for the
release.
+- Update the status of the release version in the AXIOM project in JIRA.
+- Remove archived releases from
<https://dist.apache.org/repos/dist/release/ws/axiom/>.
+
+## References
+
+The following documents are useful when preparing and executing the release:
+
+- [ASF Source Header and Copyright Notice
Policy](http://www.apache.org/legal/src-headers.html)
+- [Apache Project Branding Guidelines](http://apache.org/foundation/marks/pmcs)
+- [DOAP Files](http://projects.apache.org/doap.html)
+- [Publishing Releases](http://www.apache.org/dev/release-publishing.html)
