Use the Quality Patch Tool

Transcript

Hello, and welcome to the demo of the Magenta Quality Patches tool.

I will be covering what Magenta Quality Patches is, installation process, usage on customer instance, internal tool structure, and workflow. The last topic will be release publication process.

Magento Quality Patches tool is a composer package that contains a set of patches and commands for working with them. It’s intended though to make distribution of quality patches across Cloud and OnPrem Magento customers.

So general flow looks next.

Support team creates a patch and pushes it into MQP repository.

As soon as the next version of the MQP composer package is published, the patch becomes available to Cloud and OnPrem customers.

Customer installs or updates MQP composer dependency, and gets the latest patches compatible with his Magento version.

Customer selects and applies patches that are needed for solving his issues.

Let’s take a look how it can work for OnPrem Magento customers.

Imagine that I’m a happy owner of Russian styled fancy Magento store. Everything is going well until one day, I face several core issues.

For demo purpose, I’ll add some issues to instance.

So, I have three issues and I’m not happy anymore. I’m calling to Magento support and asking for help. Support tells me, hey Victor, we are happy to inform you that your issues are known, and there is a Magento Quality Patches tool that will help you to fix them. If you are OnPrem customer, then you should require an MQP composer package using the command: composer require magento/quality patches. If you are a Cloud customer, just update magento/ece-tools and you will be all set.

Okay. Let’s try.

I’ll make small modifications in the command to get the demo package.

Need to wait for a while until composer updates the dependencies.

It can be not so fast.

And here we go. Now we have Magento Patches script located in vendor/bin folder.

This script provides next commands.

Status shows a list of available patches.

Apply performs patches planned, and revert performs patch reverting. Let’s check the list of available patches with the status command.

We see the table with next information. Patch ID. ID is the same as Jira issue number. Patch title shows title of the patch. Type. For OnPrem, all patches are optional. For Cloud, some pages can be required. Status can be applied, not applied, or not available, when we can’t identify status due to some conflicts. And details contains the list of effective components, and such information like required patches. We need this feature to solve possible compatibility conflicts. So, as customer, I see that patch MC-1 fixes Issue 1, patch MC-2 fixes Issue 2, and patch MC-3 fixes Issue 3.

It’s good news for me because I have all these issues on my instance. Let’s apply a first patch.

We see a message that a patch has been successfully applied, and let’s check status table.

We see that MC-1 patch has applied status.

Let’s refresh our instance, and we see that Issue 1 was gone and was fixed by patch MC-1. Patch MC-1 works. If I changed my mind and want to come back to Issue 1, I can revert the patch MC-1. Let’s do it.

We see a message that patch MC-1 has been reverted successfully. Let’s check status table.

We see that patch MC-1 has not applied status, and after refreshing the page, we see Issue 1 is on a place. Now I want to apply two patches at once to fix both Issue 1 and Issue 2. Let’s do it.

We see that both patches have been applied successfully.

Let’s check status table.

Patches MC-1 and MC-2 have applied status, and after refreshing the page, we see both issues fixed.

And now I changed my mind again and want to revert all applied patches. I can do it with command option all.

Revert. And option all.

Let’s check the status table.

Now you can see that all patches have not applied status. And let’s refresh the page. After refreshing the page, all issues again, make us troubles. Next case, it will be applying a patch that has dependency on other patch. It’s patch MC-3.

As you can see, it requires MC-2.

The reason of dependency can be modifications, the same lines of code by both patches.

Let’s apply it.

Tool tells me that patch MC-2 is required for MC-3, and asks confirmation to apply it as well. I give my confirmation, and here we go. Both patches are applied. Let’s check our page. As you can see, Issue 2 and Issue 3 were fixed. And the patch MC-3 and MC-2 changed the same line of code.

And the last case I would like to demonstrate you is a patch replacement. Imagine that Support wants to replace patch MC-3 with some improved version, MC-3 version two. For demo purpose, I’ll do it in a patch configuration directly on instance.

Let’s check status table.

Here, we can see recommendation to replace MC-3 with MC-3, version two.

And we see that MC-3 has type deprecated now. Let’s do it.

Why? MC-3, version two.

The tool asks confirmation to revert deprecated page, and applies a new one.

Let’s check status table again.

Now you see that deprecated patch, MC-3, disappeared from status table at all. So it’s not available anymore. Let’s check our page.

And we see Issue 3 was fixed by a new patch, MC-3, version two.

That shows the many features of Magento Quality Patches tool. There are some differences of usage for Cloud customers. Before applying selected quality patches, the set of Required Cloud patches is applied automatically. It shouldn’t make any trouble since all optional quality patches are compatible with Required Cloud patches. And since Cloud has read only file system, patches are applied during the deployment process by ECE tools. So, a customer needs to set the list of patches as environment variable in .magento.env.yaml file, and commit the changes. It looks like that. We open .magento.env.yaml file.

The list of desired patches here. Quality patches.

And commit, and push changes into the remote branch.

After that, the process of re-deploy will be started, and applied to all these patches on Cloud instance. We’ve just seen how to work with MQP on customer instance. Now let’s take a closer look at the internal structure and workflow. The main parts of MQP repository are: Commerce folder contains patches related to Magento Enterprise and B2B. Os folder contains patches for components distributed as open source. And patches.json file contains configuration. The main reason we need two support folders is a different license type for open source and commerce patches. Patches configuration has a json format.

Root element is a patch ID, which is the same as Jira issue number. Next, the related composer package names are specified. Each patch is linked to some composer package. Typically, it’s a base package for Magento CE, EE, or B2B, or meta package for inventory page builder, and other bundled extensions. Next, we specify composer version constraints for patch sources. It can be one version, a version range, one patch, as well as for several Magento releases. And the last element, it’s a patch title. For the same patch, title can be different depending on Magento edition. So the final patch is a composite of sources that match package versions installed on particular Magento instance. Let’s go through the process of creating and adding the first patch to the MQP repository. Imagine that we need to create a patch for issue MDVA-1 for Magenta version 2.3.5. I am pretty sure that most of you know how to create a patch. So I’ll just list basic steps. Our patch will be composite and contain CE and EE part.

To create CE part, we need to clone a repository, checkout a branch using git tag 2.3.5 Magento release, make code changes and create git-based patch. After that we should convert git-based patch to composer-based format, using m2-convert-for-composer tool. Now CE part of the patch is ready, and we need to perform the similar steps to create EE part. To add the patch to MQP repository, you should do four simple steps.

First, clone a repository, Magento Quality Patches. Second, add CE and EE part of the patch to OS and Commerce folders respectively. Third, update patches configuration file, patches.json.

And the last one, create a PR. Here we add MDVA-1 patch configuration. It contains CE and EE part. Then we create a PR to master branch and wait for builds to merge the PR. Travis CI Build includes integrity test and functional test. Integrity test validates patches configuration. Functional test uses Magento Cloud Docker to verify that patches can be applied to correspondent Magento releases, doesn’t have conflicts with other patches, and Magento can be installed option. As soon as Build becomes green, we can merge the PR. To make patch available for Magento customers, we need to release a new version of MQP composer package. Release publication process is pretty simple. It includes next steps. Create a new release on GitHub. Download release package from GitHub. Upload release package and publish it on repo.magento.com In general, that’s it. Everything should go well until one day we are faced with a patch conflict. To guarantee that any combination of patches can be applied on customer instance, we should add new patches with already resolved conflicts. Let’s go through the conflict resolving process. Imagine we need to create another patch for release 2.3.5 MDVA-2. So, visit on release branch 2.3.5. Recreate issue branch MDVA-2. Make a fix. Perform git.div and create a patch MDVA-2. Next, we add this patch to MQP configuration and create a PR to the master branch. Suddenly, Travis Build fails. What’s going on? Need to look at details. Here, we see two failed jobs with functional tests. Let’s open Travis job detail page. In a job log using search error patch or patch failed, we can quickly find the lines with patch error output. Also, all operations with patches are logged in a separate file storage, in Magento_root var/log directory. Log contains git error output and the result of patch conflict analysis. Conflict analysis identifies which particular Cloud or quality patch is causing a conflict. In our case, it’s the patch MDVA-1. So, let’s go back to MDVA-2 patch creation process and modify it. The new thing here we need to apply branch MDVA-1 to the release branch, commit changes, merge MDVA-2 branches with it, resolve a conflict and create a new MDVA-2 patch. This patch will have dependency on MDVA-1, and we need to set this dependency using require attribute in the MQP configuration. Require attribute has type array, so patch can help dependency on several patches. Now MDVA-2 patch is ready for delivery in MQP repository. And the last two features I’d like to talk about is marking patch as deprecated, and patch replacement. There may be a situation when later, it turns out that there is patch has issues. It can be some performance degradation or other problem. We can’t simply remove patch with next release, since some customers will have it installed. So, we should mark the patch as deprecated using deprecated attribute. Now, if the patch was applied on the instance, the customer will see a warning in the status table. If the patch wasn’t applied previously, it’ll be hidden for customers in a list of available patches. If we decide to replace a patch’s improved version, we can do it using attribute, replaced-with. we should set ID of the replacement. After that, customers will see recommendation to replace a patch with another one. To get more information about MQP tool, sharing your feedback and asking questions, please join the Slack channel #mqp-tool.

Thanks for watching. -