From 5c4de3440f91bb36af4d5a667b8d38f625e99169 Mon Sep 17 00:00:00 2001 From: Cameron Eagans Date: Fri, 10 Feb 2023 16:49:07 -0700 Subject: [PATCH] Add some docs --- docs/.htaccess | 1 - docs/_index.md | 51 +++-- docs/api/_index.md | 4 + docs/api/capabilities.md | 4 + docs/api/events.md | 4 + docs/api/example-event-plugin.md | 4 + docs/api/example-resolver-plugin.md | 4 + docs/api/overview.md | 4 + docs/api/patches-lock.md | 4 + docs/getting-started/_index.md | 4 + docs/getting-started/installation.md | 14 ++ docs/getting-started/system-requirements.md | 29 +++ docs/getting-started/terminology.md | 4 + docs/introduction/_index.md | 4 - docs/introduction/getting-started.md | 95 -------- docs/introduction/installation.md | 71 ------ docs/project/_index.md | 4 + docs/project/code-of-conduct.md | 4 + docs/project/contributing.md | 4 + docs/project/security.md | 4 + docs/project/support-policy.md | 4 + docs/troubleshooting/_index.md | 4 + docs/troubleshooting/fixing-your-patch.md | 4 + docs/troubleshooting/guide.md | 4 + docs/troubleshooting/non-patchable-targets.md | 4 + docs/usage/_index.md | 4 + docs/usage/commands.md | 4 + docs/usage/configuration.md | 205 ++++++++++++++++++ docs/usage/defining-patches.md | 4 + docs/usage/workflow.md | 4 + 30 files changed, 364 insertions(+), 194 deletions(-) delete mode 100644 docs/.htaccess create mode 100644 docs/api/_index.md create mode 100644 docs/api/capabilities.md create mode 100644 docs/api/events.md create mode 100644 docs/api/example-event-plugin.md create mode 100644 docs/api/example-resolver-plugin.md create mode 100644 docs/api/overview.md create mode 100644 docs/api/patches-lock.md create mode 100644 docs/getting-started/_index.md create mode 100644 docs/getting-started/installation.md create mode 100644 docs/getting-started/system-requirements.md create mode 100644 docs/getting-started/terminology.md delete mode 100644 docs/introduction/_index.md delete mode 100644 docs/introduction/getting-started.md delete mode 100644 docs/introduction/installation.md create mode 100644 docs/project/_index.md create mode 100644 docs/project/code-of-conduct.md create mode 100644 docs/project/contributing.md create mode 100644 docs/project/security.md create mode 100644 docs/project/support-policy.md create mode 100644 docs/troubleshooting/_index.md create mode 100644 docs/troubleshooting/fixing-your-patch.md create mode 100644 docs/troubleshooting/guide.md create mode 100644 docs/troubleshooting/non-patchable-targets.md create mode 100644 docs/usage/_index.md create mode 100644 docs/usage/commands.md create mode 100644 docs/usage/configuration.md create mode 100644 docs/usage/defining-patches.md create mode 100644 docs/usage/workflow.md diff --git a/docs/.htaccess b/docs/.htaccess deleted file mode 100644 index c96b8976..00000000 --- a/docs/.htaccess +++ /dev/null @@ -1 +0,0 @@ -Redirect 301 "/composer-patches/introduction/" "/composer-patches/introduction/getting-started/" diff --git a/docs/_index.md b/docs/_index.md index 0931aa5f..c53fe9b0 100644 --- a/docs/_index.md +++ b/docs/_index.md @@ -4,29 +4,33 @@ description: A simple plugin for Composer that allows you to apply patches to yo layout: projecthome github: https://github.com/cweagans/composer-patches buttons: - - title: "View on Github" - href: https://github.com/cweagans/composer-patches - style: blue - - title: "Project updates" - href: https://www.cweagans.net/projects/composer-patches - style: blue + +- title: "View on Github" + href: https://github.com/cweagans/composer-patches + style: blue +- title: "Project updates" + href: https://www.cweagans.net/projects/composer-patches + style: blue + quicklinks: - - title: "Getting started" - icon: installation - description: "Step-by-step guides to installing the plugin and basic usage." - href: # - - title: "Usage & Configuration" - icon: plugins - description: "Advanced usage information for users with complex workflows." - href: # - - title: "Development" - icon: architecture - description: "Interact with the plugin programmatically for specialized use-cases." - href: # - - title: "Contributing" - icon: themes - description: "Contribute to development and keep the project alive and healthy." - href: # + +- title: "Installation" + icon: installation + description: "Get up-and-running with Composer Patches in your project" + href: /composer-patches/getting-started/installation +- title: "Workflow" + icon: plugins + description: "Learn how to use Composer Patches with a group of engineers." + href: /composer-patches/usage/workflow +- title: "Troubleshooting" + icon: architecture + description: "Figure out how to solve any problems that you run into." + href: /composer-patches/troubleshooting/guide +- title: "Contributing" + icon: themes + description: "Contribute to development and keep the project alive and healthy." + href: /composer-patches/project/contributing + --- {{< quicklinks >}} @@ -36,5 +40,6 @@ All documentation for the current, produciton-ready version of the plugin is in {{< /warning >}} {{< warning title="This guide is still under construction" >}} -All of the documentation for 1.x versions of the plugin was in the readme. For 2.x, I want a more developed set of documentation that gives people as much information as they need. I'm still writing here, so expect some rough edges. +All of the documentation for 1.x versions of the plugin was in the readme. For 2.x, I want a more developed set of +documentation that gives people as much information as they need. I'm still writing here, so expect some rough edges. {{< /warning >}} diff --git a/docs/api/_index.md b/docs/api/_index.md new file mode 100644 index 00000000..e44749be --- /dev/null +++ b/docs/api/_index.md @@ -0,0 +1,4 @@ +--- +title: API +weight: 40 +--- diff --git a/docs/api/capabilities.md b/docs/api/capabilities.md new file mode 100644 index 00000000..f181e24a --- /dev/null +++ b/docs/api/capabilities.md @@ -0,0 +1,4 @@ +--- +title: Capabilities +weight: 20 +--- diff --git a/docs/api/events.md b/docs/api/events.md new file mode 100644 index 00000000..8cdaec14 --- /dev/null +++ b/docs/api/events.md @@ -0,0 +1,4 @@ +--- +title: Events +weight: 30 +--- diff --git a/docs/api/example-event-plugin.md b/docs/api/example-event-plugin.md new file mode 100644 index 00000000..c8814bd2 --- /dev/null +++ b/docs/api/example-event-plugin.md @@ -0,0 +1,4 @@ +--- +title: Writing an event subscriber +weight: 70 +--- diff --git a/docs/api/example-resolver-plugin.md b/docs/api/example-resolver-plugin.md new file mode 100644 index 00000000..333098f8 --- /dev/null +++ b/docs/api/example-resolver-plugin.md @@ -0,0 +1,4 @@ +--- +title: Writing a resolver plugin +weight: 60 +--- diff --git a/docs/api/overview.md b/docs/api/overview.md new file mode 100644 index 00000000..e5d8bef1 --- /dev/null +++ b/docs/api/overview.md @@ -0,0 +1,4 @@ +--- +title: Overview +weight: 10 +--- diff --git a/docs/api/patches-lock.md b/docs/api/patches-lock.md new file mode 100644 index 00000000..66dd367a --- /dev/null +++ b/docs/api/patches-lock.md @@ -0,0 +1,4 @@ +--- +title: Patches.lock +weight: 40 +--- diff --git a/docs/getting-started/_index.md b/docs/getting-started/_index.md new file mode 100644 index 00000000..7053ec94 --- /dev/null +++ b/docs/getting-started/_index.md @@ -0,0 +1,4 @@ +--- +title: Getting Started +weight: 10 +--- diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md new file mode 100644 index 00000000..7391a5e1 --- /dev/null +++ b/docs/getting-started/installation.md @@ -0,0 +1,14 @@ +--- +title: Installation +weight: 20 +--- + +Installation is the same as any other Composer package: + +```shell +composer require cweagans/composer-patches:~2.0 +``` + +{{< warning title="2.0.0 is not released yet" >}} +This documentation is being written in advance of the release of 2.0.0. The above command will not work yet. +{{< /warning >}} diff --git a/docs/getting-started/system-requirements.md b/docs/getting-started/system-requirements.md new file mode 100644 index 00000000..f3975f36 --- /dev/null +++ b/docs/getting-started/system-requirements.md @@ -0,0 +1,29 @@ +--- +title: System Requirements +weight: 10 +--- + +Supporting every version of the software that we depend on is not feasible, so we support a limited, "modern-ish" system +configuration. + +## PHP + +We follow the list of [currently supported PHP versions](https://www.php.net/supported-versions.php) provided by the +community. Unsupported/EOL versions of PHP will not be supported under any circumstances. + +## Composer + +Composer 2.2 (LTS) is the minimum version. However, few people run such an old version of Composer and we do not +regularly test functionality with anything other than the current stable release. If you run into problems, we _will_ +ask you to try a recent version of Composer before proceeding with troubleshooting. + +## Patchers + +Most of the patchers that are supported don't change much, but there are a couple version-related items to keep in mind: + +* **General**: If you're using a particular program for applying patches, it would be great if it was a version that was + released in the last few years. As a rule of thumb, if the version of whatever software is older than what is + distributed with the current Debian "stable" release, we probably won't be able to do much with it. +* **GNU Patch**: Version 2.7 added support for most features of the `diff --git` format and is required for any patches + that rename/copy files, change permissions, or include symlinks. Future versions of Composer Patches may consider + lesser versions to be unusable. diff --git a/docs/getting-started/terminology.md b/docs/getting-started/terminology.md new file mode 100644 index 00000000..1dbf030b --- /dev/null +++ b/docs/getting-started/terminology.md @@ -0,0 +1,4 @@ +--- +title: Terminology +weight: 30 +--- diff --git a/docs/introduction/_index.md b/docs/introduction/_index.md deleted file mode 100644 index 9d07276c..00000000 --- a/docs/introduction/_index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -title: Introduction -weight: 10 ---- diff --git a/docs/introduction/getting-started.md b/docs/introduction/getting-started.md deleted file mode 100644 index c8717699..00000000 --- a/docs/introduction/getting-started.md +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: Getting Started -weight: 20 ---- - -## Quick start - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur. - -### Installing dependencies - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus. - -```shell -npm install @tailwindlabs/cache-advance -``` - -Possimus saepe veritatis sint nobis et quam eos. Architecto consequatur odit perferendis fuga eveniet possimus rerum cumque. Ea deleniti voluptatum deserunt voluptatibus ut non iste. Provident nam asperiores vel laboriosam omnis ducimus enim nesciunt quaerat. Minus tempora cupiditate est quod. - -{% callout type="warning" title="Oh no! Something bad happened!" %} -This is what a disclaimer message looks like. You might want to include inline `code` in it. Or maybe you’ll want to include a [link](/) in it. I don’t think we should get too carried away with other scenarios like lists or tables — that would be silly. -{% /callout %} - -### Configuring the library - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus. - -```js -// cache-advance.config.js -export default { - strategy: 'predictive', - engine: { - cpus: 12, - backups: ['./storage/cache.wtf'], - }, -} -``` - -Possimus saepe veritatis sint nobis et quam eos. Architecto consequatur odit perferendis fuga eveniet possimus rerum cumque. Ea deleniti voluptatum deserunt voluptatibus ut non iste. Provident nam asperiores vel laboriosam omnis ducimus enim nesciunt quaerat. Minus tempora cupiditate est quod. - -{% callout title="You should know!" %} -This is what a disclaimer message looks like. You might want to include inline `code` in it. Or maybe you’ll want to include a [link](/) in it. I don’t think we should get too carried away with other scenarios like lists or tables — that would be silly. -{% /callout %} - ---- - -## Basic usage - -Praesentium laudantium magni. Consequatur reiciendis aliquid nihil iusto ut in et. Quisquam ut et aliquid occaecati. Culpa veniam aut et voluptates amet perspiciatis. Qui exercitationem in qui. Vel qui dignissimos sit quae distinctio. - -### Your first cache - -Minima vel non iste debitis. Consequatur repudiandae et quod accusamus sit molestias consequatur aperiam. Et sequi ipsa eum voluptatibus ipsam. Et quisquam ut. - -Qui quae esse aspernatur fugit possimus. Quam sed molestiae temporibus. Eum perferendis dignissimos provident ea et. Et repudiandae quasi accusamus consequatur dolore nobis. Quia reiciendis necessitatibus a blanditiis iste quia. Ut quis et amet praesentium sapiente. - -Atque eos laudantium. Optio odit aspernatur consequuntur corporis soluta quidem sunt aut doloribus. Laudantium assumenda commodi. - -### Clearing the cache - -Vel aut velit sit dolor aut suscipit at veritatis voluptas. Laudantium tempore praesentium. Qui ut voluptatem. - -Ea est autem fugiat velit esse a alias earum. Dolore non amet soluta eos libero est. Consequatur qui aliquam qui odit eligendi ut impedit illo dignissimos. - -Ut dolore qui aut nam. Natus temporibus nisi voluptatum labore est ex error vel officia. Vero repellendus ut. Suscipit voluptate et placeat. Eius quo corporis ab et consequatur quisquam. Nihil officia facere dolorem occaecati alias deleniti deleniti in. - -### Adding middleware - -Officia nobis tempora maiores id iusto magni reprehenderit velit. Quae dolores inventore molestiae perspiciatis aut. Quis sequi officia quasi rem officiis officiis. Nesciunt ut cupiditate. Sunt aliquid explicabo enim ipsa eum recusandae. Vitae sunt eligendi et non beatae minima aut. - -Harum perferendis aut qui quibusdam tempore laboriosam voluptatum qui sed. Amet error amet totam exercitationem aut corporis accusantium dolorum. Perspiciatis aut animi et. Sed unde error ut aut rerum. - -Ut quo libero aperiam mollitia est repudiandae quaerat corrupti explicabo. Voluptas accusantium sed et doloribus voluptatem fugiat a mollitia. Numquam est magnam dolorem asperiores fugiat. Soluta et fuga amet alias temporibus quasi velit. Laudantium voluptatum perspiciatis doloribus quasi facere. Eveniet deleniti veniam et quia veritatis minus veniam perspiciatis. - ---- - -## Getting help - -Consequuntur et aut quisquam et qui consequatur eligendi. Necessitatibus dolorem sit. Excepturi cumque quibusdam soluta ullam rerum voluptatibus. Porro illo sequi consequatur nisi numquam nisi autem. Ut necessitatibus aut. Veniam ipsa voluptatem sed. - -### Submit an issue - -Inventore et aut minus ut voluptatem nihil commodi doloribus consequatur. Facilis perferendis nihil sit aut aspernatur iure ut dolores et. Aspernatur odit dignissimos. Aut qui est sint sint. - -Facere aliquam qui. Dolorem officia ipsam adipisci qui molestiae. Error voluptatem reprehenderit ex. - -Consequatur enim quia maiores aperiam et ipsum dicta. Quam ut sit facere sit quae. Eligendi veritatis aut ut veritatis iste ut adipisci illo. - -### Join the community - -Praesentium facilis iste aliquid quo quia a excepturi. Fuga reprehenderit illo sequi voluptatem voluptatem omnis. Id quia consequatur rerum consectetur eligendi et omnis. Voluptates iusto labore possimus provident praesentium id vel harum quisquam. Voluptatem provident corrupti. - -Eum et ut. Qui facilis est ipsa. Non facere quia sequi commodi autem. Dicta autem sit sequi omnis impedit. Eligendi amet dolorum magnam repudiandae in a. - -Molestiae iusto ut exercitationem dolorem unde iusto tempora atque nihil. Voluptatem velit facere laboriosam nobis ea. Consequatur rerum velit ipsum ipsam. Et qui saepe consequatur minima laborum tempore voluptatum et. Quia eveniet eaque sequi consequatur nihil eos. diff --git a/docs/introduction/installation.md b/docs/introduction/installation.md deleted file mode 100644 index d113224d..00000000 --- a/docs/introduction/installation.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -title: Installation -weight: 10 ---- - -Quasi sapiente voluptates aut minima non doloribus similique quisquam. In quo expedita ipsum nostrum corrupti incidunt. Et aut eligendi ea perferendis. - ---- - -## Quis vel iste dicta - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur. - -### Et pariatur ab quas - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus. - -```js -/** @type {import('@tailwindlabs/lorem').ipsum} */ -export default { - lorem: 'ipsum', - dolor: ['sit', 'amet', 'consectetur'], - adipiscing: { - elit: true, - }, -} -``` - -Possimus saepe veritatis sint nobis et quam eos. Architecto consequatur odit perferendis fuga eveniet possimus rerum cumque. Ea deleniti voluptatum deserunt voluptatibus ut non iste. Provident nam asperiores vel laboriosam omnis ducimus enim nesciunt quaerat. Minus tempora cupiditate est quod. - -### Natus aspernatur iste - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus. - -Voluptas beatae omnis omnis voluptas. Cum architecto ab sit ad eaque quas quia distinctio. Molestiae aperiam qui quis deleniti soluta quia qui. Dolores nostrum blanditiis libero optio id. Mollitia ad et asperiores quas saepe alias. - ---- - -## Quos porro ut molestiae - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur. - -### Voluptatem quas possimus - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus. - -Possimus saepe veritatis sint nobis et quam eos. Architecto consequatur odit perferendis fuga eveniet possimus rerum cumque. Ea deleniti voluptatum deserunt voluptatibus ut non iste. Provident nam asperiores vel laboriosam omnis ducimus enim nesciunt quaerat. Minus tempora cupiditate est quod. - -### Id vitae minima - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus. - -Voluptas beatae omnis omnis voluptas. Cum architecto ab sit ad eaque quas quia distinctio. Molestiae aperiam qui quis deleniti soluta quia qui. Dolores nostrum blanditiis libero optio id. Mollitia ad et asperiores quas saepe alias. - ---- - -## Vitae laborum maiores - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur. - -### Corporis exercitationem - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus. - -Possimus saepe veritatis sint nobis et quam eos. Architecto consequatur odit perferendis fuga eveniet possimus rerum cumque. Ea deleniti voluptatum deserunt voluptatibus ut non iste. Provident nam asperiores vel laboriosam omnis ducimus enim nesciunt quaerat. Minus tempora cupiditate est quod. - -### Reprehenderit magni - -Sit commodi iste iure molestias qui amet voluptatem sed quaerat. Nostrum aut pariatur. Sint ipsa praesentium dolor error cumque velit tenetur quaerat exercitationem. Consequatur et cum atque mollitia qui quia necessitatibus. - -Voluptas beatae omnis omnis voluptas. Cum architecto ab sit ad eaque quas quia distinctio. Molestiae aperiam qui quis deleniti soluta quia qui. Dolores nostrum blanditiis libero optio id. Mollitia ad et asperiores quas saepe alias. diff --git a/docs/project/_index.md b/docs/project/_index.md new file mode 100644 index 00000000..f81e0c66 --- /dev/null +++ b/docs/project/_index.md @@ -0,0 +1,4 @@ +--- +title: Project +weight: 50 +--- diff --git a/docs/project/code-of-conduct.md b/docs/project/code-of-conduct.md new file mode 100644 index 00000000..3b7d7171 --- /dev/null +++ b/docs/project/code-of-conduct.md @@ -0,0 +1,4 @@ +--- +title: Code of conduct +weight: 30 +--- diff --git a/docs/project/contributing.md b/docs/project/contributing.md new file mode 100644 index 00000000..e9e0d0ad --- /dev/null +++ b/docs/project/contributing.md @@ -0,0 +1,4 @@ +--- +title: Contributing +weight: 10 +--- diff --git a/docs/project/security.md b/docs/project/security.md new file mode 100644 index 00000000..407b9764 --- /dev/null +++ b/docs/project/security.md @@ -0,0 +1,4 @@ +--- +title: Security +weight: 40 +--- diff --git a/docs/project/support-policy.md b/docs/project/support-policy.md new file mode 100644 index 00000000..81cd67e2 --- /dev/null +++ b/docs/project/support-policy.md @@ -0,0 +1,4 @@ +--- +title: Support policy +weight: 20 +--- diff --git a/docs/troubleshooting/_index.md b/docs/troubleshooting/_index.md new file mode 100644 index 00000000..9420cbe9 --- /dev/null +++ b/docs/troubleshooting/_index.md @@ -0,0 +1,4 @@ +--- +title: Troubleshooting +weight: 30 +--- diff --git a/docs/troubleshooting/fixing-your-patch.md b/docs/troubleshooting/fixing-your-patch.md new file mode 100644 index 00000000..ddb390f4 --- /dev/null +++ b/docs/troubleshooting/fixing-your-patch.md @@ -0,0 +1,4 @@ +--- +title: Fixing your patch +weight: 30 +--- diff --git a/docs/troubleshooting/guide.md b/docs/troubleshooting/guide.md new file mode 100644 index 00000000..b702f60d --- /dev/null +++ b/docs/troubleshooting/guide.md @@ -0,0 +1,4 @@ +--- +title: Guide +weight: 10 +--- diff --git a/docs/troubleshooting/non-patchable-targets.md b/docs/troubleshooting/non-patchable-targets.md new file mode 100644 index 00000000..3179de30 --- /dev/null +++ b/docs/troubleshooting/non-patchable-targets.md @@ -0,0 +1,4 @@ +--- +title: Non-patchable targets +weight: 20 +--- diff --git a/docs/usage/_index.md b/docs/usage/_index.md new file mode 100644 index 00000000..58fdbc56 --- /dev/null +++ b/docs/usage/_index.md @@ -0,0 +1,4 @@ +--- +title: Usage +weight: 20 +--- diff --git a/docs/usage/commands.md b/docs/usage/commands.md new file mode 100644 index 00000000..ae234367 --- /dev/null +++ b/docs/usage/commands.md @@ -0,0 +1,4 @@ +--- +title: Commands +weight: 40 +--- diff --git a/docs/usage/configuration.md b/docs/usage/configuration.md new file mode 100644 index 00000000..d5f9a5cb --- /dev/null +++ b/docs/usage/configuration.md @@ -0,0 +1,205 @@ +--- +title: Configuration +weight: 10 +--- + +{{< lead text="The plugin ships with reasonable defaults that should work on most environments, but many behaviors are configurable." >}} + + + +## Configuration provided by Composer Patches + + + +### `patches-file` + +```json +{ + [...], + "extra": { + "composer-patches": { + "patches-file": "mypatches.json" + } + } +} +``` + +**Default value**: empty + +Patch definitions can additionally be loaded from a JSON file. This value should usually be the name of a file located alongside your `composer.json`. + +Technically, this value can be a path to a file that is nested in a deeper directory in your project. I don't recommend doing that, as it may cause some confusion if you're using local patches (all paths to local patches will still be relative to the project root where `composer.json` is located). + +--- + +### `package-depths` + +```json +{ + [...], + "extra": { + "composer-patches": { + "package-depths": { + "my/package": 3 + } + } + } +} +``` + +**Default value**: empty + +`package-depths` allows you to specify overrides for the default patch depth used for a given package. The value for each package is the value that would normally be passed to e.g. a `patch` command: `patch -p3 [...]`. + +--- + +### `default-patch-depth` + +```json +{ + [...], + "extra": { + "composer-patches": { + "default-patch-depth": 3 + } + } +} +``` + +**Default value**: `1` + +`default-patch-depth` changes the default patch depth for **every** package. The default value is usually the right choice (especially if the majority of your patches were created with `git`). + +{{< warning title="Change this value with care" >}} +You probably don't need to change this value. Instead, consider setting a package-specific depth in `package-depths` or setting a `depth` on an individual patch. +{{< /warning >}} + +--- + +### `disable-resolvers` + +```json +{ + [...], + "extra": { + "composer-patches": { + "disable-resolvers": [ + "\\cweagans\\Composer\\Resovler\\RootComposer", + "\\cweagans\\Composer\\Resovler\\PatchesFile" + ] + } + } +} +``` + +**Default value**: empty + +`disable-resolvers` allows you to disable individual patch resolvers (for instance, if you want to disallow specifying patches in your root `composer.json`, you might want to add the `\\cweagans\\Composer\\Resolver\\RootComposer` resolver to this list). If a resolver is available and _not_ specified here, it will be used for resolving patches. + +For completeness, both of the resolvers that ship with the plugin are listed above, but you should _not_ list both of them unless you don't want **any** patches to be discovered. + +After changing this value, you should re-lock and re-apply patches to your project. + +--- + +### `disable-downloaders` + +```json +{ + [...], + "extra": { + "composer-patches": { + "disable-downloaders": [ + "\\cweagans\\Composer\\Downloader\\ComposerDownloader" + ] + } + } +} +``` + +**Default value**: empty + +`disable-downloaders` allows you to disable individual patch downloaders. If a downloader is available and _not_ specified here, it may be used for downloading patches. + +{{< warning title="Change this value with care" >}} +You probably don't need to change this value unless you're building a plugin that provides an alternative download mechanism for packages. +{{< /warning >}} + +--- + +### `disable-patchers` + +```json +{ + [...], + "extra": { + "composer-patches": { + "disable-patchers": [ + "\\cweagans\\Composer\\Patcher\\BsdPatchPatcher", + "\\cweagans\\Composer\\Patcher\\GitPatcher", + "\\cweagans\\Composer\\Patcher\\GnuGPatchPatcher", + "\\cweagans\\Composer\\Patcher\\GnuPatchPatcher" + ] + } + } +} +``` + +**Default value**: empty + +`disable-patchers` allows you to disable individual patchers. If a patcher is available and _not_ specified here, it may be used to apply a patch to your project. + +For completeness, all of the patchers that ship with the plugin are listed above, but you should _not_ list all of them. If no patchers are available, the plugin will throw an exception during `composer install`. + +After changing this value, you should re-lock and re-apply patches to your project. + + +## Relevant configuration provided by Composer + +### `preferred-install` + +```json +{ + [...], + "config": { + "preferred-install": "source" + } +} +``` + +**Default value**: `"dist"` + +The relevant Composer documentation for this parameter can be found [here](https://getcomposer.org/doc/06-config.md#preferred-install). + +If you're applying patches that were generated with `git`, setting `preferred-install` to `"source"` is **highly recommended** (either by changing the setting for all packages or by setting that value on a per-package basis as shown in the Composer documentation. This will allow the `GitPatcher` to apply patches as often as possible (the `GitPatcher` won't even _attempt_ to apply a patch if the target directory isn't managed by `git`). Git is the most reliable patcher available to Composer Patches. _Not_ changing this setting will result in other patchers attempting to apply patches. Historically, these patchers have had varying degrees of success depending on a number of factors, so it's better to use the `GitPatcher` when you're able to do so. + +--- + +### `secure-http` + +```json +{ + [...], + "config": { + "secure-http": false + } +} +``` + +**Default value**: `true` + +The relevant Composer documentation for this parameter can be found [here](https://getcomposer.org/doc/06-config.md#secure-http). + +By default, Composer will block you from downloading anything from plain HTTP URLs. Setting this option will allow you to download data over plain HTTP. Generally, securing the endpoint where you are downloading patches from is a **much better** option. You can also download patches, save them locally, and distribute them with your project as an alternative. Nevertheless, if you really must download patches over plain HTTP, this is the way to do it. + +--- + +### `HTTP_PROXY` + +```shell +HTTP_PROXY=http://myproxy:1234 composer install +``` + +The relevant Composer documentation for this parameter can be found [here](https://getcomposer.org/doc/03-cli.md#http-proxy-or-http-proxy). + +If you are using Composer behind an HTTP proxy (common in corporate network environments), setting this value will cause Composer to properly use the specified proxy. If you're using the default `ComposerDownloader` for downloading patches, this setting will be respected and patches will be downloaded through the proxy as well. diff --git a/docs/usage/defining-patches.md b/docs/usage/defining-patches.md new file mode 100644 index 00000000..d089569c --- /dev/null +++ b/docs/usage/defining-patches.md @@ -0,0 +1,4 @@ +--- +title: Defining Patches +weight: 20 +--- diff --git a/docs/usage/workflow.md b/docs/usage/workflow.md new file mode 100644 index 00000000..f093ed36 --- /dev/null +++ b/docs/usage/workflow.md @@ -0,0 +1,4 @@ +--- +title: Workflow +weight: 30 +---