At Adobe, we’re always striving to keep our Merchants’ eCommerce stores secure, performant and reliable by helping them stay up-to-date with the latest versions of Adobe Commerce. Just as if you were taking care of a physical store, an eCommerce store requires maintenance to make sure you are providing the best experience for your customers, but we are aware of the potential challenges that are associated with the upgrade process as well as the recurrent investment required.
Thus, we are proud to introduce the first stable version of the Upgrade Compatibility Tool, available now to Adobe Commerce customers. Upgrade Compatibility Tool is a Command Line Interface (CLI) application that analyzes a given Adobe Commerce instance, pointing out any issues line by line so that you can be aware of what needs to be fixed before starting the upgrade process.
Let's take a deeper dive into how it works.
Using the Upgrade Compatibility Tool
For the Upgrade Compatibility Tool to work, you will need the following minimum requirements:
- PHP version 7.3 or higher
- Composer
- Adobe Commerce composer keys
- An old Magento instance to check against
- At least 2GB of RAM
1. Provided that you have the required Adobe Commerce credentials set up in your system, type the following into a terminal window to install Upgrade Compatibility Tool:
composer create-project magento/upgrade-compatibility-tool --repository https://repo.magento.com
2. Once the installation is finished, you're ready to check an Adobe Commerce instance. Suppose you have Adobe Commerce version 2.4.0 installed and want to upgrade to version 2.4.3. In the Upgrade Compatibility Tool path, you would type:
bin/uct upgrade:check /path/to/adobe-commerce-2 -c 2.4.3
3. After some processing time that will vary depending on the number of 3rd party modules installed and volume of customizations in your instance, the results will be shown as follows:
Results are grouped by module and file, and each issue is identified by the line number where the issue occurs as well as a description of the issue itself.
In addition, issues are labeled with one of three severity levels:
- Warning: issues that won't affect the upgrade process, but require attention
- Error: issues that may affect the upgrade process for the intended or future versions
- Critical: issues that must be resolved before upgrading
At the end of the issues list, you’ll see a snapshot of how many issues you may need to address before tackling the upgrade, as well as some metrics related to the tool execution. This summary of results is also exported to a file in the event that you need to import them to another tool.
4. Lastly, you can filter results with various commands.
- –min-issue-level will show issues only with a severity level greater or equal to the issue before it
- --ignore-current-version-compatibility-issues will not include known issues in your report
- bin/uct–help or our devdocs can show you additional ways that the Upgrade Compatibility Tool can be of benefit
What's next
We aim to continually improve the Upgrade Compatibility Tool to best serve our customers’ needs. As you test the tool, we encourage you to provide feedback by filling out a survey. In addition, you can contact us via the #upgrade-compatibility-tool Slack channel should you have any questions.
Stay tuned for announcements about future Upgrade Compatibility Tool releases – until then, happy upgrading!