Quality Patches Tool Overview and How to Efficiently Use It

Most of our readers know that Magento has security, cloud, quality, and custom patches that can be installed to fix particular website issues on Adobe Commerce or Magento Open Source platforms. 

In this post, we’ll speak about the tool released by Adobe to apply quality patches and work with them – Quality Patches Tool (QPT). In addition, we’ll describe how to use QPT on different Magento platforms and the existing best practices.

Overview.

Quality Patch is a fix provided by Adobe Commerce support or the Magento Open Source community to resolve a particular issue/bug in a core Magento functionality. Quality patch is available for certain Adobe Commerce/Magento Open Source versions and in most cases, it is included in the newest release.

Quality Patches Tool or QPT allows you to apply, revert, and view general information about quality patches available for your installed version of Adobe Commerce (for both on-premise and cloud infrastructure) and Magento Open Source.

The list of all available quality patches can be found in the Adobe Commercial DevDocs. More detailed information about a specific patch can be found at Adobe Commerce Help Center

Please note that the Quality Patches Tool is for quality patches only.

Security patches can be found in the Magento Security Center.

Installation on a quality patch

QPT is delivered as a composer package. So, for Adobe Commerce on cloud infrastructure, the package is included in the ECE-Tools package (available from 2002.1.3 ECE-Tools version).

To install the latest QPT package, use:

composer update magento/ece-tools --with-dependencies

For the Adobe Commerce (on-premise) & Magento Open Source QPT can be installed via the next command:

composer require magento/quality-patches

Applying quality patches

To apply a quality patch on Adobe Commerce on cloud infrastructure use QUALITY_PATCHES variable in the .magento.env.yaml file:

stage:
  build:
    QUALITY_PATCHES:
        - MCTEST-1002
        - MCTEST-1003

You need to commit your changes to .magento.env.yaml and provided in QUALITY_PATCHES patches will be installed automatically to cloud instances within a deployment.

Before pushing quality patches to cloud instances, you should apply patches manually in a local environment and test them before you deploy.

To apply patches to a local environment, run the next in your project root:

vendor/bin/ece-patches apply

and do not forget to clear cache after that:

bin/magento cache:clean

Keep in mind that ECE-Tools applies patches in the following sequence:

ECE-Tools applies patches in the following sequence

Test the patches, and make any necessary changes to custom patches if needed.

To install a quality patch on Adobe Commerce (on-premise) & Magento Open Source run the following:

vendor/bin/magento-patches apply MCTEST-1002 MCTEST-1003

Also, please don’t forget to clear the cache after applying patches to see changes in the Magento application.

QPT controls quality patch installation and does not allow to install a patch twice. See the example below:

QPT controls quality patch installation1
QPT controls quality patch installation2

We recommend using the post-install-cmd command event in composer.json to install QPT patches on projects with non-cloud infrastructure.

Example, of post-install-cmd command event in composer.json:

"scripts": {
        "post-install-cmd": [
            "bash post-install.sh"
        ]
}

A content of post-install.sh bash script is:

#!/bin/bash

appliedPatches='MCTEST-1002 MCTEST-1003'

if [ "$appliedPatches" ]
then
    ./vendor/bin/magento-patches apply $appliedPatches
fi

Reverting quality patches

The reverting process is very simple.

Adobe Commerce on cloud infrastructure:

Remove a necessary patch from the QUALITY_PATCHES in .magento.env.yaml.

Adobe Commerce (on-premise) & Magento Open-Source

vendor/bin/magento-patches revert MCTEST-1002 MCTEST-1003

To revert all quality patches:

vendor/bin/magento-patches revert —-all

As during a patch installation, QPT also controls a revert operation and won’t allow reverting a patch twice or reverting a patch that is not applied. 

See the example below:

QPT won’t allow reverting a patch twice1

Checking the patch status

QPT provides an ability to check the statuses of all quality patches.

You may use one of the following commands to check the statuses of quality patches for Adobe Commerce and Magento Open-Source in shell:

vendor/bin/ece-patches status
vendor/bin/magento-patches status

In Adobe Commerce on cloud infrastructure, you may also check the statuses of quality patches in the Site-Wide Analysis Tool (SWAT):

check the statuses of quality patches in the Site-Wide Analysis Tool (SWAT)

Logging of patching operations

The Quality Patches Tool logs all operations in the <Magento_root>/var/log/patch.log file.

Example of a log:

Quality Patches Tool logs all operations

Recommendations when using a Quality Patches Tool

  • If you see an issue in your Adobe Commerce or Magento Open Source project please check QPT for a quality patch.
  • We do not recommend using the QPT to apply large numbers of patches because it increases the complexity of project code, which makes upgrading to a new version of Adobe Commerce or Magento Open Source more difficult.
  • We strongly recommend testing all patches in a staging or development environment before deploying to production.
  • Consider keeping a list of applied patches in a separate location. You might need to re-apply some of them after upgrading to a new version of Adobe Commerce or Magento Open Source.
  • After upgrading to a new version of Adobe Commerce or Magento Open Source, you must make a revision of installed patches and re-apply patches if the patches are not included in the new version.

Quality Patches Tool and Magento community

Quality Patch, which was created by the Magento community, is not verified by the Adobe QA team. There is a video guide about quality patch creation by contributors.