| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| 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 |
| |
| https://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 https://maven.apache.org/xsd/xdoc-2.0.xsd"> |
| <properties> |
| <title>Overview</title> |
| <author email="dev@commons.apache.org">Apache Commons Team</author> |
| </properties> |
| |
| <body> |
| |
| <section name="Release Plugin"> |
| |
| <p> |
| This is a <a href="https://maven.apache.org/">Maven 3.x</a> Plugin which is |
| used by <a href="https://commons.apache.org/">Apache Commons</a> releases. See |
| the <a href="development.html">Development</a> page for information to |
| help maintain this plugin. |
| </p> |
| |
| <p>The main purpose of the plugin is to automate the steps of our, namely |
| The Apache Commons Project's, release process. Currently we have the mechanics |
| for detaching distribution artifacts (i.e. all <code>tar.gz</code> artifacts and |
| signatures as well as all <code>.zip</code> artifacts and signatures), creating |
| a <code>site.zip</code> file, and staging all of those artifacts in a subversion |
| repository (for the most part a subdirectory of |
| <a href="https://dist.apache.org/repos/dist/dev/commons/">https://dist.apache.org/repos/dist/dev/commons/</a>. |
| It can, however, stage to any subversion repository. |
| </p> |
| |
| </section> |
| |
| <section name="Plugin Goals"> |
| <p> |
| Available Goals (which are meant to be used together; the only reason they are separated is for |
| code readability): |
| </p> |
| <ul> |
| <li> |
| <b>commons-release:detach-distributions</b> - Remove |
| <code>tar.gz</code>, <code>tar.gz.asc</code>, <code>zip</code>, and <code>zip.asc</code> |
| files from being uploaded to nexus and copy them to the <code>target/commons-release-plugin</code> |
| directory. |
| </li> |
| <li> |
| <b>commons-release:stage-distributions</b> - Take all staged files in the |
| <code>target/commons-release-plugin</code> directory, and the <code>RELEASE-NOTES.txt</code> from |
| the root of the project, and commit them to a specified staging subversion repository. |
| </li> |
| <li> |
| <a href="vote-txt.html">commons-release:vote-txt</a> -Dcommons.nexus.repo.id=nnnn [-Dgit.tag.name] # where nnn is the number following orgapachecommons- in the Nexus 'Repository' column |
| </li> |
| </ul> |
| </section> |
| |
| <section name="Using the plugin"> |
| <p> |
| Configure the plugin as the last plugin in the<code><build></code> section of the <code>pom.xml</code> |
| </p> |
| <p>This is now done in the Commons Parent POM, so is not needed in the component POM.</p> |
| <source><![CDATA[ |
| <plugin> |
| <groupId>org.apache.commons</groupId> |
| <artifactId>commons-release-plugin</artifactId> |
| <version>1.8.0</version> |
| <executions> |
| <execution> |
| <id>clean-staging</id> |
| <phase>post-clean</phase> |
| <goals> |
| <goal>clean-staging</goal> |
| </goals> |
| </execution> |
| <execution> |
| <id>detach-distributions</id> |
| <phase>verify</phase> |
| <goals> |
| <goal>detach-distributions</goal> |
| </goals> |
| </execution> |
| <execution> |
| <id>stage-distributions</id> |
| <phase>deploy</phase> |
| <goals> |
| <goal>stage-distributions</goal> |
| </goals> |
| </execution> |
| </executions> |
| </plugin> |
| ]]></source> |
| <p> |
| The following properties need to be defined in the component POM if not already defined |
| </p> |
| <source><![CDATA[ |
| <properties> |
| <!-- Previous version of the component (used for reporting binary compatibility check)--> |
| <commons.bc.version>m.n</commons.bc.version> |
| <commons.release.isDistModule>true</commons.release.isDistModule> |
| </properties> |
| ]]></source> |
| <p> |
| Ensure your Release Manager details are defined in your Maven <code>~/.m2/settings.xml</code> file |
| (These are used by the vote-txt goal) |
| Properties have to be defined in a profile. For example: |
| </p> |
| <source><![CDATA[ |
| <settings> |
| ... |
| <profiles> |
| ... |
| <profile> |
| <id>active-profile</id> |
| <properties> |
| <commons.releaseManagerName>Your Name</commons.releaseManagerName> |
| <commons.releaseManagerKey>Your Signing Key Hex ID</commons.releaseManagerKey> |
| </properties> |
| </profile> |
| </profiles> |
| |
| <activeProfiles> |
| <!-- define active profile name --> |
| <activeProfile>active-profile</activeProfile> |
| </activeProfiles> |
| ... |
| </settings> |
| ]]></source> |
| <p> |
| After the above configuration performing the release would occur by (<i>note.</i> more |
| in depth details can be found at |
| <a href="https://commons.apache.org/releases/prepare.html">Preparations For A Release</a>): |
| </p> |
| <ol> |
| <li>creating our release branch,</li> |
| <li>checking compatibility,</li> |
| <li>checking your dependencies,</li> |
| <li>checking javadocs and code style,</li> |
| <li>checking the apache license,</li> |
| <li>configure the build to generate a complete set of release artifacts,</li> |
| <li>preparing the release notes, updating the download file and other autogenerated files,</li> |
| <li>tagging the release candidate, and</li> |
| <li> |
| running the following command: |
| <source><![CDATA[ |
| mvn -Duser.name=<yourApacheId> [-Duser.password=<yourApacheIdsPassword] [-Dcommons.release.dryRun=true -Ptest-deploy] -Prelease clean test site deploy |
| ]]></source></li> |
| </ol> |
| <p> |
| To avoid specifying distribution credentials at the command |
| line, consider using the <code>distServer</code> plugin configuration parameter (property <code>commons.distServer</code>) |
| to specify a server definition in Maven <code>settings.xml</code> which defines your (encrypted, right?) authentication info. |
| </p> |
| <p> |
| If the component is new, then, before running this maven command, you would want to create |
| the requisite subversion directory <code>https://dist.apache.org/repos/dist/dev/commons/foo</code>. Notice, |
| that the way to perform a dry run of the release you need to include |
| <code>-Dcommons.release.dryRun=true -Ptest-deploy</code>. |
| </p> |
| </section> |
| </body> |
| </document> |
