UPDATE.md

This file contains instructions for updating your Lightning-based Drupal site.

Lightning has a two-pronged update process. Out of the box, it provides a great deal of default configuration for your site, but once it's installed, all that configuration is "owned" by your site and Lightning cannot safely modify it without potentially changing your site's behavior or, in a worst-case scenario, causing data loss.

As it evolves, Lightning's default configuration may change. In certain limited cases, Lightning will attempt to safely update configuration that it depends on (which will usually be locked anyway to prevent you from modifying it). Otherwise, Lightning will leave your configuration alone, respecting the fact that your site owns it. So, to bring your site fully up-to-date with the latest default configuration, you must follow the appropriate set(s) of instructions in the "Configuration updates" section of this file.

Updating Lightning

Composer

If you've installed Lightning using our Composer-based project template, all you need to do is:

• cd /path/to/YOUR_PROJECT
• composer update
• Run drush updatedb && drush cache-rebuild, or visit update.php, to perform automatic database updates. You can also use Drupal Console's update:execute command.
• Perform any necessary configuration updates (see below).

Tarball

Do not use drush pm-update or drush up to update Lightning! Lightning includes specific, vetted, pre-tested versions of modules, and occasionally patches for those modules (and Drupal core). Drush's updater totally disregards all of that and may therefore break your site.

To update Lightning safely:

1. Download the latest version of Lightning from https://www.drupal.org/project/lightning and extract it.
2. Replace your profiles/lightning directory with the one included in the fresh copy of Lightning.
3. Replace your core directory with the one included in the fresh copy Lightning.
4. Visit update.php or run drush updatedb to perform any necessary database updates.
5. Perform any necessary configuration updates (see below).

Configuration updates

These instructions describe how to update your site's configuration to bring it in line with a newer version of Lightning. Lightning does not make these changes automatically, because they may change the way your site works.

However, as of version 2.1.8, Lightning provides a Drupal Console command which can perform these updates automatically, confirming each change interactively as it goes. If you intend to perform all the configuration updates documented here, this can save quite a bit of time!

Automatic configuration updates

Ensure Drupal Console is installed, then switch into the web root of your Lightning installation and run:

$ drupal update:lightning CURRENT_VERSION

...where CURRENT_VERSION is the version of Lightning you're currently using, in semantic version format (e.g., "8.x-2.24" should be "2.2.4", and "8.x-2.21-beta3" is "2.2.1-beta3").

To run all available configuration updates without any prompting, use:

$ drupal update:lightning CURRENT_VERSION --no-interaction

If you'd rather do the updates manually, follow the instructions below, starting from the version of Lightning you currently use. For example, if you are currently running Beta 1 and are trying to update to Beta 3, you will need to follow the instructions for updating from Beta 1 to Beta 2, then from Beta 2 to Beta 3, in that order.

3.0.0 to 3.0.1

There are no manual update steps for this version.

2.2.6 to 3.0.0

There are no manual update steps for this version.

Note: If your application uses any of the following modules, you will need to add them to your project's composer.json file or include them in your codebase using another method:

• Scheduled Updates
• Lighting Scheduled Updates
• Features
• Configuration Update Manager
• Media Entity
• Media Entity Document
• Media Entity Image

Note: You will likely need to update Lightning's constraint to get the 3.x branch. The following is a good starting point, but additional commands might be needed depending on your specific requirements and constraints:

composer require acquia/lightning:~3.0.0 --no-update
composer update acquia/lightning --with-dependencies

2.2.5 to 2.2.6

There are no manual update steps for this version.

2.2.4 to 2.2.5

There are no manual update steps for this version.

2.2.3 to 2.2.4

• Visit Structure > Media types. For each media type, click "Manage display" and select the "Embedded" display. Then drag the "Name" field into the "Disabled" section and press "Save".
• To migrate to Content Moderation, install the wbm2cm module and Drush (8.x or 9.x). Back up your database, then run drush wbm2cm-migrate to run the migration.
• If you previously used a sub-profile to exclude Lightning Workflow's "Schedule Publication" sub-component (its machine name is lightning_scheduled_updates), you will need to update your sub-profile's excluded dependencies to exclude lightning_scheduler instead, which replaces lightning_scheduled_updates in this release.

2.2.2 to 2.2.3

There are no manual update steps for this version.

2.2.1 to 2.2.2

There are no manual update steps for this version.

This release fixes some requirements problems with the 2.2.1 media migration. You can update directly from 2.2.0 to 2.2.2. When doing so, follow the "Special instructions for media entity migration" steps below.

2.2.0 to 2.2.1

Special instructions for Media Entity migration

This release will migrate your existing media entities to the core Media module. Prior to running the database updates, you must:

1. Ensure Composer properly downloaded and patched all dependencies.
2. Rebuild Drupal's caches.

This release changes the set of patches that are applied to drupal/core without actually updating core, which exposes this bug in the composer-patches plugin. As a result, you will likely need to run composer update twice. Specifically:

composer update acquia/lightning --with-dependencies
composer update drupal/core

Alternatively, you can delete your "/docroot/core" and "/docroot/modules" folders and your composer.lock file before running composer update. If you use BLT, the provided composer nuke command will do that for you.

Once you have confirmed that your codebase has been update properly, you must rebuild your site's caches before running the database updates.

drush cache-rebuild

If your codebase has been updated properly, you should see the following four pending database updates when you run drush updatedb:

lightning_api module : 
  8002 -   Installs the Consumers module. 

lightning_media module : 
  8018 -   Updates the media browser's argument validation. 

media_entity module : 
  8200 -   Clears the module handler's hook implementation cache. 
  8201 -   Replace Media Entity with Media. 

Configuration updates

• Visit Structure > Content types. For each moderated content type, click "Manage form display", then drag the "Publishing status" field into the "Disabled" section and press "Save".

2.1.8 to 2.2.0

There are no manual update steps for this version.

2.1.7 to 2.1.8

• Lightning now ships with support for image cropping, using the Image Widget Crop module. To use it for the Image media bundle (the default behavior in new Lightning sites), do the following:
  • Install the Image Widget Crop module.
  • Visit Structure > Media bundles. For the Image media bundle, choose "Manage form display".
  • If the Image field is enabled, set its widget type to "ImageWidget crop", and configure it like so:
    • Only "Freeform" should be selected for "Crop Type".
    • "Always expand crop area" should be checked.
    • "Show links to uploaded files" should be checked.
    • "Show Remove button" should be checked.
  • Press "Update", then "Save".
  • Go to the "Media browser" tab. If the Image field is enabled, set its widget type to "ImageWidget crop" and configure it like so:
    • Only "Freeform" should be selected for "Crop Type".
    • "Always expand crop area" should be checked.
    • "Show links to uploaded files" should NOT be checked.
    • "Show Remove button" should NOT be checked.
  • Press "Update", then "Save".
  • By default, Image Widget Crop uses a CDN-hosted copy of the Cropper JavaScript library. Lightning includes a copy of Cropper as well, which you can use instead of the CDN-hosted version if you prefer to. To use Lightning's included copy of the library, visit Configuration > Media > ImageWidgetCrop settings and make the following changes under "Cropper library settings":
    • Set "Custom Cropper library" to libraries/cropper/dist/cropper.min.js.
    • Set "Custom Cropper CSS file" to libraries/cropper/dist/cropper.min.css.
• Lightning now has support for bulk uploading media assets. To enable this feature, install the Bulk Media Upload module from the Lightning Package.
• New installs of Lightning that include the Workflow component will now place the Operations drop-button as the last column of the /admin/content view. To make this change in your existing Lightning installation, edit the content view, move the Operations field to the end of the list of fields, and save the changes.

2.1.6. to 2.1.7

• IMPORTANT! Page Manager is no longer a dependency of Lightning Layout, and it will no longer ship with Lightning as of the next release. Therefore, if you are actively using Page Manager, you must add it to your project as an explicit dependency in order to continue to using it. Otherwise, you must uninstall it before updating to the next version of Lightning, or your site may break.
• IMPORTANT! Lightning has added support for pulling front-end JavaScript libraries into your project using Composer, via Asset Packagist. This requires a few simple, one-time changes to your project's root composer.json. Note that, without these changes, some functionality in future Lightning releases will not work. The required changes, and instructions on how to make them (either manually, or automatically using a Lightning-provided script) are documented here.
• Lightning now supports exposing all Drupal entities as JSON, in the standard JSON API format. To enable this feature, install the Content API module from the Lightning package.
• If Lightning's content role functionality is available, grant all "creator" content roles the following permissions, as desired:
  • Toolbar: Use the administration toolbar
  • Quick Edit: Access in-place editing
  • Contextual Links: Use contextual links

2.1.5 to 2.1.6

This version of Lightning adds the ability to choose an image style, alt text, and other settings each time you embed an image in a WYSIWYG editor, rather that needing to rely on view modes. To enable this functionality:

1. As always, visit update.php or run drush updatedb to perform database updates.
2. Clear all caches.
3. Under Configuration > Content Authoring > Text formats and editors, configure the Rich Text filter format. Under "Filter settings", open the tab labeled "Limit allowed HTML tags and correct faulty HTML".
4. In the "Allowed HTML tags" text field, you should see a tag like <drupal-entity data-*>. Change it to <drupal-entity data-* alt title>.
5. Save the filter format.
6. Under Configuration > Content Authoring > Text editor embed buttons, edit the "Media browser" embed button.
7. Under "Allowed Entity Embed Display plugins", ensure that the "Media Image" checkbox is checked.
8. Save the embed button.
9. If you would like to allow authors to choose how embedded media should be displayed, go to Configuration > System > Lightning > Media, ensure that the box labeled "Allow users to choose how to display embedded media" is checked, then submit the form. If the box is not checked, Lightning will automatically choose a preferred display method (the recommended, default behavior).

2.1.4 to 2.1.5

There are no manual update steps for this version.

2.1.3 to 2.1.4

There are no manual update steps for this version.

Note:
There is a known issue with Metatag version 8.x-1.1 where you might need to clear your site's cache after updating. See Metatag 8.x-1.1 Release notes and this related issue.

As per our Dependency Constraint Policy, Lightning doesn't pin to a specific version of Metatag, so depending on your your setup, Metatag is likely to be updated when you update to Lightning 2.1.4. For Composer users, we recommend pinning to Metatag version 1.0.0. Alternatively, you can be prepared to clear your site's cache immediately after running update.php.

2.1.2 to 2.1.3

There are no manual update steps for this version.

2.1.1 to 2.1.2

There are no manual update steps for this version.

2.1.0 to 2.1.1

• To allow fields that use the media browser to filter to only the media types accepted by the field, do the following:
  • Edit the Browser display of the Media view.
  • Add the Bundle contextual filter, to the current display only, with the following settings:
    • When the filter value is NOT available, provide a default value:
      • Type: Entity Browser Context
      • Context key: target_bundles
      • Fallback value: all
      • Multiple values: OR
    • When the filter value IS available or a default is provided:
      • Specify validation criteria: Yes
      • Validator: Media bundle
      • Multiple arguments: One or more IDs separated by , or +
      • Action to take if filter value does not validate: Display all results for the specified field
    • Under the "More" section, "Allow multiple values" should be checked.
  • If the view has the media bundle as an exposed filter (most likely named "Media: Bundle"), edit it and set the "Yield to argument" select box to the name of the argument you just created (which will probably be "Media: Bundle"). If you don't see the "Yield to argument" select box, clear all caches and try again.
  • Save the view.

2.0.6 to 2.1.0

There are no manual update steps for this version.

2.0.5 to 2.0.6

There are no manual update steps for this version.

2.0.4 to 2.0.5

There are no manual update steps for this version.

If you previously used the lightning.extend.yml file to customize your installation and you have a need to continuously install your application (for example, in an Acquia Cloud Site Factory instance) you will need to convert your extend file into a sub-profile of Lightning. See the Lightning as a base profile documentation for more information.

2.0.3 to 2.0.4

• Edit the Scheduled update field on any content type that has it. Click *Field settings, set "Allowed number of values" to "Unlimited" and save. Then click Edit, rename the field to "Scheduled updates", and save.
• If you have the Image Browser entity browser available:
  • Go to Configuration > Content authoring > Entity browsers and edit the Image Browser entity browser.
  • Click Next.
  • Empty the "Width of the modal" and "Height of the modal" text fields.
  • Click Next, then proceed through the rest of the wizard without changing anything else. Then click Finish to save the entity browser.
• If you have Lightning Workflow installed, add the View moderation states permission to all content reviewer roles.
• If you have Lightning Workflow installed, Go to Structure > Views and edit the Content view.
  • Expand the Advanced section and under Relationships click on 'latest revision'.
  • Un-check the "Require this relationship" checkbox and click Apply (all displays).
  • Save the view.

2.0.2 to 2.0.3

• If you have the Landing Page content type installed, there are several manual update steps (to be performed in order):
  • Create a formatted text field on the Landing Page content type. You can re-use the standard node Body field for this purpose.
  • Customize the Teaser view mode of the Landing Page content type. Do not enable Panelizer for it. Add the new text field to the display.
  • Disable Panelizer for the Default view mode of the Landing Page content type, then add the new text field to the display.
• If you would like search functionality:
  • If you would like to use the Drupal database as a search backend, enable the Search API DB module. You don't need to enable this module if you'd rather use Apache Solr (or something else) as a backend.
  • Install the Lightning Search component. If you have already enabled Search API DB, Lightning Search will create a search server on top of the database backend, and use it to power the Content search index. Otherwise, you will need to create the server manually, then point the index to it.
• Grant the "Access the Content overview page" and (if available) "Use the Archive transition" permissions to all content type reviewer roles, if there are any.
• Edit the Content view, if you have it, and add the following:
  • A required relationship to Content latest revision.
  • The Forward revision(s) exist filter. For parity with a clean Lightning installation, label it "Has unpublished edit(s)".

2.0.1 to 2.0.2

• Install the Diff module.
• If you would like to use Lightning's simple contact form, install the Contact Form feature from the Lightning package. Alternatively, if you'd like to use Contact and Contact Storage's simple form building functionality but not Lightning's default configuration, simply install the Contact and Contact Storage modules.

2.0.0 to 2.0.1

There are no manual update steps for this version.

1.14 to 2.0.0

Once you have followed the instructions contained in 1.14 to update to 2.0.0, there are no further manual update steps.

1.13 to 1.14

There are no manual update steps for this version. However, Lightning 1.14 contains a script which will modify your root project's composer.json file in order to switch your project to the official Drupal.org Packagist and up date you to Lightning 2.0.0.

If you use the tarball to manage your codebase, you can update directly to the 2.x branch with no manual update steps.

1.12 to 1.13

There are no manual update steps for this version.

1.11 to 1.12

There are no manual update steps for this version.

1.10 to 1.11

There are no manual update steps for this version.

1.06 to 1.10

There are no manual update steps for this version.

If you would like to test the new Lightning Preview module and Workspace Preview System in a development environment, enable the Lightning Preview module from module listing page. Note that Lightning Preview and WPS are not yet ready for production environments.

1.05 to 1.06

There are no manual update steps for this version.

1.04 to 1.05

There are no manual update steps for this version.

1.03 to 1.04

• Go to Structure > Views and edit the Media view.
• Edit the Browser display and configure the pager.
• Change "Items to display" to 12 and press Apply.
• Repeat this configuration for the Image Browser display.
• Save the view.

1.02 to 1.03

There are no manual update steps for this version.

1.01 to 1.02

There are no manual update steps for this version.

1.00 to 1.01

There are no manual update steps for this version.

RC7 to 1.00

There are no manual update steps for this version.

RC6 to RC7

After running drush updatedb or visiting /update.php:

• Go to Structure > Content types and choose Manage Display for the Landing Page content type.
• Under "Custom Display Settings", make sure the the Full content box is checked.
• Scroll down and ensure the Panelize this view mode and Allow custom overrides of each entity boxes are checked.
• Press Save.
• Click the Full content tab.
• Scroll down and ensure that the Panelize this view mode, Allow custom overrides of each entity, and Allow panelizer default choice boxes are checked.
• Press Save.
• Click the Manage form display tab.
• Move the Panelizer field out the Disabled area. Be sure that "Panelizer" is selected as the widget type, and press Save.

Depending on what customizations you made to Landing Page prior to the update, some, all, or none of these setting might already be enabled.

RC5 to RC6

There are no manual update steps for this version. There are several database updates. So, as always, be sure to run drush updatedb or visit /update.php.

RC4 to RC5

There are no manual update steps for this version.

RC3 to RC4

• Add <br> to the Rich Text filter format's list of allowed HTML tags.
• Add the following permissions to Media Creator role:
  • Access the Media overview page
• Add the following permissions to the Media Manager role:
  • Access the Media overview page
  • Administer media bundles
• Edit the Media view. Change the Media display, and under Page Settings, set the access permission to "Access the Media overview page".

RC2 to RC3

There are no manual update steps for this version.

RC1 to RC2

There are no manual update steps for this version.

Beta 5 to RC1

There are no manual update steps for this version.

Beta 4 to Beta 5

• Scheduled updates which change several pieces of content at once were broken. The fix is a change to configuration that is owned by the site, so Lightning does not attempt to make the change automatically. To implement the fix manually:
  • Go to Configuration > Scheduled Updates Overview > Scheduled Update Types
  • Edit the Publish multiple nodes at a certain time update type
  • Under "Update Runner Settings", select Default from the "Update Runner" field
  • Select every content type listed in the "Content type" field
  • Press Save

Beta 3 to Beta 4

There are no manual update steps for this version.

Beta 2 to Beta 3

• Scheduled updates to content are broken by Lightning's content moderation functionality. Beta 3 includes a workaround out-of-the-box which is NOT applied by the update. To implement the fix manually:
  • Go to Configuration > Scheduled Updates Overview > Scheduled Update Types
  • Edit the Publish single node at certain time update type
  • Under "Update Runner Settings", select Latest Revision from the "Update Runner" field
  • Under "Advanced Runner Options", select The owner of the update. from the "Run update as" field
  • Press Save

Beta 1 to Beta 2

• Enable the view media permission for the anonymous and authenticated user roles.
• Install the Lightning Workflow module.