Web Framework version system
This RFC describes the versioning and update system to be used by Web Framework 2, which will replace the current Web Framework.
For more on the rationale for the features described in this RFC and how these changes might impact your team, see the Web Framework 2 product summary.
Versions in Web Framework 2
Web Framework 2 departs from the previous version of the framework in that it follows an industry-standard convention called semantic versioning. If you’ve used IU’s Rivet design system in a project, you’re likely already familiar with semantic versioning.
You can read more about the technical details of semantic versioning, but here are the two key takeaways for framework site managers:
Versions are cumulative
Versions of the Web Framework are no longer isolated releases that can be optionally applied in potentially any order. Instead, versions are cumulative and include all new features and bug fixes added in all previous versions.
Includes changes made in 2.1.0
Includes changes made in 2.1.0 and 2.2.0
Includes changes made in 2.1.0, 2.2.0, and 2.3.0
Updates are a single indivisible package
In the current version of the Web Framework, updates are released as a collection of edits that need to be made to specific code files and assets on each site, some of which were optional with regard to brand, accessibility, or security guidelines.
Version 2 of the Web Framework bundles updates into packages that are applied in their entirety using a web-based update tool. This prevents partial updates from being applied that leave sites in an uncertain version state (or updates being skipped entirely). This approach also simplifies site maintenance and support, as all sites of a given Framework version are consistent in terms of code.
Framework site manager dashboard
Managers of a Web Framework 2 site can sign in to the Framework site manager dashboard using IU Login.
The dashboard lists all sites for which the logged-in individual is a manager and includes details about each site’s current version and actions the individual can take with each site. It is through this dashboard that all Web Framework site updates are managed—there is no longer a manual component to updating a Web Framework site.
1. “Updates required” alert
This alert will show if one or more sites need to be updated. The alert includes a link to the changelog which shows in detail what’s new in the latest release of the Web Framework.
2. A framework site you manage
Each entry shows the name of the site, along with the site’s current version and the IU username of the person who applied the last version update.
If a site needs to be updated, the icon will show a yellow exclamation point. If a site is up to date, the icon will show a pair of circular green arrows (in the case of a site that’s set to update automatically) or a green checkmark (in the case of a site that updates only when a site manager initiates the process).
3. Actions tab
Reveals the actions that can be taken with a site, including updating the site, managing the site’s plugins, and toggling automatic updates.
Update confirmation screen
Before applying an update, a site manager will be shown an update confirmation screen. This screen details each step of an update and notifies a site manager of any issues that prevent the update from being safely applied.
1. Update summary
A short description of what’s new in the Web Framework version to which the site is being updated. Includes a link to the full changelog so that a site manager can view in detail what has changed.
2. “Unable to apply update” alert
If there’s an issue with the site that would prevent the update from being applied, this alert will appear.
3. Update steps overview
A summary of all steps the update system will take to update the site to the latest version. A green checkmark will appear next to update steps that the tool has determined it can safely apply.
4. Update step that cannot be applied
An example of an update step that cannot be applied because the update system found an issue that would prevent that update step from being applied safely. A red circle and slash will appear next to update steps that cannot be applied.
Situations in which an update step cannot be applied are rarely the result of a site manager’s actions and typically represent an issue with the WCMS, such as an outage. Site managers are encouraged to contact UITS Support to resolve the issue.
5. Submit button
The button to confirm and schedule the update. In this example, the update cannot be applied because there is an issue preventing one of the steps from being applied, so the button is disabled. This button is active when no issues are detected.
Web Framework sites can be set to update automatically when a new version is released. Site owners have control over which of their sites update automatically.
Sites set to update automatically are added to a queue to be processed overnight in the week following a Web Framework release. When an update is applied, the site’s managers will receive an email notification. Likewise, site managers will be notified by email if an issue prevents the automatic update from being applied.
To keep from overwhelming the WCMS server, site updates are added to a queue instead of applied immediately. The task queue processes job requests in the order in which they are received.
In most cases, an update will be applied to a site within a few minutes after a site manager submits the request. When the update is complete, the site’s managers will receive an email notification.
Notifications and logging
The update system sends email notifications to site managers when:
- A new version of the Web Framework is available
- Automatic updates have been toggled on or off for their site
- Their site has been successfully updated
- The update system ran into an issue trying to update their site
In addition, everything the update system does is logged. Site-specific logs are viewable by site managers in the version manager dashboard. Members of the Web Framework team and UITS Support can also view these logs in order to help troubleshoot issues.
Frequently asked questions
Below are answers to some frequently-asked questions about the Web Framework 2 version system.
Will any updates require me to make manual changes to my site’s code?
No. All Web Framework updates are now handled through the site manager dashboard.
Are all updates mandatory?
Starting with Web Framework 2, there will no longer be a distinction between required or optional updates (or parts of updates). However, updates will often include bug fixes, accessibility enhancements, or security patches, so site managers are encouraged to update their sites as soon as possible after a release is made available.
Framework updates will be released on a regular schedule (likely every other month), and when a site manager is ready, they can sign in to the site manager dashboard and update their sites. Site managers can also set their sites to be updated automatically when a new version is released.
What happens if something goes wrong during an update?
The update system tries to prevent problems before they happen by verifying that it can safely carry out every step of an update. If the update system detects a problem, it won’t let a site manager update the site.
In uncommon situations where the update system runs into a problem while updating a site (such as the WCMS experiencing an outage mid-update), the system knows how to roll back a site if possible. Problems with an update are also logged and both site managers and the Web Framework team are automatically notified so that the issue can be resolved.
How often will I run into update steps that can’t be applied?
If a site is customized using the Web Framework’s new plugin, override, and hook systems, a site manager should rarely run into a situation where an update step cannot be applied.
If they do, members of the Web Framework, Web Studio, and UITS Support teams will be trained to help resolve any issues. Documentation will also be available to help site managers troubleshoot issues preventing an update from being applied.
Will updating my site erase or break any customizations I’ve made?
Web Framework 2 provides several new methods for customizing a site, including plugins, overrides, and hook actions. These customization methods are built to work with the update system, so updating a site to a new version will not overwrite any customizations made using these methods.