Upgrade Compatibility Tool Overview

Transcript

Hi folks. In this video, you will learn what is the Upgrade Compatibility Tool? How to download it and install it? How to use it? And which are the best practices to make the most out of it? Apart from that, we’ll show the different reports that the Upgrade Compatibility Tool generates. Let’s start.

The Upgrade Compatibility Tool is a common line tool that analyzes your instance for potential upgrade issues. It checks for issues between the current version you have installed and the version you are trying to upgrade to. Using this tool will reduce the effort required from your team to understand the scope and impact of the upgrade. It will help you avoid common code issues when upgrading and provides clear direction on how to resolve issues found. It also helps prioritize the most critical issues necessary to ensure a successful upgrade, saving time and cause when upgrading.

In order to download the tool, you will need to run the composer create-project command, since it is distributed as a composer package with every release of Adobe Commerce version.

Execute the composer create-project command on your terminal.

Remember, that it requires PHP 7.3 or later, at least 2 gigabytes of RAM, Node.js and Adobe Commerce Access keys. When the tool is already installed, let’s make sure that it has the right permissions to execute it in your system. You can do so executing this command.

You can double check that it’s running without problems, simply executing bin/uct list, which will give you a list of the available commands. The main one is the upgrade:check command, which analyzes your instance and checks errors, warnings and critical error in your Adobe Commerce instance. You need to provide the directory of your Adobe Commerce code base and optionally the version you want to check against. In case it is omitted, the latest release version of Adobe Commerce will be used.

It is important to mention that you can just run the tool to analyze a certain vendor, module or even a directory, which would be much faster than analyzing the whole Adobe Commerce instance. In this case, you will need to specify the path as an option.

Some other interesting options to use with this command are -i or --ignore-current-version-compatibility-issues. This one suppress all known critical issues, errors and warnings against your current Adobe Commerce version. It will only provide errors against the version you are trying to upgrade to.

The other one is about setting the minimum issue level. This option helps you prioritize only the most important issues with your upgrade. The values you can use are warning, error and critical in ascending order of severity.

Using these comments together, will help you identify the most critical issues for your team to address.

As a result of the analysis perform the Upgrade Compatibility Tool displays a list of issues for each file specifying its severity, error code and error description.

You can easily navigate through the files by clicking the link and jumping to the specific line in order to fix whatever is needed to be compatible with a target version.

The report includes a detail summary that contains very useful information. You can see the percentage of modules and files that require update, and the number of critical issues, errors and warnings found during the analysis. You will notice that there is also a link to the error message reference which contains detail information for all the error codes. Apart from the list and summary displayed in the terminal, you are provided with reports in different formats, since the Upgrade Compatibility Tool exports them by default. On the one hand, you have the report in JSON format, which can easily be used from the merchant management or agency side. This format is more suitable for integrations with other tools. On the other hand, the HTML report will be perfect for high level evaluation of complex projects, because apart from the list of error and summary shown before, it provides very useful diagrams. These diagrams show the modules by issue severity, the files by issue severity and the modules that have more backwards incompatible changes. All issues identify by the tool, are listed on the report with a specific error codes. Use the documentation to get more detail about each error message reference. Adobe also gives suggestions to fix each issue type so you can plan out your remediation steps. Use the report to estimate the amount of effort it will take to update your code. Since this is a common line tool, you can incorporate it into automated testing and code checks suites. You can also use the JSON output to generate your own reports. Saving the results from each upgrade project is recommended, so that you can compare future upgrade results with previous results. It’s also recommended that you run the tool regularly while working on the upgrade to have visibility into your progress. The number of issues should decrease as you fix them. The Upgrade Compatibility Tool will continue to be improved upon and future releases will include features such as auto fixes to help you fix issues as fast as possible. Just for you to know, there is a Magento2 PHP Storm plugin that includes a built-in Upgrade Compatibility Tool, so that the developers will have the chance to run this tool from the IDE which will let them avoid compatibility issues during the development phase. Please check the documentation if you are interested in this topic. Thank you very much for your attention. -