uPortal 5.x Release Process
- Use Gradle to tag, push, and upload the release to Sonatype (documentation)
- Close & release the Nexus Staging Repository within Sonatype
- Release the version in the Manage Versions JIRA UI
- Create the release notes
- Create & update the appropriate release page as a child of the Release Notes page
- Use Git to inspect the incremental commits since the last release (e.g.
$ git log v5.0.5 ^v5.0.4 --no-merges)
- Review the issue tracker and confirm that referenced issues have been Resolved
- Enter the release notes on the GitHub releases page
- Open a Pull Request on
uPortalVersionto the new release
- Publish a new
apereo/uPortal-demoDocker image and update the
:latesttag 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@.
- Suggestion: Review the
masterbranch 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.
Before cutting a release it is highly recommended to do the following testing at a minimum
Build & Test a Quickstart
- Once the build completes extract the generated quickstart, start it up and verify it works as expected. (Instructions)
- 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.
- 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.
- 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)
- 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.
- Create next minor release version (if not present)
- Copy last minor release wiki page and change versions, copy/paste release notes.
- 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.
- Update the NOTICE file and license file headers
NOTICE file update
License file header
Build & Deploy the Maven artifacts & site
Note: The tag should be uportal-<major>.<minor>.<patch>[-M<milestoneVersion>|-RC<releaseCandidateVersion>]
Build the quickstart and source distribution
- TEST THE QUICKSTART
- Start the QuickStart and poke around, make sure everything looks good.
- 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.
- Go to https://oss.sonatype.org
- Log in, of course.
- Search among Staging Repositories for your username
- Select the repository you staged and hit "Close" (the lifecycle is Open --> Closed --> Released).
If it checks out PUSH THE RELEASE TO GITHUB
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
- 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.
- Update the developer.jasig.org site by running bamboo with the tag you just created: https://developer.jasig.org/bamboo/browse/UP-RELSITE
- Upper right Run --> Run Customized --> set the tag name --> Run
- Edit the Release associated with the tag in GitHub
- Add release notes
- Upload the binaries
- Go to https://oss.sonatype.org and release the staging repository
- Navigate to "Staging Repositories"
- Select the same project you "Closed" above and hit Release.
- Update Jira
- Mark the version released, moving remaining open issues to the next version.
- 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.
- 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.)
- Create Public Release Notes on http://www.apereo.org/uportal
- Go to https://www.apereo.org and log in
- Create a Product Release
- Give the page a title of uPortal X.Y.Z
- Add the magic tag uPortal product release
- Add a link to the GitHub release page's hosting of the binary releases
- Add a short release note, linking to the wiki page and to the GitHub release page
- Under the URL path settings section set a URL of: uportal/download/uportal-X-Y-Z
- Under Publishing options check Published, Promoted to front page, and Sticky at top of lists
- Click Save
- 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
- Create a news entry on http://www.apereo.org/uportal
- Add a news entry (type=Article; tag="uPortal news") so that news of the release surfaces to the /uPortal page.
- Give it a URL path of uportal-news/uportal-x-y-x
- Send Email
- For a Milestone or RC release, email to uportal-dev is needed. Be sure to acknowledge those who contributed to the release.
- For a GA release also email uportal-user . Be sure to put the release into context for an existing adopter to understand.
- 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?)
- Update release notes link to link latest
- 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.