Apache Maven 1.x has reached its end of life, and is no longer supported. For more information, see the announcement. Users are encouraged to migrate to the current version of Apache Maven.

Following Best Practices

At Maven, we eat our own dog food! Please make sure you are familiar with the Best Practices document and follow those techniques.

Prerequesites

You have do these steps only for your first release.

Setup your maven settings

You must define the following properties in ~/build.properties. (Note: you may want to put these in maven-plugins/plugin-parent/build.properties and in core/build.properties instead if you need to define them differently for other projects).

  • maven.username - your apache username to deploy the web site.
  • maven.password - your apache password (if needed, depending of the protocol used in the site plugin).
  • maven.repo.apache.releases.username - your apache username
  • maven.repo.apache.releases.privatekey - the filename of your SSH private key
  • maven.repo.apache.releases.passphrase - the passphrase for your private key (not your Apache password)
  • maven.announcement.mail.from - Your name and email address, as subscribed to the users and developers mailing lists, e.g. Brett Porter <brett@apache.org>. It's needed to use your apache account if you want to send the announcement to announce@maven.apache.org.
  • maven.announcement.mail.server - The SMTP server to use for sending the announcement mail.
  • maven.nsis.exe - The path to the nsis binary to generate the setup for the maven distribution.

Generate a code signing key (OpenPGP Compatible Signature)

You'll find some useful information here : http://www.apache.org/dev/release-signing.html.

To sum up :

  1. Install GNU Privacy Guard for your your platform and add it in your PATH.

  2. Create your key :

    $ gpg --gen-key

    Keep the default settings.

    Enter your personal information :

    Real name: FirstName LastName
    Email address: YourEMail@apache.org
    Comment: CODE SIGNING KEY
    

    It creates a key with the following user ID like this :

    FirstName LastName (CODE SIGNING KEY) <YourEMail @ apache.org>
  3. Export it :

    $ (gpg --list-sigs "FirstName LastName" && gpg --armor --export "FirstName LastName") > ~/MY_KEYS
  4. And append the result to the KEYS file stored in https://svn.apache.org/repos/asf/maven/project.

  5. To automatically sign your artifacts, you need to have the maven artifact 1.9 (at least) and if you have several keys you have to set the property "maven.artifact.gpg.keyname" to select the one you want to use.

Releasing a Plugin or a Component

For more general notes on making a release, please see the Releasing documentation in the User's Guide.

  • Run maven scm:prepare-release and enter the appropriate tag (maven-[projectname]-[major].[minor].[bugfix]) and version.

  • Produce a clean build using maven -Dmaven.repo.list=apache.releases -Dmaven.site.deploy.live=true scm:perform-release. When prompted for the tag, enter the one used in the previous step. When prompted for the goal, enter plugin:repository-deploy,source:deploy,javadoc:deploy,site:deploy for plugins, or jar:deploy,source:deploy,javadoc:deploy,site:deploy for an individual JAR.

  • Check for the new version at http://people.apache.org/repo/m1-ibiblio-rsync-repository/maven/plugins/ or http://people.apache.org/repo/m1-ibiblio-rsync-repository/maven/jars/.

  • Go to the JIRA administration page for the Maven subproject you have just released (Note that you need to be a JIRA administrator for this project) and release the version. Also make sure to add a new version for the following development version. This is required so that developers can assign a "fix for" version to issues.

  • Run maven announcement. Edit this, then send it in a release email to the Maven user and developer lists. If you are happy with the default announcement, run maven announcement:mail.

Releasing a Maven Distribution

For more general notes on making a release, please see the Releasing documentation in the User's Guide.

Compared to a plugin or a component, there are a couple of additional steps when releasing a Maven distribution.

  • Run maven maven:build-plugin-profile and check the versions are what you expect to distribute

  • Update the website files for the download links and release notes

  • Run maven scm:prepare-release and enter the appropriate tag (maven-[major].[minor].[bugfix]) and version.

  • Produce a clean build using maven -Dmaven.repo.list=apache.releases scm:perform-release. When prompted for the tag, enter the one used in the previous step. When prompted for the goal, enter maven:release. Do this on Windows so that the .exe file is generated (you have to install NSIS, and to setup the NSIS plugin to find the exe). You can find the binaries in target/checkout/target/distribution

  • Sign and create checksums for the binaries :

    gpg --local-user "[FirstName] [LastName] (CODE SIGNING KEY) <[YourEMail] @ apache.org>" --armor --detach-sign maven-[version].exe
    gpg --print-md MD5 maven-[version].exe > maven-[version].exe.md5
    gpg --local-user "[FirstName] [LastName] (CODE SIGNING KEY) <[YourEMail] @ apache.org>" --armor --detach-sign maven-[version].tar.bz2
    gpg --print-md MD5 maven-[version].tar.bz2 > maven-[version].tar.bz2.md5
    gpg --local-user "[FirstName] [LastName] (CODE SIGNING KEY) <[YourEMail] @ apache.org>" --armor --detach-sign maven-[version].tar.gz
    gpg --print-md MD5 maven-[version].tar.gz > maven-[version].tar.gz.md5
    gpg --local-user "[FirstName] [LastName] (CODE SIGNING KEY) <[YourEMail] @ apache.org>" --armor --detach-sign maven-[version].zip
    gpg --print-md MD5 maven-[version].zip > maven-[version].zip.md5
    gpg --local-user "[FirstName] [LastName] (CODE SIGNING KEY) <[YourEMail] @ apache.org>" --armor --detach-sign maven-[version] -src.tar.gz
    gpg --print-md MD5 maven-[version]-src.tar.gz > maven-[version]-src.tar.gz.md5
    gpg --local-user "[FirstName] [LastName] (CODE SIGNING KEY) <[YourEMail] @ apache.org>" --armor --detach-sign maven-[version]-src.zip
    gpg --print-md MD5 maven-[version]-src.zip > maven-[version]-src.zip.md5
    
  • Manually upload the distributions on people.apache.org to the distributions locations (under /www/www.apache.org/dist/maven/binaries/ and /www/www.apache.org/dist/maven/source/).

  • Check for the new version at http://www.apache.org/dist/maven/binaries/ and http://www.apache.org/dist/maven/source/.

  • Go to the JIRA administration page for the Maven project (Note that you need to be a JIRA administrator for this project) and release the version. Also make sure to add a new version for the following development version. This is required so that developers can assign a "fix for" version to issues.

  • Run scm:perform-release -Dmaven.site.deploy.live=true with the site:deploy goal, and mail out release notes

Some related FAQs

  • Q : When would I do a release?

    A : Plugins have their own release cycle now. So you can make a release whenever there is a change that you want to get into the hands of the users. This should be for major bugfixes and thoroughly tested and complete new features. You may also decide to make periodical releases every couple of months if there have only been minor bugfixes.

  • Q : What is the convention for versioning?

    A : Rewrites and changes that break compatibility are a major version number change. Announcements for these plugins should details what old functionality would be broken and link to a migration document on the plugin project web site. Minor version increments are for feature enhancements, major bugfixes and groups of bugfixes. These versions can go beyond 10: eg 1.13. A third version increment is optional and signifies minor updates. These may also be deployed as snapshots or users may just be asked to build out of CVS to acquire these fixes.

  • Q : Who decides when a plugin can be released?

    A : The lead developer of a plugin has the responsibility for making sure releases happen, but must first hold a vote on the Maven Developer list before cutting the release. The vote should detail the changes made and confirm that the testing has been performed and that there is no pending work that should hold up the release.