Cutting a uPortal Release

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

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.
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. Create next minor release version (if not present)
   2. 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).
   3. 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.
   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

   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.