Docs updates

cweagans · Feb 14, 2024 · 68c371c · 68c371c
1 parent c19a396
commit 68c371c
Show file tree

Hide file tree

Showing 3 changed files with 33 additions and 2 deletions.
diff --git a/docs/api/patches-lock-json.md b/docs/api/patches-lock-json.md
@@ -19,4 +19,4 @@ If the [`COMPOSER`]({{< relref "../usage/configuration.md#composer" >}}) environ
 ```
 * Each patch definition will look like the [expanded format]({{< relref "../usage/defining-patches.md#expanded-format" >}}) that users can put into their `composer.json` or external patches file.
 * No _removals_ or _changes_ will be made to the patch definition object. _Additional_ keys may be created, so any JSON parsing you're doing should be tolerant of new keys.
-* The `extra` object in each patch definition may contain a number of attributes set by other projects or by the user and should be treated as free-form input.
+* The `extra` object in each patch definition may contain a number of attributes set by other projects or by the user and should be treated as free-form input. Currently, Composer Patches uses this attribute to store information about where a patch was defined (in the `provenance` key).
diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md
@@ -49,6 +49,27 @@ Technically, this value can be a path to a file that is nested in a deeper direc
 
 ---
 
+### `ignore-dependency-patches`
+
+```json
+{
+    [...],
+    "extra": {
+        "composer-patches": {
+            "ignore-dependency-patches": [
+                "some/package",
+            ]
+        }
+    }
+}
+```
+
+**Default value**: empty
+
+`ignore-dependency-patches` allows you to ignore patches defined by the listed dependencies. For instance, if your project requires `drupal/core` and `some/package`, and `some/package` defines a patch for `drupal/core`, listing `some/package` in `ignore-dependency-patches` would cause that patch to be ignored. This does _not_ affect the _target_ of those patches. For instance, listing `drupal/core` here would not cause patches _to_ `drupal/core` to be ignored.
+
+---
+
 ### `default-patch-depth`
 
 ```json
@@ -81,7 +102,8 @@ You probably don't need to change this value. Instead, consider setting a packag
         "composer-patches": {
             "disable-resolvers": [
                 "\\cweagans\\Composer\\Resolver\\RootComposer",
-                "\\cweagans\\Composer\\Resolver\\PatchesFile"
+                "\\cweagans\\Composer\\Resolver\\PatchesFile",
+                "\\cweagans\\Composer\\Resolver\\Dependencies"
             ]
         }
     }

diff --git a/docs/usage/defining-patches.md b/docs/usage/defining-patches.md
@@ -130,6 +130,15 @@ If you're defining patches in `patches.json` (or some other separate patches fil
 }
 ```
 
+### Dependencies
+
+Packages required by your project can define patches as well. They can do so by defining patches in their root `composer.json` file. Defining patches in a separate `patches.json` in a dependency is currently unsupported.
+
+{{< callout title="Patch paths are always relative to the root of your project" >}}
+Patches defined by a dependency should always use a publicly accessible URL, rather than a local file path. Composer Patches _will not_ attempt to modify file paths so that the patch file can be found within the installed location of a dependency.
+{{< /callout >}}
+
+
 ## Duplicate patches
 
 If the same patch is defined in multiple places, the first one added to the patch collection "wins". Subsequent definitions of the same patch will be ignored without emitting an error. The criteria used for determining whether two patches are the same are: