From 50f735dd61cd67bf8753f94d93f9c482e34bc633 Mon Sep 17 00:00:00 2001 From: "Eirik S. Morland" Date: Mon, 16 Feb 2026 11:29:44 +0100 Subject: [PATCH 1/3] Add a page about composer patches --- docs/introduction/composer-patches.mdx | 63 ++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 docs/introduction/composer-patches.mdx diff --git a/docs/introduction/composer-patches.mdx b/docs/introduction/composer-patches.mdx new file mode 100644 index 0000000..dc49a82 --- /dev/null +++ b/docs/introduction/composer-patches.mdx @@ -0,0 +1,63 @@ +--- +title: "Composer patches" +is_intro: true +date: 2018-03-25T10:50:02+02:00 +anchor: "composer-patches" +weight: +--- + +If your project uses the [composer-patches](https://github.com/cweagans/composer-patches) plugin by cweagans, there are a few things to be aware of when using violinist. + +## How composer-patches works + +The `cweagans/composer-patches` plugin allows you to apply patches to your composer dependencies after they are installed or updated. Patches are typically defined in your `composer.json` under the `extra` section: + +```json +{ + "extra": { + "patches": { + "vendor/package": { + "Description of the patch": "https://example.com/patch.patch" + } + } + } +} +``` + +When composer installs or updates a package that has patches defined, the plugin will download and apply those patches automatically. + +## Patches that no longer apply + +This is the most common issue when using composer-patches with violinist. When a dependency is updated, the patch you have defined may no longer apply cleanly to the new version. This happens because the code the patch targets has changed in the new version. + +When this happens, the update will fail and violinist will not be able to create a pull request for that package. This is actually the desired behavior — it prevents you from unknowingly running a version of a package without your expected patch applied. + +### What to do + +When you notice that an update is failing because of a patch that no longer applies, you have a few options: + +1. **Check if the patch is still needed.** The new version of the package may already include the fix your patch was providing. If so, remove the patch from your `composer.json` and the update should succeed on the next run. + +2. **Update the patch.** If the patch is still needed, you will need to create a new version of the patch that applies cleanly to the new version of the package. Update the patch reference in your `composer.json` and the update should succeed on the next run. + +3. **Add the package to the blocklist.** If you are not ready to deal with the patch yet, you can [block the package](/configuration/blocklist) from being updated by violinist until you are ready. + +## Patches from a local file + +If your patches are stored as local files in your repository (as opposed to remote URLs), they will work fine with violinist. Violinist checks out your repository before running composer commands, so local patch files will be available. + +```json +{ + "extra": { + "patches": { + "vendor/package": { + "My local patch": "patches/my-fix.patch" + } + } + } +} +``` + +## Patches and the lock file + +Keep in mind that composer-patches modifies packages after they are installed. The `composer.lock` file will reflect the unpatched version of the package. This is normal and expected behavior. The patches are applied on top of what the lock file specifies. From 458ed7829bd1b2025922bb956e4f22f6b99627bc Mon Sep 17 00:00:00 2001 From: Eirik Stanghelle Morland Date: Thu, 2 Jul 2026 23:13:22 +0200 Subject: [PATCH 2/3] Clarify that fixing broken patches requires manual package update too (#116) The "What to do" section previously listed removing/updating the patch as alternative options. In practice both editing the patches section in composer.json and manually running composer update (to actually apply the fix and update composer.lock) are required, since violinist can't do either step automatically. Claude-Session: https://claude.ai/code/session_013eaSzEA2f12Ps2Bz1F4mq4 Co-authored-by: Claude --- docs/introduction/composer-patches.mdx | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/introduction/composer-patches.mdx b/docs/introduction/composer-patches.mdx index dc49a82..329391e 100644 --- a/docs/introduction/composer-patches.mdx +++ b/docs/introduction/composer-patches.mdx @@ -34,13 +34,15 @@ When this happens, the update will fail and violinist will not be able to create ### What to do -When you notice that an update is failing because of a patch that no longer applies, you have a few options: +When you notice that an update is failing because of a patch that no longer applies, fixing it requires two steps, both of which you have to do yourself — violinist cannot do either one automatically: -1. **Check if the patch is still needed.** The new version of the package may already include the fix your patch was providing. If so, remove the patch from your `composer.json` and the update should succeed on the next run. +1. **Edit the patches section.** In your `composer.json`, either remove the patch entry if the new version of the package already includes the fix it was providing, or update the patch reference to a version of the patch that applies cleanly to the new version. -2. **Update the patch.** If the patch is still needed, you will need to create a new version of the patch that applies cleanly to the new version of the package. Update the patch reference in your `composer.json` and the update should succeed on the next run. +2. **Update the package manually.** Editing `composer.json` alone isn't enough — you also need to run `composer update vendor/package` yourself (locally or in CI) so the package is actually updated and the patch is applied. Commit the resulting `composer.json` and `composer.lock` together. -3. **Add the package to the blocklist.** If you are not ready to deal with the patch yet, you can [block the package](/configuration/blocklist) from being updated by violinist until you are ready. +Once both changes are committed, violinist will be able to pick up updates for that package again. + +If you are not ready to deal with the patch yet, you can instead [block the package](/configuration/blocklist) from being updated by violinist until you are. ## Patches from a local file From b0b5ab9c0bc8412fb2c1791e0ba9177950dc25b6 Mon Sep 17 00:00:00 2001 From: Eirik Stanghelle Morland Date: Thu, 2 Jul 2026 23:14:08 +0200 Subject: [PATCH 3/3] Update composer-patches.mdx --- docs/introduction/composer-patches.mdx | 20 -------------------- 1 file changed, 20 deletions(-) diff --git a/docs/introduction/composer-patches.mdx b/docs/introduction/composer-patches.mdx index 329391e..2abd0c7 100644 --- a/docs/introduction/composer-patches.mdx +++ b/docs/introduction/composer-patches.mdx @@ -43,23 +43,3 @@ When you notice that an update is failing because of a patch that no longer appl Once both changes are committed, violinist will be able to pick up updates for that package again. If you are not ready to deal with the patch yet, you can instead [block the package](/configuration/blocklist) from being updated by violinist until you are. - -## Patches from a local file - -If your patches are stored as local files in your repository (as opposed to remote URLs), they will work fine with violinist. Violinist checks out your repository before running composer commands, so local patch files will be available. - -```json -{ - "extra": { - "patches": { - "vendor/package": { - "My local patch": "patches/my-fix.patch" - } - } - } -} -``` - -## Patches and the lock file - -Keep in mind that composer-patches modifies packages after they are installed. The `composer.lock` file will reflect the unpatched version of the package. This is normal and expected behavior. The patches are applied on top of what the lock file specifies.