Upgrading a BLT and Lightning build from Drupal 8.5.x to Drupal 8.6.x

Pipelines contains a Drupal Security upgrade check, that will alert you when there is a security update for Drupal core.  

Be advised that if you are using Lightning, the warning message will generally give you a notice about Drupal core, but Lightning is a distribution that contains Drupal Core.  Even though the message says “update Drupal” - you should really update Lightning.

This process is a bit more complicated when you use Acquia BLT, but when your site is ready for the final upgrade, BLT handles the composer update of Lightning (and Drupal).

 

Update Composer

We strongly advise that you use composer to properly manage lightning and Drupal dependencies, and it’s a good idea to make sure that Composer is up to date.

• First, update composer  to the latest version with:

composer self-update

 

Prepare for the BLT Update

• Lock BLT to your current version, before upgrading Lightning, so that you can bring Lightning (which includes Drupal Core) and contributed modules up to date:

composer require acquia/blt:8.9.x

Note: Use your code's current version number instead of blt:8.9.x, and double-check the BLT release support status grid https://github.com/acquia/blt#user-content-release-support-status for additional detail about version number compatibility.

• Update your codebase to Lightning  2.2.8:

composer require acquia/lightning:2.2.8 --no-update
composer update acquia/lightning --with-all-dependencies

 

• Generate a list of other contributed modules that need an update.

composer outdated 'drupal/*'

See https://www.drupal.org/docs/8/update/update-modules

 

• Use composer to update other contributed modules to the latest version.

composer update drupal/modulename --with-dependencies

If there are errors, you can get more information to find and resolve and problems with

composer why

 

• Rebuild Drupal's cache and run database updates:

drush cr
drush updatedb

You may have to rebuild cache again with drush cr

 

• Cleanup cruft from the Media migration:

drush pm-uninstall entity media_entity

 

* Then make sure you perform any additional steps outlined in https://github.com/acquia/lightning/blob/8.x-3.x/UPDATE.md

 

Believe it or not, all of this was just preparation for the BLT upgrade steps

Update Acquia BLT to the latest 9.1.x branch

• First - unlock the version of BLT!   - the simplest way to do it, is simply to open your composer.json file to edit the line where you set composer require acquia/blt:8.9.x  and change the version number in that line.

Check the version compatibility of the BLT version with Drupal table of the BLT release status https://github.com/acquia/blt#user-content-release-support-status

 

• To update to the latest version of BLT that is compatible with your existing dependencies, run the following command:

composer update acquia/blt --with-all-dependencies

This command uses composer to update all of your dependencies (in accordance with the version constraints in your composer.json file ) and permit the latest version of BLT to be installed.  

(Keep an eye on https://github.com/acquia/blt/releases to see if there are any BLT manual upgrade steps.)

 

• Update BLT to 9.2.x latest version. This should fetch Lightning 3.2.x (which includes  Drupal 8.6.x ) as dependencies

First - unlock the version of BLT, again. The simplest way to do it, is simply to open your composer.json file to edit the line where you set composer require acquia/blt:9.1.x  and change the version number in that line.

 

• Run any Lightning manual update steps (outlined  in https://github.com/acquia/lightning/blob/8.x-3.x/UPDATE.md )
• Run any database updates, use drush cache rebuild (cr) before hand to help flush caches which makes a smaller, more svelte database to run updates against.

drush cr
drush updatedb
drush cr

• Run any Lightning configuration updates.

drush cache:rebuild
drush update:lightning

• Export the new configuration.

drush config:export

 

• Merge into develop branch and deploy into dev environment, test, proceed further together with deployment steps

 

• Review and commit changes to your project files.

 

Note: Blt has an internal “schema” that should be updated automatically during composer update. It converts a lot of files and blt *.yml files to a new notation. Must be ensured these schema updates are really applied and revisited afterwards, as if composer fails, they may not be applied.

 

• Note: if using your site is multisite, and using config_split:

 Expect to revisit and/or patch blt’s settings/config.settings.php file

By default it hardcodes expected AH (Acquia Hosting) environments and splits, and these may not fit your applications’ structure or use-cases, and it’s not possible to override this code easily in blt.yml file

Another Warning: The specific Drupal update Drupal 8.5 to  8.6 will also require updating drush from drush 8 to drush 9.

Drush 9 is a complete rewrite of drush from the ground up (see https://www.drush.org/ for additional detail).  Some of the contributed modules do not yet have commands refactored for drush 9, and there are some syntax command differences between drush 8 and drush 9 commands.   See https://drushcommands.com/ to get an idea of what the differences.

 

Your web application, whether it’s running locally, or on Acquia Cloud will preferentially use the version of drush installed with your project in the vendor directory.  This application level (or vendor directory level), drush will automatically override any drush aliases on Acquia Cloud - unless you use drush launcher or specify another version. This is new behavior for drush 8, and above, and it’s a little surprising to developers that are used to drush’s previous behavior. You can check which drush is being used by your application by using: 

drush status

If it’s a multisite, use the -l or --uri=flag to specify the site, or run the drush status (sometimes shortened to drush st) from the folder with the applications’ settings e.g. docroot/sites/default)

 

When you are using drush9 locally with Acquia, add some additional syntax outlined in https://github.com/acquia/blt/issues/2641 to help your local drush 9 instance connect more smoothly by using the  drush9 alias on Acquia Cloud.

dev:  
  root: /var/www/html/mysite/docroot  

  paths:    
    drush-script: drush9 

 

Note Drush 9 Aliases: the Drush Alias files that you can download for Acquia are compatible with drush 8, they will need to be converted to support drush 9.  

Use drush site:alias-convert to convert your existing aliases see https://support.acquia.com/hc/en-us/articles/360009815514-Help-my-drush-aliases-don-t-work-with-Drush-9- for more detail.