The Apereo CAS project presents a rather active and healthy development cycle, with monthly maintenance releases and patch versions. There are also feature (or minor) releases typically twice a year, and the project, of course, reserves the right to publish a major release once every few years to keep up with the latest trends and technologies in the IAM and OSS ecosystem. Given a CAS deployment is made up of many moving parts, frameworks, and components, it is important to keep up with the latest CAS releases to take advantage of new features, enhancements, and security fixes.
In this post, we will present a brief overview of the various CAS release types, their impact and maintenance needs. We will also review the necessary steps and strategies required for a CAS upgrade to outline how one may manage and adjust different CAS versions from one to the next.
Apereo CAS generally and loosely follows the concepts of Semantic Versioning, with some small modifications and adjustments to match the realities of CAS deployments in the wild. These modifications are necessary to maintain a healthy development lifecycle and set clear expectations regarding the maintenance and support needs of the larger community.
Let’s start with the initial modest assumption that our starting CAS version is set to A.B.C in our CAS overlay’s gradle.properties file:
cas.version=A.B.C
A CAS security release is one that is typically presented in the form of A.B.C.1, A.B.C.2, etc. Such releases directly address a targetted security issue and are generally extremely lightweight and lean in nature, and only focus on a specific area in the codebase. As a result, going from a security release to the next should be a drop-in replacement. Essentially, all you should have to do is to modify your CAS version in the gradle.properties file and aim for the target desired version:
cas.version=A.B.C.1
That’s it. Unless the instructions clearly indicate otherwise, or you have made significant code modifications to your CAS overlay, that is all you should have to do. No more, no less. You can pretty much close your eyes and proceed with the CAS upgrade with the assurance that nothing else in your build will require any attention except the area that is affected by the security release, which is typically buried in the bowls of the software itself and should be largely invisible to you.
Note that security releases are not, strictly speaking, 100% backward compatible when it comes to CAS APIs. If you have made code modifications to your CAS build, especially in the areas that might be affected by the security release, you might be expected to make adjustments. Of course, every effort is made to ensure breaking APIs are avoided or kept to a minimum but sometimes and depending on the nature of the fix, this might not be completely avoidable. Likewise, you might see differences in CAS behavior at runtime if you are affected by the security issue, which makes it super important to have a solid test suite to verify that changes are up to your expectations as you progress.
For the majority of deployments, changing the CAS version in that one line is enough. You do not need to reboot or refresh your entire CAS overlay project from scratch or make any other significant modifications to your build unless there are very, very good reasons to do so. The CAS project largely supports the mantra of favoring less work, and this is very much in line with that spirit.
A CAS patch or maintenance release is one that is typically presented in the form of A.B.1, A.B.2, etc. When the right-most number changes, it signals to the adopter that this release contains small enhancements and bug fixes largely deemed to be backward compatible, save the usual exceptions when it comes to code or runtime behavior. A maintenance release is usually very small and focused in nature and targets one or more areas in the CAS ecosystem that likely suffer from bugs and defects, be it Java components, user interface, language bundles, documentation, etc.
Patch releases typically come out once every 30 days. You can watch the release schedule here.
Similar to security releases, a maintenance release does not require the adopter to reboot or refresh the CAS overlay project, and will never, intentionally of course, force breaking API changes or require major upgrades to the deployment environment or the underlying Java platform or relevant build tools. In a maintenance release, (and while there are some super minor exceptions to this rule from time to time such as servlet container versions like Apache Tomcat, etc), nothing else other than CAS itself changes.
For such versions, all you should have to do is to modify your CAS version in the gradle.properties file and aim for the target desired version:
cas.version=A.B.1
That’s it, you’re done. Remember that there is no way to mess this up; if you are unhappy with the newer version, you can just adjust that one line and go back and forth as you wish.
A CAS feature or minor release is one that is presented in the form of A.1.C, A.2.C, etc. When the middle number changes, it signals to the adopter that this release contains somewhat significant features and enhancements such as new integrations, new extensions and more. Feature releases might not be completely backwards-compatible when it comes to CAS APIs, configuration and/or runtime behavior.
Feature releases usually come out once every 6 months, and present a series of beta or release candidates along with relevant release notes for each to highlight breaking changes and summarize new features. The goal here is for the adopter to be able to follow along the process, keep tabs on potential breaking changes relevant for their deployment and hopefully contribute feedback and fixes. A release candidate, by definition, is exactly that: a candidate that may be somewhat unstable for a very specific definition of stability. In a CAS release candidate, the system and the build might depend on SNAPSHOT or RC libraries, and certain types of functionality or extensions might be tagged as WIP. APIs might change from candidate to candidate. Remember that the goal here is to demonstrate progress and collect feedback.
Specifically a CAS feature release might require the interested adopter to:
As a result, it might be easier to reboot and refresh the CAS overlay and start anew, unless you really know what you’re doing and have kept up with the release progress and process over the months. It may not be immediately enough to just upgrade the CAS version in your build; other plugins and components used in the build might also need your attention.
A CAS major release is one that is presented in the form of 1.B.C, 2.B.C, etc. When the left-most number changes, it signals to the adopter that this release could contain significant features and enhancements such as new integrations and most importantly, platform-level requirements might have changed. You may be asked to go to a newer Java version, or an entirely different operating system, etc. A major release is, by definition, free to change anything and everything, though, of course, every effort is made to ensure application data and configuration remain compatible. Should the need show up, however, with very, very good reasons, a major release allows for that sort of change to pass.
CAS major releases do not follow a predefined schedule; they are decided upon by the project maintainers and developers when time and technology feel right and are in demand. Anecdotally, they are released once every few years mainly to keep up with the Java release cadence. Just as before, it might be easier to reboot and refresh the CAS overlay and start anew, unless you really know what you’re doing.
If you have questions about the contents and the topic of this blog post, or if you need additional guidance and support, feel free to send us a note and ask about consulting and support services.
Happy Coding,
Monday-Friday
9am-6pm, Central European Time
7am-1pm, U.S. Eastern Time
Monday-Friday
9am-6pm, Central European Time