Page tree
Skip to end of metadata
Go to start of metadata

Java Product Release Process

This document describes the process that the Shibboleth team uses to package up and release a new version of our Java software products.

Release Environment

All our Java products use Maven to perform the actual build of release artifacts. Those artifacts are then uploaded to our Nexus installation at

Initial Configuration

Prior to performing any releases a few one-time configurations need to be done.

  1. Ensure that you have the proper data in your ~/.m2/settings.xml file.
  2. Generate an SSH key
  3. Generate a PGP key and get it signed by the other developers. To avoid use of SHA-1 use the following in your gpg.conf file:

    personal-digest-preferences SHA512
    cert-digest-algo SHA512
    default-preference-list SHA512 SHA384 SHA256 SHA224 AES256 AES192 AES CAST5 ZLIB BZIP2 ZIP Uncompressed
  4. Send the public SSH and PGP keys to committers email list with a request to be allowed to perform releases

A systems admin will then:

  1. Log in to Nexus and go the Security -> Users -> Add -> External User Role Mappingscreen
    1. Enter the user's LDAP uid as their user name (same userid they use for SVN)
    2. In the Role Management section, add the role Nexus Deployment and save the user account
  2. Add an account for you on the server, set your SSH key as an authorized key, and allow you to su to the Shibboleth website user
  3. Add your GPG key to the KEYS file on the download site

Parent POM Adjustment

In most cases, a major or minor release will involve tagging a new version of the parent POM and updating all projects to depend on it. In rare cases, this may be needed for patch releases but it's more likely that if a dependency has to be updated, the various project POMs will be overridden to reference it. When in doubt, ask.

  1. Ensure that your working copy is in sync with the project repository (i.e., pull down any updates and commit any local changes).
  2. If not done, tag the parent POM to freeze the parent so it can be referenced by the subsequent steps. The tag version is a single, monotonically-increasing number.
  3. Run the command java-parent-project-v3/bin/ (for a monolithic project} or java-parent-project-v3/bin/ (for a multi-module project). The arguments are the parent POM tag number, and the path to the project.

    # Lock java-support against tag version 5 of V3 parent
    java-parent-project-v3/bin/ 5 java-support
  4. After verifying the project's build using the newly referenced parent POM, commit the project changes.

Release Process

  1. Ensure that your working copy is in sync with the project repository (i.e., pull down any updates and commit any local changes).
  2. Set the project version number in the POM to release version number. Also update versions of any dependencies on our own projects and make sure the javadoc URLs are correct.
  3. Once satisfied, tag the release using a name equal to the version number of the release (e.g., 1.0.1, 3.4.5) and ensure the POM at the tip of the branch being released NEVER contains a non-SNAPSHOT version number.

    Git-based Projects
    # Assume working copy is on branch 'master', with ONLY tag-specific changes pending
    # (e.g. non-SNAPSHOT version)
    # Don't forget to 'git add' the pom.xml and any other changed files at this point
    # Commit the changes to be tagged to the HEAD of the branch
    git commit -m "Update files to be tagged for release"
    # Create a signed, annotated tag from HEAD
    git tag -s -m "Tag 3.2.0 release" 3.2.0
    # Edit pom.xml to update the version to X.Y.Z+1-SNAPSHOT (in the example, 3.2.1-SNAPSHOT).
    # Commit the pom.xml change.
    git add pom.xml
    git commit -m "Update POM to next SNAPSHOT version"
    # Push the new commits.
    git push
  4. In a separate sandbox (same or different machine), checkout or export the tag to build the final release.
  5. Execute mvn -Dmaven.repo.local=/tmp/repo-release -Pcentral-disabled,release,sign clean deploy
    1. If you want to preserve the transient release repo for archiving, etc, use a permanent location for -Dmaven.repo.local, with the version in the name.
  6. At this stage, DO NOT make any changes to fix errors without increasing the version again. This commits you to a release and you cannot go back.
  7. Mark the version as released in Jira.
  8. For top-level projects (IdP): Place the product distribution in the download section of the website by:
    1. Log in to the Shibboleth webserver
    2. Copy the distribution archive, its md5 and sha1 hashes, and PGP signature to a version-named directory in the download site. You can verify the signature(s) at this point.

      The easiest way to do this is to wget the files from the Nexus release repository as that way the copy occurs over the loopback interface.

    3. Adjust the latest sym-link to point to the new version.
  9. For top-level projects:
    1. Update the relevant product's ReleaseNotes topic with the new release, the date, a link to a JIRA issue filter that produces the appropriate list of issues, and any important information about issues addressed, advisories, special requirements during upgrades, etc.
    2. Send an announcement to Be sure to sign the email with your PGP key.
    3. Add a NEWS blog item to the wiki space.
    4. Update the "latest stable version" mentioned on the front page of the wiki space for the relevant product.
  10. For releases that include one or more Security Advisories:
    1. Finalize each advisory and fill in the date, double check any footnotes and URLs for correctness, and finalize the filename of the advisory based on the date and correct the self-referential link to the advisory in the text. See previous advisories for examples.
    2. Sign the advisory in text form with a PGP key that's in the project's PGP_KEYS file.
    3. Place the signed advisory on the server in /home/shibwww/html/community/advisories in a file named secadv_YYYYMMDD.txt and ensure appropriate ownership and 644 file mode.
    4. Send the PGP-signed advisory to (see previous examples in the archive).
    5. Update the relevant SecurityAdvisories page in the IDP30 wiki space for an IdP advisory. The page includes a tabular display of all the advisories and links, and a table listing releases and how the advisories affect them.
    6. Add a NEWS blog item to the wiki space.

Windows Installer

This is described separately.

  • No labels