lightning_api 5.0.0

DO NOT upgrade to this release without reading this page first, or you may break your site!

What's changed?

Lightning API 5 provides no new features or functionality over Lightning API 4. The main difference is that Lightning API 5 removes all hard dependencies on contributed modules, so you no longer need to keep modules you aren't using.

Lightning API 5 also removes all previous database updates. This means you'll need to be fully up-to-date on Lightning API 4 before you upgrade to Lightning API 5.

Do I need to upgrade right now?

No, there's no rush. Lightning API 4 supports Drupal 9 and 10. However, only Lightning API 5 will support Drupal 11, so if you want to keep using Lightning API's functionality on Drupal 11, you'll need to upgrade at some point.

The main advantage of upgrading sooner is to remove contributed modules that Lightning API 4 requires, but that you're not using. Lightning API 4 will reach its end-of-life at the same time that Drupal 10 does.

Anything else I should know?

All of the Lightning components have released new major versions which drop hard dependencies. Because this kind of change can break your site, you must upgrade all the Lightning components at the same time. The good news is that they can all be upgraded in the same way, so you only need to do this process once, no matter which Lightning component(s) you're using.

Upgrade Instructions

You'll need Composer 2 or later, and Drush 10 or later.

There are two parts to this process: bringing the Lightning components up-to-date, then upgrading them to the next major versions.

Part 1: Get the Lightning components up to date

1. Update the Lightning components to their latest versions:

   composer update 'drupal/lightning_*' –with-all-dependencies

2. Run database updates (drush updatedb, or visit update.php).
3. At this point, you should be running Lightning API 4.10. Export config if needed, commit changes, and deploy to your dev, staging, and production environments. Be sure to run database updates on those environments too.

Part 2: Upgrade the Lightning components to the next major version

At this point, all environments should be running Lightning API 4.10.

1. Back in your local environment, clear all caches:

   drush cache:rebuild

2. Run drush update:lightning --upgrade. This will automatically move all the Lightning components' dependencies into the project's composer.json, and bump the components themselves to their next major versions. You can use the --commands-only option to leave composer.json untouched and only display the equivalent Composer commands. (This will happen automatically if composer.json isn't writable.)
3. Run composer update 'drupal/lightning_*' --with-all-dependencies.
4. Run database updates again (drush updatedb, or visit update.php).
5. Export config if needed, commit changes, and deploy again, running database updates on target environments as well.

Technical Info

This information is meant for technical users who are comfortable working directly with composer.json. If that's not you, you may cheerfully ignore this section. 🙂

What is this doing?

The goal of this upgrade path is to "transfer" dependencies from the control of the Lightning components, to the control of the site owner. So this upgrade path simply moves the dependencies of the Lightning components you have, to your project's composer.json. To minimize the chances of things breaking, the update:lightning command will try to pin the dependencies to their currently-installed versions; if that's not possible, it will use the same unpinned version constraints defined by the components.

With dependencies controlled by the site, rather than by the components, it becomes possible for the site owner to update modules independently of the Lightning components, or uninstall modules that aren't needed. This can also allow for easier upgrading to new major versions of Drupal, since sites won't need to wait for all of the Lightning components' dependencies to become compatible.

What changes should I expect to see in composer.json?

You'll see a lot of new dependencies in the require section. In fact, these things were already installed -- it's just that the Lightning components were installing them for you, rather than your site requiring them directly.

To minimize the possibility of your site breaking, all of the components' dependencies are moved into composer.json, rather than the upgrade script trying to detect which ones are actually in use. You can remove the ones you don't need.

If you have Lightning Layout installed, you'll see some patches for Panels and Panelizer listed in the extra section, along with a dependency on the cweagans/composer-patches plugin. You can remove these patches if your site doesn't use those modules. (If you don't need to patch modules at all, you can also remove the dependency on cweagans/composer-patches.)

If you have Lightning Media installed, you should also see an installer path for the enyo/dropzone package listed in the extra.installer-paths section. You'll want to be sure that the installer path matches the libraries directory in your Drupal site.