Apache Maven is a software project management and comprehension tool. Based on the concept of a project object model (POM), Maven can manage a project's build, reporting and documentation from a central piece of information.
This document describes how to release Maven artifacts for Apache Software Foundation projects to the Maven Central Repository. This is optional. Apache project must release all software packages through the ASF mirror system. See Release distribution policy for more details.
Note make sure you are using version 3.0.5 or newer of Maven. You can download and install the latest version of Maven before continuing.
The ASF Nexus repository enforces security by constraining who can deploy or release a project's artifacts. Nexus maps which artifacts (usually by GroupId) your project produces. This is particularly helpful in preventing accidental releases of a project.
Before a project can use the repository to release Maven artifacts, it must be configured in Nexus. This is generally a quick and easy process. To get set up, use this link to create a Jira ticket with the following information:
https://<project>.apache.org/).org.apache.If you have specific questions or concerns, please call them out in the ticket.
Once you file the Jira ticket, Infra will do the following:
maven-metadata.xml files and prevent rsync conflicts in Central, we must move all your artifacts to the new repository. We will mark the folder in the old repository as read-only to prevent accidental deployments.Further information about the POM and other Maven matters is here.
To use the ASF Nexus repository, follow these steps.
Inherit the Apache Parent POM like this:
<parent>
<groupId>org.apache</groupId>
<artifactId>apache</artifactId>
<version>23</version>
</parent>
This parent POM sets up the defaults so your <distributionManagement> section uses the correct release and snapshot repositories. Be sure to remove those from your POM so they inherit correctly. Keep the entry for deploying your site (if you use Maven to deploy your site). If you do, we suggest you use apache.website as the id to better match the settings below and to save the sanity of committers working on multiple projects.
The POM also provides a default configuration to make sure that a correct source archive is created for your project. This is separate and in addition to the typical -sources.jar that is created.
You must sign all artifacts with a key that is publicly verifiable. Follow the instructions here to get your keys created and environment set up.
Note: We recommend that you use Maven's password encryption capabilities for your passwords. Do not store your signing key in settings.xml.
The gpg plugin can prompt for the key (input is masked) or you can configure it to use an agent.
<settings>
...
<servers>
<!-- To publish a snapshot of your project -->
<server>
<id>apache.snapshots.https</id>
<username> <!-- YOUR APACHE LDAP USERNAME --> </username>
<password> <!-- YOUR APACHE LDAP PASSWORD (encrypted) --> </password>
</server>
<!-- To stage a release of your project -->
<server>
<id>apache.releases.https</id>
<username> <!-- YOUR APACHE LDAP USERNAME --> </username>
<password> <!-- YOUR APACHE LDAP PASSWORD (encrypted) --> </password>
</server>
...
</servers>
</settings>
Try installing locally artifacts with activation of apache-release profile:
mvn clean install -Papache-release
This will build artifacts and sources and sign them.
mvn release:prepare -DdryRun=true You may also wish to pass -DautoVersionSubmodules=true as this will save you time if your project is multi-moduled.pom.xml with the one called pom.xml.tag to see if the license or any other info has been removed. This has been known to happen if the starting <project> tag is not on a single line. The only things that should be different between these files are the <version> and <scm> elements. Backport any other changes you find to the original pom.xml file and commit it before proceeding with the release.mvn deploy
...
[INFO] [deploy:deploy]
[INFO] Retrieving previous build number from apache.snapshots.https
...
Notes
mvn release:clean
mvn release:prepare
Notes
.sha256 or .sha512 files; Nexus doesn't handle them.md5s in dist.apache.org/repos/dist/release/ must be removed manually.release:prepare may fail with Unable to tag SCM and svn: No such revision X. Wait 10 seconds and run mvn release:prepare again.mvn release:perform
Maven automatically inserts the release into a temporary staging repository for you. See the Nexus staging documentation for full details.
Now you must close the staging repository to indicate to Nexus that the build is done and to make the artifacts available. Follow the steps in Closing the Staged Repository, later in this document. This will allow your community to vote on the staged artifacts.
[INFO] Unable to tag SCM
Provider message:
The svn tag command failed.
Command output:
svn: Commit failed (details follow):
svn: File
'/repos/asf/maven/plugins/tags/maven-eclipse-plugin-2.7/.../EclipsePlugin.java'
already exists
Then use a Subversion client 1.6 or newer and run svn update.
[ERROR] BUILD FAILURE
[INFO]
[INFO] Unable to tag SCM
Provider message:
The svn tag command failed.
Command output:
svn: Path
'https://svn.apache.org/repos/asf/maven/plugins/tags/maven-eclipse-plugin-2.7'
already exists
Delete the tag using
svn del -m "re-releasing build" {svn path}
This likely occured because you're trying to restage the release and you didn't roll back the changes that created the previous tag, or you're trying to release a version that already exists. If that is the case, you need to adjust the versions in your POM and start over.
Apache Ant is a popular command-line build tool. Ivy is a dependency manager designed to work with Ant.
Usually your normal build process will create the artifacts you want to publish (typically jars), but you may need to PGP-sign them the same way you sign your normal distribution artifacts. The jars are expected to follow the naming scheme artifactId-version.jar.
You will need a minimal POM for your jar. If you are already using Ivy, you can use the makepom task to create one from your ivy.xml file. Otherwise see the Apache Maven project's documentation for "minimal" and the Apache Compress Antlib's POM for an example.
If you are publishing multiple jars you may consider adding a parent POM to encapsulate the common information; see the Maven documentation for details. An example might be Ant's parent POM, used for the several jars that make up an Ant release.
Users who use your project's jars from the Maven repository rather than using your "normal" distributions will likely want additional artifacts containing the source files or javadocs matching your jars in files named artifactId-version-sources.jar and artifactId-version-javadoc.jar respectively. Don't forget to sign those jars as well if you provide them.
If you are not already using Ivy in your project you'll need to create a minimal ivy.xml file for it. The syntax is described in Ivy's documentation. Since you will only use the file to publish your artifacts, all you need to provide are the organization, module and revision definitions and an entry for each artifact you want to publish; see Ant's ivy.xml file for a minimal version.
organization and module combined must match your Maven groupId.
You need artifact elements for your jar as well as the POM and any PGP signature file. You don't need artifacts for your checksum files (if you create any) since Nexus creates MD5 and SHA1 checksums for you.
If you are publishing source or javadoc jars as well, you'll need to provide something similar to Maven's classifier. You do so by adding an extra attribute to each artifact element that lives outside of Ivy's XML namespace and referencing this element in your ivysettings.xml file (see below). An example which uses this approach is the Compress Antlib's ivy.xml. It contains additional information and -sources as well as -javadoc artifacts.
Alternatively you can specify the -sources and -javadoc artifacts inside your publish task rather than your ivy.xml file. If you use Ivy 2.2.0 or later, you can also configure it to PGP-sign your artifacts so you no longer need to specify your signatures as artifacts. Ivy's own ivy-settings.xml configures Ivy to sign artifacts and the publish task inside the upload-nexus target declares the POM as well as -sources and -javadoc jars as additional artifacts.
If you are already using Ivy you may need to adapt your resolvers configuration by adding an url resolver for Nexus and referencing that in a module matching your ivy.xml.
You usually need to adapt the ivysettings.xml file used by Ant by using the same values for organization and name on the module element that you used in your ivy.xml file (where name on the module element in ivysettings.xml corresponds to module in ivy.xml).
Ant's ivysettings.xml uses Ant properties for the authentication information and Nexus' URL which will be expanded by the ivy:configure task. It also shows how to use the classifier extra attribute.
Uploading involves three Ivy tasks.
ivy:configure uses your ivysettings.xml file to configure Ivy (what else?).ivy:resolve reads your ivy.xml and doesn't do much beyond that if you are only using Ivy to upload your artifacts.ivy:publish publishes the artifacts to Nexus.Here is a link to an example build file combining those steps that expects you to provide the authentication information via the command line (i.e. ant -Dupload.user=YOUR-ASF_ID -Dupload.password=YOUR-PASSWORD).
How to manage your staged release, no matter which build tool you used.
Your artifacts should now exist in a new staging repository. See Locate and Examine for instructions on how to "close" this repository to trigger the quality checks and prepare it for a vote.
Now you go call your vote. Based on the results you will either promote (yay!) or drop and restage the release. If you are an incubating project, don't forget the IPMC vote before promoting. The actual Vote process is project=specific, but if you're looking for some examples, the Maven project has thorough documentation on their voting process.
If you bungled the release or your vote failed, follow these instructions to drop your repo. Don't forget to roll back any SCM changes.
Congratulations, your vote was successful. The last step is to promote the artifacts to the release repository where they will get picked up by Central.
Copyright 2021, The Apache Software Foundation, Licensed under the Apache License, Version 2.0.
Apache® and the Apache feather logo are trademarks of The Apache Software Foundation...