Quickstart 2.11.0 Upgrade Notes

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.

• Database server requirements
• PHP version can be one of 8.1, 8.2, 8.3

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

WebP Image Conversion

This release adds a WebP conversion step to all image styles provided by AZ Quickstart and Drupal core. A patch for Drupal core has also been included that adds a directive to the .htaccess file included with Drupal core to ensure the WebP image MIME type is supported. Sites hosted on Apache web servers may need to update their .htaccess files to take advantage of this improvement.

If you have custom image styles on your site, you can now upgrade them to include a convert to WEBP step.

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.

• Remove or replace modules removed from Drupal Core in version 10.3.
• Ensure all of the custom modules you are using are Drupal 10.3 compatible.
• Ensure all of the contrib modules you are using are Drupal 10.3 compatible.
• Ensure you aren't applying any Quickstart patches that conflict with Quickstart 2.11

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.11.0 version of az-digital/az_quickstart.

After that is done, simply run

composer 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

Additional Notes

Redundant permissions have been removed from the 'Content Administrator' role that are also available in the 'Content Editor' role. Typically users with the 'Content Administrator' role should also have the 'Content Editor' role. Quickstart roles are meant to be additive. Sites created prior to 2.11.0 will still have the redundant permissions in the 'Content Administrator' role and won't match sites created after 2.11.0 unless the role is reset manually.

Learn about managing users in Quickstart

Useful resources

• Upgrade status contrib module
  • Provides reports with information about D11 compatibility of modules in a site codebase
  • Has functionality for scanning custom modules for D11 compatibility
  • Included as a require-dev dependency in our Quickstart Scaffolding composer project template repository

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.