Admittedly, I'm trying to learn the best practices of using Composer. But, I think the concept of a distribution challenges a composer-based workflow and I wanted to discuss this.

I recently tried to override a dependency which was defined in the profile (Panels, to be specific). There is no new release of Panels yet for Lightning to adopt, but there is really critical functionality (the pencil icon for Panels IPE) I think is direly needed for usability.

As such, I attempted to update my composer.json file by specifying the dev release of Panels. This clearly conflicted with the version of Panels defined by Lightning (which I knew and understood). Except, I don't have a clear solution for diverging from the provided profile.

Is the use of a profile within composer.json intended to be an all or nothing sort of thing? Are there other solutions out there (besides explicit patches) for overriding the version of a module?


nerdstein created an issue. See original summary.

nerdstein’s picture

Issue summary: View changes
balsama’s picture

Status: Active » Needs review

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.


I've marked this as Needs Review for now in case anyone has anything to add. If you have concerns or more questions, feel free to move it back to Needs Work.

balsama’s picture

Status: Needs review » Closed (works as designed)

I've posted this summary on