Skip to content
This repository was archived by the owner on Nov 19, 2024. It is now read-only.

Commit b618a46

Browse files
jeff-matthewsjeff-matthews
authored
KB migration: Create a patch (#5056)
* MAGEDOC-3956: Added new how to topic to install guide * MAGEDOC-3956: Moved content to existing patch topic * MAGEDOC-3956: Replaced 2.3 file with symlink * MAGEDOC-3956: Reorg topic sections * MAGEDOC-3956: Minor wordsmithing * Fixed up headers.
1 parent 0e75257 commit b618a46

File tree

2 files changed

+109
-86
lines changed

2 files changed

+109
-86
lines changed

‎guides/v2.2/comp-mgr/patching.md

Lines changed: 108 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -5,57 +5,142 @@ functional_areas:
55
- Upgrade
66
---
77

8-
This topic discusses the workflow for applying a patch to your Magento application.
8+
{:.bs-callout-warning}
9+
We strongly recommend that test all patches in a staging/development environment before deploying to production. We also strongly recommend that you back up your data before applying a patche. See [Back up and roll back the file system][].
910

10-
We strongly recommend that patches be tested in a staging/development environment before being deployed to production.
11+
## How patches work
1112

12-
## First: backup your data
13+
There are two types of patches:
1314

14-
We also strongly recommend that you back up your data before any patches are applied.
15-
To back up your data, refer to [Back up and roll back the file system][].
15+
- **Official patches**—patches that Magento publishes on the [Magento Security Center][].
16+
- **Custom patches**—unofficial patches that you can create from a git commit.
1617

17-
## Get the patch
18+
Patch (or diff) files are text files that note:
1819

19-
Magento patches can be found in the [Magento Security Center][]. Follow the instructions on the page to download the patch file, depending on your version and installation type.
20+
- The file(s) to be changed.
21+
- The line number to begin the change and the number of lines to be changed.
22+
- The new code to swap in.
2023

21-
## How patches work
24+
When the [patch][] program is run, this file is read in and the specified changes are made to the file(s).
2225

23-
Patch (or diff) files are text files that note:
26+
## Official patches
2427

25-
* The file(s) to be changed.
26-
* The line number to begin the change and the number of lines to be changed.
27-
* The new code to swap in.
28+
You can find official Magento patches in the [Magento Security Center][]. Follow the instructions on the page to download the patch file, depending on your version and installation type.
2829

29-
When the [patch][] program is run, this file is read in and the specified changes are made to the file(s).
30+
## Custom patches
31+
32+
Sometimes it takes a while for the Magento Engineering Team to include a bug fix made on GitHub in a Magento 2 Composer release. In the meantime, you can create a patch from GitHub and use the [`cweagans/composer-patches`][1] plugin to apply it to your Composer-based Magento 2 installation.
33+
34+
There are many ways to create patch files. The example below focuses on creating a patch from a known commit.
35+
36+
To create a custom patch:
37+
38+
1. Create a `patches/composer` directory in your local project.
39+
1. Identify the GitHub commit or pull request to use for the patch. This example uses the [`2d31571`][2] commit, linked to Magento 2 GitHub issue [#6474][3].
40+
1. Append the `.patch` or the `.diff` extensions to the commit URL. Use `.diff` for a smaller file size. For example: [https://github.com/magento/magento2/commit/2d31571f1bacd11aa2ec795180abf682e0e9aede.diff][4]
41+
1. Save the page as a file in the `patches/composer` directory. For example, `github-issue-6474.diff`.
42+
1. Edit the file and remove `app/code/<VENDOR>/<PACKAGE>` from all paths so that they are relative to the `vendor/<VENDOR>/<PACKAGE>` directory.
43+
44+
{:.bs-callout-info}
45+
Text editors that automatically remove trailing whitespace or add new lines can break the patch. Use a simple text editor to make these changes.
46+
47+
The following example shows the previously mentioned diff file after removing all instances of `app/code/Magento/Payment`:
48+
49+
```diff
50+
diff --git a/view/frontend/web/js/view/payment/iframe.js b/view/frontend/web/js/view/payment/iframe.js
51+
index c8a6fef58d31..7d01c195791e 100644
52+
--- a/view/frontend/web/js/view/payment/iframe.js
53+
+++ b/view/frontend/web/js/view/payment/iframe.js
54+
@@ -154,6 +154,7 @@ define(
55+
*/
56+
clearTimeout: function () {
57+
clearTimeout(this.timeoutId);
58+
this.fail();
59+
return this;
60+
},
61+
```
62+
63+
## Applying patches
3064

31-
## Using the command line to apply a patch
65+
There are two ways to apply patches:
66+
67+
- Using the command line
68+
- Using Composer
69+
70+
### Command line
3271

3372
1. Upload the local file into the `<Magento_root>` on the server using FTP, SFTP, SSH or your normal transport method.
3473
1. Login to the server as the [Magento admin user][] and verify the file is in the correct directory.
3574
1. In the command line interface, run the following commands according to the patch extension:
3675

37-
patch < patch_file_name.patch
76+
```bash
77+
patch < patch_file_name.patch
78+
```
3879

3980
The command assumes the file to be patched is located relative to the patch file.
4081

41-
{: .bs-callout-info}
42-
If the command line shows: `File to patch:`, it means it cannot locate the intended file, even if the path seems correct.
43-
In the box displayed in the command line terminal, the first line shows the file to be patched.
44-
Copy the file path and paste it into the `File to patch:` prompt and press `Enter` and the patch should complete.
82+
{: .bs-callout-info}
83+
If the command line shows: `File to patch:`, it means it cannot locate the intended file, even if the path seems correct. In the box displayed in the command line terminal, the first line shows the file to be patched. Copy the file path and paste it into the `File to patch:` prompt and press `Enter` and the patch should complete.
4584

46-
5. For the changes to be reflected, refresh the cache in the Admin under **System** > Tools > **Cache Management**.
85+
1. For the changes to be reflected, refresh the cache in the Admin under **System** > Tools > **Cache Management**.
4786

4887
Alternatively, the patch can be applied locally with the same command, then committed and pushed normally.
4988

50-
## Using Composer to install patches
89+
### Composer
90+
91+
{:.bs-callout-warning}
92+
Always perform comprehensive testing before deploying any custom patch.
93+
94+
To apply a custom patch using Composer:
95+
96+
1. Open your command line application and navigate to your project directory.
97+
1. Add the `cweagans/composer-patches` plugin to the `composer.json` file.
98+
99+
```bash
100+
composer require cweagans/composer-patches
101+
```
102+
103+
1. Edit the `composer.json` file and add the following section to specify:
104+
- **Module:** *\"magento/module-payment\"*
105+
- **Title:** *\"MAGETWO-56934: Checkout page freezes when ordering with Authorize.net with invalid credit card\"*
106+
- **Path to patch:** *\"patches/composer/github-issue-6474.diff\"*
51107

52-
It is possible to install a patch with Composer, but it takes a few more steps.
53-
Please refer to the [Magento Help Center][] for details on how to use Composer to do patch installation.
108+
For example:
109+
110+
```json
111+
"extra": {
112+
"composer-exit-on-patch-failure": true,
113+
"patches": {
114+
"magento/module-payment": {
115+
"MAGETWO-56934: Checkout page freezes when ordering with Authorize.net with invalid credit card": "patches/composer/github-issue-6474.diff"
116+
}
117+
}
118+
}
119+
```
120+
121+
If a patch affects multiple modules, you must create multiple patch files targeting multiple modules.
122+
123+
1. Apply the patch. Use the `-v` option only if you want to see debugging information.
124+
125+
```bash
126+
composer -v install
127+
```
128+
129+
1. Update the `composer.lock` file. The lock file tracks which patches have been applied to each Composer package in an object.
130+
131+
```bash
132+
composer update --lock
133+
```
54134

55135
<!-- Link Definitions -->
136+
56137
[Magento Security Center]:https://magento.com/security/patches
57138
[-p1 instead of -p0]:http://man7.org/linux/man-pages/man1/patch.1.html
58139
[Back up and roll back the file system]:https://devdocs.magento.com/guides/v2.3/install-gde/install/cli/install-cli-backup.html
59140
[patch]:https://en.wikipedia.org/wiki/Patch_(Unix)
60141
[Magento Help Center]:https://support.magento.com/hc/en-us/articles/360005484154-Create-a-patch-for-a-Magento-2-Composer-installation-from-a-GitHub-commit
61142
[Magento Admin user]:https://devdocs.magento.com/guides/v2.3/config-guide/cli/config-cli.html#config-install-cli-first
143+
[1]: https://github.com/cweagans/composer-patches/
144+
[2]: https://github.com/magento/magento2/commit/2d31571f1bacd11aa2ec795180abf682e0e9aede
145+
[3]: https://github.com/magento/magento2/issues/6474
146+
[4]: https://github.com/magento/magento2/commit/2d31571f1bacd11aa2ec795180abf682e0e9aede.diff

‎guides/v2.3/comp-mgr/patching.md

Lines changed: 0 additions & 63 deletions
This file was deleted.

‎guides/v2.3/comp-mgr/patching.md

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
../../v2.2/comp-mgr/patching.md

0 commit comments

Comments
 (0)