How to Release

tl;dr#

Once you've done your first release, you'd most probably be more comfortable with the quick guide to get the release out (nevertheless, all steps are explained below):

  • Prepare the release 
  mvn clean install apache-rat:rat -Papache-release               # generates artifacts, checks for AL headers
  mvn release:prepare -DdryRun=true -DautoVersionSubmodules=true  # review pom.xml, confirm only appropiate sections have been changed
  mvn deploy -Papache-release                                     # deploy a snapshot
  mvn release:clean                                               # prepare the release 1/3
  mvn release:prepare -DautoVersionSubmodules=true                # prepare the release 2/3
  mvn release:perform                                             # prepare the release 3/3
  • Close the staging repo
  • svn copy binaries and source to https://dist.apache.org/repos/dist/dev/jspwiki/X.Y.Z/
  • Run the vote and, if successful, continue with the items on the list
  • Publish Nexus repository
  • Publish binaries and source to the mirrorsContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png
  • Publish latest javadocs
  • Wait for 24 hours, then announce the release
  • Add the next release version to JIRA

First time release managers#

  1. Generate PGP code signing keysContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png
  2. Add the PGP code signing keys to the KEYS fileContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png as documented on the Infrastructure siteContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png
  3. Put in a Infrastructure JIRAContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png asking to get added to the jspwiki unix group on people.apache.org
  4. Copy the modified KEYS file to the release folder /www/www.apache.org/dist/jspwiki on people.apache.org and ensure it has 0664 permissions.
  5. Add the following servers to your Maven settings.xml file: 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
  <servers>
    <server>
      <id>apache.releases.https</id>
      <username>APACHE-ID</username>
      <password>APACHE-PASSWORD</password>
    </server>
    <server>
      <id>apache.snapshots.https</id>
      <username>APACHE-ID</username>
      <password>APACHE-PASSWORD</password>
    </server>
    <server>
      <id>svn.apache.org</id>
      <username>APACHE-ID</username>
      <password>APACHE-PASSWORD</password>
    </server>
    <server>
      <id>github.com</id>
      <username>GITHUB-ID</username>
      <password>GITHUB-2FA-TOKEN</password>
    </server>
  </servers>

Note that your password doesn't need to be inside the settings.xml file, due to Maven encryption capabilitiesContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png. It is also convenient to setup the ssh keysContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png on people.apache.org, otherwise you'll have to enter your login password a number of times.

Create a release candidate#

Generate release candidate artifacts#

  • Generate artifacts 
  mvn clean install apache-rat:rat -Papache-release

This will check that all files have AL headers and also build artifacts, sources and sign

  • Check POMs for release 
  mvn release:prepare -DdryRun=true -DautoVersionSubmodules=true

Perform quick diffs between pom.xml files and their sibling pom.xml.tag files to see if the license or any other info has been removed (should never happen, but just to stay on the safe side).

Prepare the release#

  • Publish a snapshot 
  mvn deploy -Papache-release
  • Prepare the release 
  mvn release:clean
  mvn release:prepare -DautoVersionSubmodules=true
  • Stage the release for a vote 
  mvn release:perform
  • Close the staging repository
  1. Login to https://repository.apache.orgContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png and select Staging Repositories on the left under Build Promotion.
  2. Select org.apache.jspwiki from the list of repositories, then click CloseContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png using "Apache JSPWiki X.Y.Z" as the description to allow others to see the repository.
  • Svn copy binaries and source to https://dist.apache.org/repos/dist/dev/jspwiki/X.Y.Z/, suggested structure 
  binaries
    portable
    webapp
  source
  wikipages

Run a vote#

  • Send the following to dev@jspwiki.apache.orgContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png: 
    Subject: [VOTE] Release JSPWiki version X.Y.Z
        
    This is a release vote for Apache JSPWiki, version X.Y.Z. The vote will be open for at least 72 hours from now.
        
    It fixes the following issues:
    https://issues.apache.org/jira/secure/ReleaseNote.jspa?projectId=12310732&version=12334934
        
    Note that we are voting upon the source (tag), binaries are provided for convenience.

    Everybody is encouraged to vote.
        
    Source and binary files:
    https://dist.apache.org/repos/dist/dev/jspwiki/[VERSION]-RC$RC

    Nexus staging repo: https://repository.apache.org/content/repositories/orgapachejspwiki-...
        
    The tag to be voted upon:
    http://github.com/apache/jspwiki/tree/[VERSION]-RC[N]
        
    JSPWiki's KEYS file containing PGP keys we use to sign the release:
    http://www.apache.org/dist/jspwiki/KEYS

    *** Please download, test and vote:

    [ ] +1 Approve the release
    [ ]  0 Don't mind
    [ ] -1 Disapprove the release (please provide specific comments)

Note that the PMC needs to vote upon the release before any release can be made official.

Roll Out#

  • Publish Nexus repository
    1. Login to https://repository.apache.orgContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png and select Staging Repositories on the left under Build Promotion.
    2. Select the repository that was closed earlier, and click Release, using the description "Apache JSPWiki X.Y.Z"
  • Publish src and bin distributions to the mirrorsContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png
    1. svn checkout https://dist.apache.org/repos/dist/release/jspwikiContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png
    2. svn copy the release artifacts from https://dist.apache.org/repos/dist/dev/jspwiki/$VERSION-CANDIDATE to https://dist.apache.org/repos/dist/release/jspwiki/$VERSION
    3. svn delete older releases
  • Wait 24 hours for mirrors to sync
  • Post link to the full release notes along with links to the major JIRA changes on the front page of the site

Announce the release#

  • Send the following from an apache.org address to announce@apache.orgContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png, user@jspwiki.apache.orgContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png, dev@jspwiki.apache.orgContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png: 
    Subject: [ANNOUNCE] Apache JSPWiki X.Y.Z released
        
    The Apache JSPWiki team is pleased to announce the release of JSPWiki X.Y.Z.
        
    This is the <REPLACE> release on the X.Y series of Apache JSPWiki, a feature-rich and 
    extensible WikiWiki engine built around the standard JEE components.
        
    The release is available here:
    http://www.apache.org/dyn/closer.cgi/jspwiki/

    JSPWiki Maven artifacts are available under org.apache.jspwiki groupId, 
    version X.Y.Z
        
    The full change log is available here:
    https://issues.apache.org/jira/browse/JSPWIKI/fixforversion/<REPLACE>

    A curated change log is also available here:
    https://jspwiki-wiki.apache.org/Wiki.jsp?page=NewIn<REPLACE>
        
    We welcome your help and feedback. For more information on how to
    report problems, and to get involved visit the project website at
    http://jspwiki.apache.org/
        
    The Apache JSPWiki Team

Add the next release version to JIRA#

  • Add the next version number to JIRAContent unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png
  • Mark the released version as "released" with a release date

Troubleshooting#

  • Cygwin mixes Windows path with cygdrive, so mvn release:prepare fails on svn commit
    • Current workaround: perform release via cmd.exe
  • Avoid gpg signing prompt when using Maven release plugin
  • mvn release:prepare doesn't find svn credentials
    • On your settings.xml file you should have one <server /> entry for each of the following ones:
      • apache.snapshots.https: to be able to deploy snapshots
      • apache.releases.https: to be able to deploy releases
      • svn.apache.org: to be able to create tags
      • Alternatively, for the last one, you could pass -Dusername=[username] -Dpassword=[password] to the mvn command (source: http://stackoverflow.com/q/1255593Content unavailable! (broken link)https://jspwiki-vm1.apache.org/images/out.png)
  • Release fails after a tag has been generated and the pom versions have been incremented
    • No need of mvn release:rollback, instead check out the tag and release:perform -DconnectionUrl=scm:svn:https://svn.apache.org/COMPLETE-URL-TO-TAG

Other links of interest#

This particular version was published on 08-Feb-2018 22:33 by Juan Pablo.  Top