Quickstart 2.7.0 Upgrade Notes - az-digital/az_quickstart GitHub Wiki

If this guide is confusing, or you have additional questions after reading it and following along, be sure to ask questions in the #azdigital-support Slack channel.

Preparing your server

Note: Quickstart 2 upstream users on Pantheon can ignore this section, as the upstream should take care of everything that is required.

• Database server requirements
• PHP version should be 8.1

You can also review the following documentation for Drupal requirements: https://www.drupal.org/docs/getting-started/system-requirements

Preparing your site codebase

Important: Every site that you plan on upgrading to 2.7.x should first be updated to use the latest 2.6.x version of Quickstart.

Update your Quickstart project template's (AKA scaffolding template or composer project template) composer.json file, to match the az-quickstart-scaffolding's composer.json file, with an emphasis on updating any php version requirements to 8.1.

Note: if you aren't using any custom modules, contrib modules not included in Quickstart, or custom patches, you can ignore this.

• Remove or replace modules removed from Drupal Core in version 10.

• Ensure all of the custom modules you are using are Drupal 10 compatible.

• Ensure all of the contrib modules you are using are Drupal 10 compatible.

• Ensure you aren't applying any Quickstart patches that conflict the 2.7

• If you are using the entity_browser Drupal module, for anything other than az_digital_asset_library, make sure you include it in your site specific composer.json. (it will be removed from Quickstart). Uninstalling Entity Browser could also delete your authenticated user role. See https://www.drupal.org/project/entity_browser/issues/3372108

• If your site already has any of the following modules installed prior to updating to 2.7 be sure to remove them from composer.json and/or codebase before updating your site to 2.7. The full list of Quickstart managed modules can be found in the 2.7.x branch of the Quickstart composer.json file.

  • media_entity_file_replace
  • asset_injector
  • flag

• Ensure that you don't have any patches for contrib modules that conflict with the Drupal 10 compatible versions of them after updating.

• If you are using a configuration management workflow, be sure to re-export config after making changes.

Updating custom modules to be Drupal 10 compatible.

If you have custom modules installed on your site and you would like to make sure that they don't break your composer build, try the following steps.

1. In your custom module's composer.json file, update any dependencies to a Drupal 10 compatible version.
2. In your custom module's composer.json file, allow Drupal 10

  "require": {
    "drupal/core": "^9 || ^10"
  }

3. In your custom module's .info.yml file, allow Drupal 10

core_version_requirement: ^9 || ^10

See this example of a pull request for a custom module in order to make it Drupal 10 compatible.

At this point composer will at least allow you to build the codebase with your custom module.

Updating the Quickstart version.

Note: Quickstart 2 upstream users on Pantheon can ignore this section, as the upstream should take care of everything that is required.

If your site's codebase is running Quickstart 2.6.7 or later, you should be able to run the following commands via composer in order to update Quickstart.

composer require "az-digital/az_quickstart: 2.7.0"

If that doesn't work, you should be able to update the Quickstart version by editing your composer.json file to use the 2.7.0 version of az-digital/az_quickstart.

After that is done, simply run

compser update -W

Running updates after updating the Quickstart version.

Swapping out the codebase:

Run these commands in the following order to ensure everything updates correctly

drush cache-rebuild
drush updb -y
drush config-distro-update --update-mode=1
drush -y az-core-config-add-permissions

Useful resources

• Upgrade status contrib module
  • Provides reports with information about D10 compatibility of modules in a site codebase
  • Has functionality for scanning custom modules for D10 compatibility
  • Included as a require-dev dependency in our Quickstart Scaffolding composer project template repository
• Matt Glaman's composer-drupal-lenient composer plugin
  • Provides a way to use Drupal modules that only need patches to their .info .yml files
  • Note: This plugin only works for composer update operations, not composer install (i.e. a composer.lock file must already exist) unless the plugin is installed globally

Additional gotchas

• If you are using a custom page template you will need to update it to use the region empty checks included in Quickstart 2.7.0 https://github.com/az-digital/az_quickstart/blob/main/themes/custom/az_barrio/templates/layout/page.html.twig#L203

• If you are using a custom menu block template, you will need to update it to use the content['#items'] empty check. https://github.com/az-digital/az_quickstart/pull/2500/files#diff-e5a96f60e2b415a56b5472b231ba75377f6f4d7350c49cffde2c6c1038837218R48-R52

• If you have overridden your taxonomy term view pages previously, before updating, you will see that the Quickstart update will override that, if you want your changes back, you can disable the Quickstart change

drush vdis az_taxonomy

Or disable it from within the admin UI.

Testing with a pre-release version of 2.7.0 on Pantheon before it is available in the Pantheon dashboard.

Since the Pantheon Dashboard only allows updating to the latest version of your site's upstream, Campus Web Services is opting to hold off on updating the upstream with 2.7.0 until the majority of sites are already running 2.6.8.

Some sites may want to forge ahead and get into Drupal 10 sooner, or test their sites in Quickstart 2.7.0 before it officially drops on Pantheon.

If this is you, here's how.

Clone your site's code base using terminus and git.

$(terminus connection:info <your-site-name>.dev --field="Git Command")

Change directory into the newly downloaded repo folder

cd <your-site-name

Check out a new branch for safety

git checkout -b d10-ready

Pull the upstream branch that you want to test your site on into your repo (you must check that it exists here)

Note: Now that Quickstart 2.7.0 is available in the pantheon upstream, you can pull in the master branch.

git pull -Xtheirs https://github.com/az-digital/az-quickstart-pantheon.git master --ff

Test that your site's codebase will build with composer.

If composer update gives you an error, here are some possible culprits within your site specific composer.json: Go back to the preparing your site codebase step.

1. A contrib module is not Drupal 10 compatible.
2. A custom module is not Drupal 10 compatible.
3. A patch no longer applies.
4. You have a contrib module that Quickstart now manages.

composer update -W 

If composer update works, delete the lock file and commit.

rm composer.lock
git add composer.json
git add composer.lock
git commit -m "Updating to Quickstart version 2.7.0"
git push --set-upstream d10-ready

Now you have some options. Create a multi-dev and update the site from live, or merge into master if you are sure. You can also test all of this locally with Lando if you want.

Once your code base is up to date, you can now update your database using the steps outlined in the running updates after updating the Quickstart version step.