Cutting a uPortal Release

Owned by Eric Dalquist
Last updated: Jan 31, 2018 by Andrew Wills
6 min read

uPortal 5.x Release Process

  1. Use Gradle to tag, push, and upload the release to Sonatype (documentation)
  2. Close & release the Nexus Staging Repository within Sonatype
  3. Release the version in the Manage Versions JIRA UI
  4. Create the release notes
    1. Create & update the appropriate release page as a child of the Release Notes page
    2. Use Git to inspect the incremental commits since the last release (e.g. $ git log v5.0.5 ^v5.0.4 --no-merges)
    3. Review the issue tracker and confirm that referenced issues have been Resolved
    4. Enter the release notes on the GitHub releases page
  5. Open a Pull Request on uPortal-start to update uPortalVersion to the new release
  6. Publish a new apereo/uPortal-demo Docker image and update the :latest tag as well 

 

uPortal 4.x Release Process (Archive)

Documenting the 5.x Process

This content is transforming & migrating to the 5.x process (above). It's a work in progress.

Before starting the release process

  • In Apache-style projects, releases are decided by a vote of committers.  Call for a vote if needed, and be executing these instructions to make so a decision of the project committers to release.  http://www.apache.org/foundation/voting.html
  • When starting these release steps in response to a successful vote-to-release, request a FREEZE of the branch being released on uportal-dev@.
  • (thumbs up) Suggestion:  Review the master branch for commits that can safely and appropriately (per the community's current guidelines for what changes may occur where) be applied to the branch you're releasing.  It is easy to forget to apply changes to multiple branches, especially changes that come into the codebase from Pull Requests on GtiHub.  You can easily generate a report of commits in master that are not in the release branch with the command(s) below.  Unfortunately, this report is not limited to commits since the last release.  Commits (lines) that begin with a '+' have not been applied to the release branch. 

 

$git cherry Example
$ git checkout master
$ git fetch origin                      // Apereo sources
$ git cherry -v origin/rel-4-1-patches  // release branch
Sample Output from $git cherry
+ f98d12932dcb275706eb1229805f5c6d009ac8ef UP-4146 Add coveralls.
+ e0aa5b4ec9bf6aaaf43e8c95c8b6480080122457 Exclude generated source and classes.
+ 2ad3b7f4cf23653e3b034e923a455d2e175dc7f4 Externalize coveralls and cobertura plugin versions.
- 7f3d735ee24314f85351673a417dae8a83bad914 UP-4143
+ 336b632dba510e41fae218a719fefbd317ba7557 Add trivial unit test.
+ b44ea44512f0915034c9af2f29b59766ceb81941 UP-4165: Add Google Analytics to muniversality
- 232595a8d9013fc9e199e4f58d4413ca0f8455ab UP-4168 Enable configuring single pre-populating auto suggest source
+ f46163b98ff1e1a518edabb306095b66655e0a76 UP-4170 allow Ant 1.9.3+.

 

Pre-Release Testing

Before cutting a release it is highly recommended to do the following testing at a minimum

  1. Build & Test a Quickstart

    cd assembly
ant clean prepare-deploy
    1. Once the build completes extract the generated quickstart, start it up and verify it works as expected.  (Instructions)
  2. Review README files, check dependency and tool versions and make sure they are all consistent with what is actually expected by the build system.

Steps and instructions for cutting a uPortal release.

  1. Update the Release Notes. Create the appropriate release page as a child of the Release Notes page for a minor release or the relevant minor release page for a patch release.
    1. Release JIRA version and move all unresolved issues to next relevant release (so, if releasing 4.1.0, push unresolved issues to 4.1.1)
    2. Review the JIRA issues of type Bug affecting the prior release.  If they weren't resolved for this release, then they probably also affect this new release.  Update their affectsVersion to include this release so they'll appear in the known-issues listing for this release.
    3. Create next minor release version (if not present)
    4. Copy last minor release wiki page and change versions, copy/paste release notes.
    5. Desirable: summarize the machine-generated release notes with something human-readable intended to help adopters understand what they're looking at and why and how they ought to upgrade to it.
  2. Update the NOTICE file and license file headers

    1. NOTICE file update 

      mvn notice:generate
git add NOTICE
git commit

    2. License file header 

      mvn license:format
git add <files that were changed>
git commit

  3. Build & Deploy the Maven artifacts & site

    mvn release:prepare
mvn release:perform

    1. Note: The tag should be uportal-<major>.<minor>.<patch>[-M<milestoneVersion>|-RC<releaseCandidateVersion>]

  4. Build the quickstart and source distribution 
    cd target/checkout/assembly
ant clean prepare-deploy
 

     

  5. TEST THE QUICKSTART
    1. Start the QuickStart and poke around, make sure everything looks good.
    2. Close the release in Sonatype to ensure the pushed Maven artifacts pass checks.  Do this now, so that if they don't pass checks, you don't push a tag of a release that doesn't pass checks.
      1. Go to https://oss.sonatype.org 
      2. Log in, of course.
      3. Search among Staging Repositories for your username
      4. Select the repository you staged and hit "Close" (the lifecycle is Open --> Closed --> Released).

    3. If it checks out PUSH THE RELEASE TO GITHUB

      $ git push <remote for jasig> <tagname>     # example:  git push jasig uportal-4.0.12
$ git push <remote for jasig> <branchname>  # example:  git push jasig rel-4-1-patches

    4. If there is a problem roll back the release commits locally, drop the staging repo at sonatype, and fix the problem and start over at step 1

      git reset --hard HEAD~2
  6. Now that the release commits and tags are pushed, the branch being released can and should be un-frozen.  Email uportal-dev@ replying to your FREEZE email announcing the THAW.
  7. Update the developer.jasig.org site by running bamboo with the tag you just created: https://developer.jasig.org/bamboo/browse/UP-RELSITE
    1. Upper right Run --> Run Customized --> set the tag name --> Run
  1. Edit the Release associated with the tag in GitHub
    1. Add release notes
    2. Upload the binaries

  2. Go to https://oss.sonatype.org and release the staging repository
    1. Navigate to "Staging Repositories"
    2. Select the same project you "Closed" above and hit Release.
  3. Update Jira
    1. Mark the version released, moving remaining open issues to the next version.
    2. Do a query for all unresolved issues that affect the previous release and release candidates. Add the new release version as an affected version for each issue in the results.
    3. Batch transition all resolved issues for the version to closed (Don't do this?  It's really annoying in preventing updates to those issues to improve their metadata.)
  4. Create Public Release Notes on http://www.apereo.org/uportal
    1. Go to https://www.apereo.org and log in
    2. Create a Product Release
    3. Give the page a title of uPortal X.Y.Z
    4. Add the magic tag uPortal product release
    5. Add a link to the GitHub release page's hosting of the binary releases
    6. Add a short release note, linking to the wiki page and to the GitHub release page
    7. Under the URL path settings section set a URL of: uportal/download/uportal-X-Y-Z
    8. Under Publishing options check Published, Promoted to front page, and Sticky at top of lists
    9. Click Save
    10. Then go and edit the page for the previous release and under Publishing options uncheck Promoted to front page, and Sticky at top of lists
  5. Create a news entry on http://www.apereo.org/uportal
    1. Add a news entry (type=Article; tag="uPortal news") so that news of the release surfaces to the /uPortal page.
    2. Give it a URL path of uportal-news/uportal-x-y-x
  6. Send Email
    1. For a Milestone or RC release, email to uportal-dev is needed.  Be sure to acknowledge those who contributed to the release.
    2. For a GA release also email uportal-user .  Be sure to put the release into context for an existing adopter to understand.
    3. For a GA release also email jasig-announce , announcing the release to a general public audience.  (Do we still do this?  Haven't done this for a couple releases?)
  7. Update release notes link to link latest
    1. Update the parent page(s) of the Release Notes page you created for your release to highlight and link your release as the latest.

Special JIRA handling for Milestone and Release Candidate releases

 

Milestone releases are special in that their Version tags in JIRA are additional rather than instead of the relevant general audience release.  So, a defect affecting a prior release that is fixed in uPortal 4.2.0-m1 would be tagged as fix-for 4.2.0-M1 and also 4.2.0.  This way the issue will show up both in reporting on what was included in the milestone release and in reporting on what was included in the general audience release, convenient for adopters considering only the GA releases and so considering what changed from 4.1.0 to 4.2.0.