The primary role of Upgrade Status is to help get your site components updated for Drupal 9 compatibility. Most of your site components are contributed modules. In many cases, either your local copies or the remote available updates will already be compatible. 38% of Drupal 8 compatible modules are now Drupal 9 compatible (3535 out of 9258) and most others have a patch waiting to land to either improve or complete compatibility. Let's look how the role of Upgrade Status has evolved.
Note: This post was originally posted on Gabor's main blog: http://hojtsy.hu/ in August of 2020.
The changing role of Upgrade Status
Therefore, the role of Upgrade Status for contributed projects is more to make you realize that you are one of (a) already compatible (b) will be compatible with an update or (c) should work with the maintainer on existing issues. As opposed to scanning for problems locally and trying to fix it for yourself. But the current 2.x version of Upgrade Status does not do the job of indicating most of these. Without running the (lengthy) scans on your projects, it does not know which local projects are already compatible. And although it has access to information about whether remote updates are Drupal 9 compatible or not, it will not display them. Look at this screenshot:
We only know the Consumers project update is going to solve your Drupal 9 compatibility issues because the maintainer kindly explained that in their Drupal 9 plan. This requires manual work and is not going to happen universally (e.g. as shown below neither Chaos Tools nor Markdown specify a Drupal 9 plan). For projects like Consumers, there is not even a good reason to run our lengthy compatibility checking locally because we know the remote update is available and is going to be compatible. Plus, we already know from the local info file that the local version is not yet compatible and requires that update. So if we would provide all this "new" data, the user could understand the situation and decide to not even run a compatibility scan but update the project. So the first step (hopefully) improving the Upgrade Status experience was to add more raw data about local and remote Drupal 9 compatibility. Then it looks like this:
The new "Local 9-ready" column shows if the project is already ready locally (without scanning the project, based on info files in the project). The new "Drupal.org 9-ready" column shows if the remote update is Drupal 9 compatible or not (based on information already provided to core's update module). So what we can see from this example is that Chaos Tools will be entirely resolved with an update, no need to run a problem scan locally. Markdown will not be entirely resolved, but is worth updating either way because likely there will be fewer issues. Not all projects will specify a Drupal 9 plan to go by as discussed above. But if there was no plan specified, we could still link to the issue queue. I don't think applying issue tags consistently is possible to expect from all contributors, so we cannot link to an issue tag search. The link goes to a drupal.org issue search for "Drupal 9" issues in the project. This is the fastest way to get to a place to collaborate with the maintainers of Markdown, given no Drupal 9 plan posted.
Deciding on the next step for each project
So more raw data is great, right? Well, it probably makes the display a lot more confusing. Based on what you read out about the data you would do different things to different projects. For the 2.x version Joe at Drupalize.me published a great post about how to read the data. But what if the module would make suggestions for next steps instead of you needing to carefully examine each part of the data. We could still give users the source data, but save a lot of time to compare data points as to whether a project should be updated or needs more work, etc. Enter the next step suggestion engine I built following extensive discussions with Ofer Shaal. The possible next steps for projects are:
- Remove: if you have uninstalled projects on your site, there is likely no point in investing effort keeping them up to date.
- Update: if your project has a remote update, that is the best course of action; even if Drupal 9 compatibility is not entirely done there, it is likely improved.
- Collaborate with maintainer: contributed projects that are up to date could still have issues; instead of fixing locally, there is high probability that there are issues (including but not limited to from Project Update Bot) in the queue, so better start collaborating instead of fixing locally.
- Scan: unless your custom project's info files specify Drupal 9 compatibility already, the suggested next step is to scan them
- Fix with rector: for custom projects there is a 40+% likeliness that there is at least one problem we find that is rector-fixable, we suggest you use rector as your next step to avoid needless manual work (again) in this case
- Fix manually: if you scanned and there were no rectorable fixes, as a last resort we suggest you fix issues manually
Instead of grouping by custom/contributed and under that installed/uninstalled, the 3.x branch now groups results based on the next suggested step. The raw data is still shown and users can still do whatever they decide if they do not agree with the suggested next step.
This is the state of the module's user interface right after installation. We can already deduct a lot of information from local Drupal 9 readiness, update information and status of projects. For the single custom project in this test setup, we can only move forward with scanning it for problems. The numeric counters of problems found overall were removed, because in the current state of contributed projects rapidly getting ready, counting their individual issues together does not really inform about anything useful.
Overview of status of your site
Usage of Upgrade Status has always been a three-step process. First, you need to help the module gather data (run available update checks, run scanning of projects). Second, you would attempt to fix the problems found (update modules, run rector, etc.). Then you scan again and verify compatibility improved. So instead of putting this into documentation, I designed a summary view for the top of the page that helps you go through the data gathering, the compatibility fixing and the celebratory steps. Here is how that looks like for my test site:
- The data gathering steps ensure the module works with the best data possible. Having a way to accurately identify project versions is important, so projects are suggested for that (unless already installed). Having up to date available update information is important, so it is possible to run that directly from here. There are projects where scanning on this UI is the next step to gather the required data (to move to "Fix with rector" or "Fix manually"). On this site I have one of those test modules. And finally, the UI indicates you can scan either project as you see fit.
- Based on the data available, the second columns shows all the next step suggestions for fixing compatibility issues. Projects to remove because they are uninstalled anyway, projects to update, collaborate on, fix with rector, and so on. If your environment is incompatible, that also shows up here with a link to details.
- Finally, there is a column to review what's ready to go. If your environment looks all good, that would show up here, as well as all the projects that are already compatible. A little circular chart shows how far along you are.
Comparing side by side
Check out the current user interface on the left and the new work in progress on the right. A summary of differences:
- The current UI is almost a blank slate and is not aware of project status locally or update's compatibility remotely.
- On the current UI to gather data you need to run the full scanner on everything. Then you need to decide on next steps based on your reading of the data.
- On the current UI the available updates refresh and the suggestion to improve version identification with the deploy modules is sort of hidden under "help text blindness", rather than being an active part of the UI.
- The new UI is actionable immediately with categories of projects by next step.
- The count summaries of problems found is gone, the focus is more on the projects rather than the individual problems. (Even though that data is entirely accessible).
What do you think?
I believe that more than two months after Drupal 9's release, the role of Upgrade Status is increasingly not to tell you to do fixes locally, but to allow you to obtain the fixes already made and collaborate on fixes being developed for contributed projects. And for custom projects, it should suggest you the most automated way forward (rector preferred) that will result in less work to execute. These were the guiding principles of the new user interface. I built it all in the 3.x branch of Upgrade Status, and you can try it out in 8.x-3.0-alpha1.
