Release Process

Owned by ScottS
Last updated: Oct 24, 2013 by Jérôme LELEUVersion comment
5 min read

This page documents the steps that a release engineer should take for cutting a CAS server release:

  1. Sanity test pending CAS release by testing protocol and major features (this should be automated) : on a Maven overlay, login, service ticket validate, logout...
  2. Ensure criteria for a release has been met (no outstanding JIRA issues, etc.)
  3. Ensure all outstanding changes are committed.
  4. Ensure all tests pass on CI (https://developer.jasig.org/bamboo/browse/CAS4-TIB) [tests are disabled during release process]
  5. Set up your environment :
    1. Ensure your settings.xml file has the Sonatype repository defined with the appropriate credentials
    2. Load your SSH key on your local computer
    3. Ensure this SSH key is also referenced in Github
  6. Checkout the CAS project :
    1. mkdir casrelease
    2. cd casrelease
    3. git clone git@github.com:Jasig/cas.git .
  7. Ensure version numbers in CAS server artifacts are correct for the release that will be cut.
    1. Ensure web.xml <display-name> declares the correct CAS server version (No longer required as of fix in 
      Error rendering macro 'jira' : Unable to locate Jira server for this macro. It may be due to Application Link configuration.
      ).
    2. Sanity test common configuration by having an other CAS deployer update and build their local Maven WAR overlay (or keep a sample around that can be used).

  8. Ensure licensing conformity before release by executing the following goals from the project root:

    Licensing Checks
    mvn -o notice:check
mvn -o license:check
mvn -o checkstyle:check

    If either of the above, the notice:generate and license:format goals may be used (the latter with care) to help remedy the situation.  See maven-notice-plugin for more information on NOTICE file generation.

  9. Prepare for release by running prepare goal of Maven Release Plugin, which prompts for version numbers:

    export MAVEN_OPTS="-Xmx2048m"
mvn release:prepare

    Alternatively, you may specify the release version number directly on the command line:

    export MAVEN_OPTS="-Xmx2048m"
mvn -DreleaseVersion=x.y.z -DdevelopmentVersion=a.b.c release:prepare

  10. Perform the release by executing the following command and answering ensuing questions. Ensure that you have the credentials to sign the releases; note that builds will fail if the tests fail so make sure all tests pass!)

    mvn release:perform
  11. Follow the process for deploying artifacts to Maven Central via Sonatype OSS repository.  See Deploying Maven Artifacts for background.
    1. Log into https://oss.sonatype.org.
    2. Find the staged repository for CAS artifacts created by the mvn release:perform goal.
    3. "Close" the repository.
    4. "Release" the repository.  Both c and d should be accompanied by email confirmation.
  12. Check out source from generated branch : from this step, the procedure should be followed only for release (not for RC and GA versions), except sending an email to cas-user and cas-dev mailing lists

  13. Build the assembly using the following command:

    mvn -DskipTests clean package assembly:assembly && mvn -N antrun:run
  14. Upload assembly to Jasig Download Servers.  See Publishing Project Downloads for instructions.
  15. Trigger release in JIRA
  16. Generate release note/message
  17. Add entry to download section of jasig.org/cas with release notes
  18. Update download block on jasig.org/cas site to point to most current download. Direct link: http://www.jasig.org/admin/build/block/configure/block/21.
  19. Update "current" version in site
  20. Send message to cas-announce, cas-user and cas-dev
  21. Post news announcement on Jasig site
  22. Optionally: announce on Twitter, Facebook, etc.

Note: the current release process assumes that documentation has been updated along the way, which is often an incorrect assumption.
Note: I think we need to define more criteria for release (i.e. enough +1 votes, 70% code coverage, etc.)

Common issues during the release process

If you're preparing and cutting the release, please be wary of the following possible issues:

SSH Authentication: private key's passphrase prompt hangs

SSH authentication with git on Windows is unable to cache the private key's password regardless of any authorized SSH agent running in the background. The maven-release-plugin currently is unable to actually present the password prompt. To mitigate the problem, you will need to modify the release.properties file, and switch the authentication scheme from SSH to HTTPS. 

Review this question here for the full context of the problem.

"[Directory] is outside the repository" error

When the maven-release plugin attempts to add/commit/push back files to the repository from the project directory, you might receive the error that the directory is outside the repository! This has to do with the fact that the plugin and git consider path names to the project directory to be case-sensitive while Windows does not. In other words, git might consider the project repository directory to be available at "c:\project", while the current directory is pointed to "C:\project". To mitigate the problem, simply "CD" into the directory path of the working directory given by git, based on the console output. 

"Dependencies cannot be found/resolved" error

Once you have prepped the release and start to execute "release:perform", the maven-release plugin will attempt to checkout the prepped release from source first and run through the build to upload artifacts. You may at this stage encounter the error that artifact dependencies (that are based on the new tagged release) cannot be found. For example, if you have prepped the release V4-RC1 and are attempting to cut it,  you may receive the error that certain modules for V4-RC1 cannot be resolved during the build. To mitigate the issue, navigate to the checkout directory and run "mvn install" once to locally capture the newly tagged artifacts.

Update the 24th october 2013 by Jérôme : when releasing the 4.0.0-RC2 : in fact, using "mvn install" didn't solve the problem for me as the version of the artifacts were already upgraded to 4.0.0-RC3-SNAPSHOT. So I checkout the CAS project again, switched to the tag (git checkout v4.0.0-RC2) and perform "mvn -o install -Pnocheck".

The build is way too slow!

Update the 24th october 2013 by Jérôme : since 4.0.0-RC2, the nocheck Maven profile is now used by the maven-release-plugin to disable all this checks : https://github.com/Jasig/cas/pull/339. The release:perform has taken 45 minutes on my regular development computer.

The current CAS build runs a number of checks and processes as it progresses forward in the release process. In order to cut down build time, you can disable some of these checks in the Maven's settings.xml file. Here are some of the steps you can through configuration ignore by setting them to true:

 

  1. Skip running tests (Tests still would have to be compiled): <skipTests>true<skipTests>
  2. Checkstyle checks: <checkstyle.skip>true</checkstyle.skip>
  3. License checks: <license.skip>true</license.skip>
  4. Notice file checks (The availability of this setting depends on the version of the plugin you have): <notice.skip>true</notice.skip>
  5. Dependency version checks: <versions.skip>true</versions.skip>

Create an active build profile that encapsulates the above settings. Disabling these checks will help speed up the build because, the maven-release plugin attempts to run all said checks for all modules prior to processing the active module during the build. In other words, if the build is attempting to process module C, it will run the checks for modules A and B...and then it moves on to C. Similarly, if the build is at module D, it will yet again run all checks for modules, A, B and C before it starts with D. Disabling the above checks will cut down the release time quite significantly.

Caution!

You must ensure that all above checks do actually pass, separately and independently, if you do decide to disable them in the build process.

Java heap space "Out of memory" errors

Depending on settings, the build might run out of Java heap space. You can tweak settings through JAVA_OPTS and MAVEN_OPTS and allow more via the "-Xmx" parameter. Usually, "2g" should suffice on a 64-bit Java VM.

Update the 24th october 2013 by Jérôme : for 4.0.0-RC2, using "export MAVEN_OPTS="-Xmx2048m" makes the Maven operations successful.