2.0.0 todo list

[cweagans]

Composer Patches needs a 2.0.0 release. The 1.x version is too fragile to do much of anything with. Here are the remaining things on my list - if you'd like to help with any of this, it'd be greatly appreciated. Feel free to comment or email me (me at mygithubusername dot net) if you need help getting started.

Features

All of these items must include test coverage of some kind to be merged.

• Flexibility
  • Add project-specific patch depth overrides in composer.json (using the existing configuration mechanism). Then, when guessing patch depth, that configuration (if present for the package that is being patched) should be a higher priority than the depth specified in Util::getDefaultPackagePatchDepth() Done in Add project-specific depth settings #452
  • Add the ability to apply binary patches. It might make sense to make this an option on the Patch object. It might also be reasonable to always use the --binary flag where applicable. (see allow binary option and implementation #403 and Issue if trying to patch file with CRLF line ending #299 and Adds patch options support, with binary option already implemented #344)
• Debugging
  • If composer was run with --verboseor-v/-vv/-vvv, --verbose` should be passed to the patching tools too. Done in Run all patchers in verbose mode #454
• Reliability
  • Add dry-run to the patchers (similar to how GitPatcher does it) (see Fixes #178: Use dry-run to test patch to avoid leftover files/folders. #202) Done in Add --dry-run to patchers #455
• DX
  • Add a Composer and an IOInterface param to dispatched events to make them more similar to the built-in Composer events. This also allows developers to reach into the currently-running Composer instance if necessary. (see Added composer & io to dispatched events, along with on patch fails event #243)

Support

There are a lot of composer-patches users and they have varied ways of using the plugin.

All of this was done in #456

• Add Github Actions to auto-triage issue queue where possible:
  • Close stale issues/PRs
  • Automatic comments based on simple string search of issue body. e.g. Cannot apply patch = link to troubleshooting guide about how to fix your patch
• Add issue templates similar to Homebrew
  • Support -> Github discussions
  • Feature request -> Github discussions
  • "Reproducible bug" should be a Github issue form that prompts for "What happened?", "What did I expect?", "Minimum reproducible composer.json", "Full output of related composer command with -vvv flag", "Full contents of patches.lock"
• Add pull request template -- request link to related issue(s), short description of PR
• Configure security policy, private vuln reporting, code scanning alerts, secret scanning alerts in Github.
• Build a docs site?

Release announcement/promo

• Release announcement
  • What's new?
  • What changed?
  • Who should upgrade/not upgrade? (People who rely on dependency patch resolution or PHP < 8.x should not upgrade yet)
  • How do I upgrade?
  • Contributions
• Release announcement promotion. Multiple communities use composer-patches as part of their workflow. I'm already set up for publication to Drupal Planet, but I could use help with finding/gaining access to similar things for the following communities. I can provide a composer-patches specific RSS feed from my blog. I intend to post the Composer Patches 2.0.0 release announcement there and I would like to get it in front of as many users as possible.
  • Drupal - also maybe reach out directly to The Weekly Drop?
  • Yii -- maybe submit to https://yiifeed.com ?
  • Magento -- open an issue at https://github.com/OpenMage/magento-lts or maybe see about getting into https://www.openmage.org/#newsletter?
  • TYPO3 -- maybe https://typo3.org/project/news/ ?
• Alert 1.x users of availability of 2.0.0 somehow? Not sure about this one.

Documentation

• Dev docs
  • How to write a patch resolver (patches-dir feature for generating patch definitions from filesystem structure #176 or Support patches in custom modules #352 for an example use-case)
  • How to subscribe to events from composer-patches (Track last issue comment, throw warning if new comment posted #301 for an example use-case)
  • External caller: how do I see what patches are applied to which package? (Drupal Core will need this for their auto-updates functionality)
• System requirements
  • Minimum tool versions: PHP (8+), Composer (2+), various versions of patch (see Requires GNU patch 2.7 for correct behavior, but composer-patches does not warn the user about this! #326 for GNU Patch) , git (see Document minimum git version #216, Fix #174: Compatibility with older Git versions #227), etc.
• Getting Started
  • Getting started guide (see Edited composer.json, "now what"? #353)
  • Installing composer-patches
  • Defining patches (composer.json or a patches file)
  • Applying patches (composer patches-repatch if dependencies are already installed or composer install if they aren't)
• Troubleshooting
  • General information in Troubleshooting guide #198
  • You can't patch composer.json in dependencies. It doesn't work that way. (Not possible to patch composer.json of a dependency #233)
  • Metapackages can't be patched (Patch not applied if metapackage #280)
• All config options and anything related (e.g. preferred-install) and why they should/shouldn't be set (Defined base structure and all options available README #281)
• Update README.md (Update outdated examples in README.md #222, but I'd like to remove a lot of stuff from README.md and put it in a dedicated docs/ section)
• Make sure information from external articles is incorporated somehow (please credit the authors)
  • https://www.lullabot.com/articles/patch-less-composer-workflow-drupal-using-forks -- not using patches is sometimes a better option.
  • Make sure article linked on Trying to work with Drupal 9.07 #335 is included in docs (ideally the information + link to article)
  • Any other article about composer-patches that you think is worth including!
• Security. Trusting external stored patches, and best practice to mitigate this. Supply chain attacks are "quite popular" and applying/trusting external patches might also be an extra attack vector to be aware of.

Nice-to-haves

• Tests
  • Add tests for Composer Preserve Paths and fix any issues that come up (see Fix preserve paths #257)
  • Test this scenario: Requires GNU patch 2.7 for correct behavior, but composer-patches does not warn the user about this! #326 (comment) not needed if we move forward with Add new patcher: git 'init' patcher #471 and/or Only have git patchers and freeform patcher? #472
  • What happens if a configured remote patch can't be downloaded? (Should throw an exception)
  • What happens if a configured local patch can't be downloaded? (Should throw an exception)
  • Test unpatching a dependency (e.g. install with a patch, remove the patch, re-install -- everything should work)
• Allow applying patches that affect test code when tests are missing? I'm not entirely sure how this would work, but if you can figure out a way to do it, I'm extremely interested in supporting this use-case (Allow applying patches that affect test code when test code is missing #295)
• CLI commands
  • composer patches-add [args]: this command should add the patch to composer.json (or if a patches file is configured, add it to the patches file instead). Then, download the patch so that it is cached (and so that we have the sha256) and re-generate the patches lock file. Tell the user that composer patches-repatch is the next step. (alias: pa) (see CLI command for adding patches #81)
  • composer patches-import [vendor/package]: this command should find the composer.json for the specified package on disk. If there is a patches stanza in that composer.json, grab all of the patch definitions and add them to the root composer.json (or a patches file if configured). (alias: pi)
• DX
  • Dispatch a new event after patch resolution so that people can modify the resolved patches (can't use patches-ignore on patches defined in root composer.json #246). This should include the PatchCollection object that the resolvers returned + any changes to the PatchCollection class needed for somebody to be able to e.g. remove a patch from the list.
• Debugging
  • If patches are specified for a package that was not installed, alert the user (see Report missing packages where patches exist (due to typo in patch package name for example) #346)
  • If no patchers are available, link to the appropriate section of the troubleshooting guide
• Reliability
  • Add explicit support for Busybox patch (testing this might be tricky, but let me know how I can support) (see Support busybox #311)
  • Add an early-warning test suite to Github Actions that uses the latest composer snapshot (to catch issues like Composer Snapshot and 1.7.1 not compatible #399)
  • PatchCollection needs a de-duplicate method, which should be called after patch resolution (Improve feedback/message when a patch was "previously applied" #289)
• Flexibility
  • Allow applying a patch to an arbitrary path? (see Apply patch on root folder #76)
• Security
  • Address PR/MR-based patch security. There are some ideas in the comments on Patches from drupal.org merge request URLs are dangerous? #347.
• External plugins
  • Dependency patch resolution: this functionality was removed from the core plugin in main because it's way too finicky. This functionality can/should be re-built as a third party plugin. Anything in this list that was closed Feb 1 - 7 or so probably has good information about things that should be supported by such a plugin.
  • Depth guesser: patch depth guessing was removed from the core plugin. It's possible to re-implement it as a separate plugin if it is important to people.
  • A plugin that packages GNU Patch using https://justine.lol/ape.html and distributes it with a Patcher that integrates with Composer Patches. This would essentially make GNU Patch available to any user who installs this plugin on any OS/platform.
  • A plugin that provides a pure-PHP implementation of patch? (see Pure PHP implementation of Patch (avoid a dependency from the Operating System) #262)
• Documentation
  • How to fix your patch
  • Patch doesn't apply - what now?
  • Patch has bad line endings (Issue if trying to patch file with CRLF line ending #299)
  • "Quick install" commands (see Add sample commands for quick installation method #418)
• Evaluate other plugins (is there functionality that should be included either in composer-patches or in an extension?):
  • https://packagist.org/packages/nathandentzau/composer-patches-dev
  • https://packagist.org/packages/szeidler/composer-patches-cli
  • https://packagist.org/packages/vaimo/composer-patches
  • https://packagist.org/packages/netresearch/composer-patches-plugin
  • https://packagist.org/packages/elgentos/magento2-composer-quality-patches
  • https://packagist.org/packages/mlocati/composer-patcher
  • "Quick install" commands (see Add sample commands for quick installation method #418)

[cweagans]

For people following along at home, updated documentation is being staged at https://docs-staging.cweagans.net/composer-patches -- still very much under construction, but I'd appreciate any feedback.

[arderyp]

Thanks @cweagans for the awesome package and documentation! I am eagerly awaiting version 2 for the more descriptive Expanded Format for defining patch configurations. Do you anticipate v2 will have BC breakes, or we should just be able to update out configs to use the new Expanded Format and be off to the races?

I notice the Expanded Format documentation here provides a url property... but for those of us that use local patch file located in our project's file tree, can we simply put a local relative file path here the same way we can in the v1 config, or will there also be a file property that hasn't yet been added to the documentation?

thanks again :)

[steinmb]

First of, thank you, thank you, for working on this. This look fantastic.

I was missing a section about security. Trusting external stored patches, and best practice to mitigate this. Supply chain attacks are "quite popular" and applying/trusting external patches might also be an extra attack vector to be aware of.

[gitressa]

Looking good, thanks! Perhaps updating the Patching projects using Composer documentation page on Drupal.org can be added to the list? It's one of the top result in search engines looking for drupal composer patch "drupal 10".

[arderyp]

@gitressa thats what brought me here as well

[gitressa]

Thanks for the thumbs up @cweagans! Maybe add it to the list, so it gets remembered? :)