BLT 10.x brings a few major architectural changes from 9.2.x, as well as a large number of smaller enhancements. This page lists a few of the biggest changes, including any potentially breaking changes, but is by no means comprehensive: there have been over 250 commits to fix bugs or add new functionality in 10.x! For a comprehensive list of changes, see the CHANGELOG.
Note that as of this release, BLT 9.2.x will receive only security fixes for the next 6 months per the support policy in the README.
How to upgrade
First review the major changes below to ensure that you are ready to upgrade.
Then ensure that all dependencies (especially BLT, Drupal core, and Drupal modules) are already up-to-date. Specifically, you must be using BLT version 9.2.6 or greater to avoid an error during the update process. We also recommend that you have all other dependencies up to date so that you can run `composer update` without a package allowlist.
composer require acquia/blt:^10.0.0 --no-update && composer update. This should automatically run a BLT update script. Make sure to follow any instructions provided by the script (including running
composer update --lock afterwards), and review and commit any changes.
Major enhancements / potentially breaking changes
composer-merge-plugin has been removed
BLT 9.2.x used wikimedia/composer-merge-plugin to help manage BLT dependencies alongside downstream project dependencies. While this was convenient from a dependency management perspective, in practice it caused a lot of issues when Composer files would get out of sync or go missing, or when downstream projects wanted to override dependency versions.
BLT 10.x takes a simpler approach by moving any dependencies of downstream BLT projects into the template composer.json file for those projects, and retaining any direct dependencies of BLT in BLT's own composer.json. This is more intuitive for end users, less error prone, and gives BLT users more control over what dependencies are included.
The upgrade from composer-merge-plugin in 9.2.x to the new format in 10.x should be automated and seamless, but users with heavy customizations to the merge plugin should ensure that dependencies are still included as expected.
Newer supported versions of several packages
BLT now supports Drush 9.6, DrupalVM 5, Drupal 8.7, and defaults to PHP 7.2.
Pipelines users: note that Drush 9.6.2 has a critical bug that will cause Pipelines builds to fail. Use Drush 9.5 until Drush 9.6.3 is released.
BLT no longer supports PhantomJS, PHP 5.6, or the Beetbox base box for DrupalVM.
BLT 9.2.x allowed projects to define custom commands and override existing commands, but only within the scope of the current project.
BLT 10.x now allows users to package these commands as plugins and distribute them as Composer packages. These can be used to provide new functionality or override existing functionality. The long-term goal is to have a broader array of community-supported BLT features (such as specific CI system integrations) as plugins, while Acquia maintains the core BLT product.
If you defined custom commands in BLT 9.2.x, these will need to be modified slightly to work in BLT 10.
Improved multisite, ACSF, and testing support
Although many multisite and ACSF enhancements have been backported to 9.2.x as well, a few BC-breaking changes will only exist in 10.x. These may be especially useful for projects doing multisite automated testing.
You can now run Drupal tests as part of BLT's test suite out of the box.
Improve settings management
The location and contents of settings files have been revamped to allow for easier and more consistent organization, especially on multisite setups and on Acquia hosting.
Issue #3599 changed the order in which settings files are included to ensure that projects can always override BLT-provided settings in each environment. Because the order has changed slightly from 9.2.x, projects that define custom settings (i.e. in `docroot/sites/default/settings`) should ensure that they still function as expected.
In issue #3570, we removed all of the global environment status variables (such as $is_ah_env, $is_dev_env, etc...) from blt.settings.php. If you have custom settings files that relied on these variables, you should replace the variables with calls to methods on the new EnvironmentDetector class.
In issue #3537, we changed how custom settings files are included. If you maintain custom settings files in docroot/sites/settings named anything other than global.settings.php, you will need to regenerate global.settings.php from default.global.settings.php.
If you are using a server-side "secret" include file on Acquia Cloud, the location for this file has changed. See #3478 for details.
If you are using private files on Acquia Cloud, the location of this private files directory has changed. See #3483 for details.
BLT no longer supports profile-based configuration splits. If you need to use profile splits, you should try a different method as described in issue #3575.