Skip to content

Quickstart 2.11.0 Upgrade Notes

Jump to bottom
Chris Green edited this page Aug 9, 2024 · 12 revisions

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.

About

Quickstart 2.11.0 ships with Drupal Core version 10.3.1. Be sure to also read the more detailed release notes for Drupal Core minor release 10.3.0 as well.

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.

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.11.x should first be updated to use the latest 2.10.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 at least 8.1, and preferably 8.3.

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

Removal of Deprecated Modules

Important: Modules deprecated as of 2.9.x have been removed from Quickstart 2.11.x and should be uninstalled on sites before upgrading to 2.11.x (unless they have been added to a site-specific composer.json file).

  • block_content_permissions

Chaos Tools (ctools) dependency removed from Quickstart 2

Quickstart no longer has a runtime dependency on the ctools module, and the module has been slated for removal. This might cause problems if other modules implicitly use ctools functionality without depending on it.

Note that for backwards compatibility, the composer definition still depends on the ctools project, but it's no longer installed on new projects and existing projects may uninstall it if they are not using it.

The composer definition is there so that existing sites do not automatically have the code removed underneath them and continue to work. This will be removed in the future in a new major version. It is recommended to either add an explicit dependency on ctools if you plan to keep using it or uninstall it.

To fully remove ctools from the project, add a replace section to the root composer.json:

"replace": {
  "drupal/ctools": "*"
}

Note that this will also skip it in case another module depends on it and the definition will need to be removed then.

Before uninstalling ctools, verify that no configuration dependencies remain:

drush config:status --filter=ctools

Views should have that dependency removed automatically when resaving them.

  • Ensure that you don't have any patches for contrib modules that conflict with the Drupal 10.3 compatible versions of them after updating.
  • If you are using a configuration management workflow, be sure to re-export config after making changes.

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.10.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.11.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.

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

drush vdis az_taxonomy

Or disable it from within the admin UI.

Testing with a pre-release version of 2.11.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.11.0 until the majority of sites are already running 2.10.7

Some sites may want to forge ahead and get into Drupal 10.3 sooner, or test their sites in Quickstart 2.11.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 d11-ready

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

Note: If the Quickstart 2.11.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.3 compatible.
  2. A custom module is not Drupal 10.3 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.11.0"
git push --set-upstream d11-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.

Clone this wiki locally