Composer-based dependency overrides

This post was migrated from an issue on

Where we're at

Lightning tries to balance two opposing requirements: Flexibility and Stability. This is especially hard right for two reasons:

  • The immaturity of the module ecosystem
  • D.O's lack of full semver support

The former means that we often need to heavily patch modules to get the stability we need. But that comes at a cost to flexibility. The latter means that module maintainers are less likely to release early and often. And, as a result, we need to add even more patches while interrelated issues languish in the queue.


Lightning has a formal process for deciding what version constraints are put on dependencies. For dependencies with no known issues that don't need to be patched, we're extremely flexible. Generally the constraint for those module would be `^8.0.0`. That allows site builders to lock to virtually any release of the module if needed or leave it untouched and automatically get updates as they become available. Sometime down the road, as our dependencies mature, we can hope that all of our dependencies will have loose constraints like that. For now, they are much more likely to have more specific constraints.

We use this flowchart to decide which constraints are put on a particular dependency's version:
Lightning Dependency Version Constraints

I think one simple way to put this is that Lightning doesn't constrain versions unless it needs to. If Lightning requires a specific version of a module, that means that that version really is needed to provide the functionality we test. Changing it will probably break something. In the specific case mentioned in the IS, the reporter is just a little ahead of Lightning. We haven't gotten around to testing and integrating that commit yet. I'd most likely accept a patch that did integrate and test it though. We move fairly quickly for a distribution - and you could patch Lightning itself if you were waiting for us to commit.


There are several workarounds - but definitely no silver bullets.

Submit a patch to Lightning itself
If you need a specific commit to a dependency of Lightning, it's likely that others could use it too. In the case outlined in the IS, an updated version of the Panels mega patch is all that's needed - given tests still pass. I'd be happy to commit a reference to an update Panels mega patch.

Create a custom patch
We do this for several modules - specifically in the panels ecosystem. See What's up with the 710k patch? for more info on why. Usually you need to re-roll a patch to make it apply to the module in the "state" that it is in. "State" means the version it started in plus any of the given patches. Most of the time, Lightning's patched dependencies end up in a state that is equal to a commit somewhere in that dependencies repo. The name of the patches we use generally include the commit hash.

Reset patches defined by dependencies (e.g. Lightning) (Not merged yet)
There is a pending PR agains the composer-patches package to add the ability to ignore specific patches from dependencies. You could use that to reset the module to a known release and then patch to your liking. This is generally the same as the first approach, but it might make creating your patch a little easier since you would be starting from a tagged release of the dependency.

Powered by Drupal Lightning