content/apt/developers/release/maven-project-release-procedure.apt

 -----
 Releasing A Maven Project
 -----
 Jason van Zyl
 Karl Heinz Marbaise
 -----
 2016-06-18
 -----

~~ 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.

Performing a Maven Project Release

  This document covers the common release procedures used by the Maven team to perform releases.
  
* {Prerequisites}

 Be sure that:

  * you have a Subversion 1.5+ client installed and on your shell's path. See {{{https://subversion.apache.org/}https://subversion.apache.org/}}.

  * you have JDK 5 installed and on your shell's path.

  * if you receive an OutOfMemoryError during the build, make sure to have set the environment variable <<<MAVEN_OPTS=-Xmx512m>>>

  * you must use Maven 2.2.1+, as Maven 2.1.0 and 2.2.0 produce incorrect GPG signatures and checksums respectively.
  
  * follow Apache environment configuration steps outlined at: {{{https://www.apache.org/dev/publishing-maven-artifacts.html#dev-env}Publishing Maven Artifacts}}.

  []

* Before you begin
  
  If you started here, you may first want to review one of the following documents that cover the specifics of various types of releases we have in the Maven Project:
  
  * {{{./maven-core-release.html} Releasing Maven Core}}

  * {{{./parent-pom-release.html} Releasing a parent POM}}

  []

* Consider updating the parent versions

  If the item you are planning to release is not using the most recent version of its parent
  (see {{{../../pom/}parent POMs}} index), consider taking this opportunity to update to it.

* Make sure that site compilation and publication works

  Particularly if you update the parent (but sometimes under other circumstances),
  the site compilation process may fail, or reveal a conspicuous error, 
  or deploy to the wrong location. It is stressful and time-consuming
  to discover this *after* you stage a release and then try to follow
  the procedure to deploy the site for review. So you may find it more
  pleasant to check out the state of the site before you start.

* Stage the Release

 [[1]] Follow the release preparation, staging and closing the repository steps outlined in {{{https://www.apache.org/dev/publishing-maven-artifacts.html#staging-maven}Staging a Maven release}}. 

 [[2]] Stage the latest documentation as explained in {{{../website/deploy-component-reference-documentation.html}deploying Maven components reference documentation}}.
 
* Call the vote
 
 Propose a vote on the dev list with the closed issues, the issues left,
 the staging repository and the staging site. For instance:

+-----+
To: "Maven Developers List" <dev@maven.apache.org>
Subject: [VOTE] Release Apache Maven XXX Plugin version Y.Z

Hi,

We solved N issues:
https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=XXXXXX&version=YYYYYYY&styleName=Text

There are still a couple of issues left in JIRA:
https://issues.apache.org/jira/issues/?jql=project%20%3D%20XXXXXXXXXX%20AND%20status%20%3D%20Open%20ORDER%20BY%20key%20DESC%2C%20priority%20DESC

Staging repo:
https://repository.apache.org/content/repositories/maven-[YOUR REPOSITORY ID]/
https://repository.apache.org/content/repositories/maven-[YOUR REPOSITORY ID]/[PATH-TO]-source-release.zip

Source release checksum(s):
[NAME-OF]-source-release.zip sha1: [SHA1SUM]

Staging site:
https://maven.apache.org/plugins-archives/maven-XXX-plugin-LATEST/

Guide to testing staged releases:
https://maven.apache.org/guides/development/guide-testing-releases.html

Vote open for 72 hours.

[ ] +1
[ ] +0
[ ] -1

+-----+

 To get the JIRA release notes link, browse to the plugin's JIRA page, select the <Road Map> link,
 and use the link to <Release Notes> that is next to the version being released.

 To get the list of issues left in JIRA, browse to the plugin's JIRA page, and from the <Preset Filters>
 on the right, use the link for <Outstanding> issues.

* Check the vote results

 Copied from {{{https://www.apache.org/foundation/voting.html#ReleaseVotes}Votes on Package Releases}}.

+-----+
Votes on whether a package is ready to be released use majority approval
-- i.e. at least three PMC members must vote affirmatively for release,
and there must be more positive than negative votes. Releases may not be vetoed.
Generally the community will cancel the release vote if anyone identifies serious problems,
but in most cases the ultimate decision, lies with the individual serving as release manager.
The specifics of the process may vary from project to project,
but the 'minimum quorum of three +1 votes' rule is universal.
+-----+

  The list of PMC members is available at {{https://people.apache.org/committers-by-project.html#maven-pmc}}.

  Once a vote is successful, post the result to the dev list and cc the PMC. For instance:

+-----+
To: "Maven Developers List" <dev@maven.apache.org>
CC: "Maven Project Management Committee List" <private@maven.apache.org>
Subject: [RESULT] [VOTE] Release Apache Maven XXX Plugin version Y.Z

Hi,

The vote has passed with the following result:

+1 : <<list of names>>

PMC quorum: ...

I will promote the artifacts to the central repo.
+-----+

  If the vote is unsuccessful, the process will need to be restarted. Be sure to drop your staging repository as
  described in {{{https://www.apache.org/dev/publishing-maven-artifacts.html#drop}Dropping a Repo}}.

* Copy the source release to the Apache Distribution Area

  The official Apache release is the 'source-release' bundle. All releases must be copied to {{{https://www.apache.org/dist/maven/}the official 
  release area}}. The release area is maintained with svnsubpub. To deliver a release, you add it to 
  {{{https://dist.apache.org/repos/dist/release/maven}the subversion repository for the dist area}}: add the release, its signature, and corresponding
  MD5 files. Currently this requires to be in maven-pmc group (see {{{https://issues.apache.org/jira/browse/INFRA-5945}https://issues.apache.org/jira/browse/INFRA-5945}}).

  For example:

+--------+
wagon/wagon-2.2-source-release.zip
wagon/wagon-2.2-source-release.zip.asc
wagon/wagon-2.2-source-release.zip.md5
+--------+

  You should also run 'svn rm' as needed to clear out older releases.  As per {{{https://www.apache.org/dev/release.html#where-do-releases-go}the policy}},
  only the latest release on a branch should stay in the main dist areas. So long as the previous release is at least a day old, the automatic archiver
  will have copied it to the archive.

  To check that everything is ok in the dist area, dist-tool-plugin has been written and run once a day to produce
  {{{https://builds.apache.org/view/M-R/view/Maven/job/dist-tool-plugin/site/dist-tool-check-source-release.html}"Disttool> Source Release" report}}.

* Promote the release

 Once the release is deemed fit for public consumption it can be transfered to a production repository where it will
 be available to all users.

 [[1]] See {{{https://www.apache.org/dev/publishing-maven-artifacts.html#promote}Promoting a Repo}} for details on promotion.

 [[2]] Deploy the current website
 
   As above, deploy the web site if appropriate and update the project site for the
   new release. See 
  {{{../website/deploy-component-reference-documentation.html#Publishing_versioned_component_reference_documentation}Publishing versioned component reference documentation}}
  or {{{../website/component-reference-documentation-helper.html}Component Reference Documentation Helper}}.
  Note that not all projects follow these conventions exactly.

 [[3]] Update the version tracking in JIRA

 In the relevant project, go to Administration, then Versions. Mark
 the <<<Y.Z>>> version as 'released'. Create version <<<Y.Z+1>>>, if that hasn't already
 been done. You may also archive any deprecated releases (milestones or alphas) at this time.

 [[4]] Wait for everything to sync

   [[a]] Sync to {{{https://repo.maven.apache.org/maven2/org/apache/maven/}Maven Central}}

     The sync into central staging from repository.apache.org occurs every 4 hours. 
     There is a separate hourly schedule that runs which pushes from staging to the other central machines, and then updates the indexes.

   [[b]] Sync to Maven Website

     If the project you are releasing doesn't yet use svnpubsub for site deployment, the deployment of the Maven website will {{{https://www.apache.org/dev/release-publishing.html#sync-delay}take an hour or so to sync}}.

   []

 [[5]] Create an announcement.

   [[a]] Using Maven Changes Plugin

   If you are releasing a plugin or a shared component you can let Maven Changes Plugin <<generate>>, and eventually even
   <<send>>, the announcement for you. First make sure that you have configured the necessary
   properties in your {{{../committer-settings.html}committer settings}}.

+------+
cd target/checkout
mvn changes:announcement-mail -Papache-release
+------+

   If sending the mail should fail, the generated annoucement is available in <<<target/annoucement>>> (see <<<annoucement.vm>>>)
   and you can use it as a base for sending the mail manually.

   If your SMTP server requires authentication you need to add the command line
   options for it:
 
+------+
cd target/checkout
mvn changes:announcement-mail -Dchanges.username=<SMTP-USERNAME> -Dchanges.password=<SMTP-PASSWORD> -Papache-release
+------+

   [[b]] Manually
    
   <<Note:>> You must send this email from your apache email account, e.g. YOUR_APACHE_USERNAME@apache.org otherwise
   the email to announce@maven.apache.org will bounce.

+-----+
From: YOUR_APACHE_USERNAME@apache.org
To: announce@maven.apache.org, users@maven.apache.org
Cc: dev@maven.apache.org
Subject: [ANN] Apache Maven XXX Plugin Y.Z Released

The Apache Maven team is pleased to announce the release of the Apache Maven XXX Plugin, version Y.Z

This plugin (insert short description of the plugin's purpose).

https://maven.apache.org/plugins/maven-XXX-plugin/

You should specify the version in your project's plugin configuration:

<plugin>
  <groupId>org.apache.maven.plugins</groupId>
  <artifactId>maven-XXX-plugin</artifactId>
  <version>Y.Z</version>
</plugin>

You can download the appropriate sources etc. from the download page:

https://maven.apache.org/plugins/maven-XXX-plugin/download.cgi

Release Notes - Maven XXX Plugin - Version Y.Z

(Copy Here Release Notes in Text Format from JIRA)

Enjoy,

-The Apache Maven team

+-----+

   []

 [[5]] Add the release to the next board report, in the private subversion area.

 This is a PMC activity.  If you are not a PMC member then email the Developer's
 list with a request to update this file for your release.

 [[6]] If releasing the Apache Parent POM, notify release-discuss@apache.org

 Several projects follow this list, and should be made aware of changes to the common parent.
 This might also be a step to take if other shared resources are released, or if plugin releases are
 of particular interest to that group.

 [[7]] Celebrate :o)