Maintaining Quickstart Sites - az-digital/az_quickstart GitHub Wiki

Creating a Quickstart website project with composer

Site to be hosted on Pantheon

Site to be hosted on other platforms

Updating your Quickstart website

Currently, Arizona Digital supports the two most recent minor releases of Arizona Quickstart. See RELEASES.md for details about our release support policy.

Applying updates

Applying Quickstart code updates via Pantheon upstream updates

Applying Quickstart code updates manually with composer

  • composer install will install updates and pull in dev dependencies, and also apply patches if they exist.
  • composer install --no-dev will install updates, and will remove dev dependencies, and also apply patches if they exist.
  • composer update is supposed to get the latest available based on the version constraints in your composer.json file, and also apply patches if they exist.
  • composer require "az-digital/az_quickstart:2.5.0" --update-no-dev Will pin to a specific version of Quickstart without dev dependencies. You can update your site, incrementing the version number whenever you want to update, or use version constraints with composer update --no-dev to only update to a tagged version.

Applying database updates

Once your site's codebase is up to date, it is important to run database updates and distribution updates.

Important: Always create a backup before running database updates or importing distribution updates.

Updating the database can be done via the command line:

drush updatedb

Applying distribution configuration updates

Important: Always ensure your site is set on the correct strategy for importing distribution updates. For Quickstart, it is recommended to use the merge strategy when importing distribution updates, which can be set via drush, or within the Admin UI.

It is advisable that you familiarize yourself with the functionality of the Config Distro module to get the most out of Quickstart.

Importing distribution updates can be done via the command line:

drush config-distro-update --update-mode=1

If you are updating to a version of Quickstart less than 2.7.x you will need to first make sure that your config_sync update mode is set to merge mode.

drush -y state:set config_sync.update_mode 1 --input-format=integer

Ensure your site has the latest permissions updates

Arizona Digital routinely audits permissions that ship with Arizona Quickstart, and updates the included roles when necessary, you can apply upstream permissions changes by running the following command.

drush -y az-core-config-add-permissions

Applying new major and minor releases

Quickstart major releases (X.y.z) and minor releases (x.Y.z) contain new features and can also include disruptive changes so they should be applied to existing sites with care (see documentation about different kinds of Quickstart releases for more information).

  • Check the release notes for the release to see if any extra steps are needed when upgrading.

Adding custom modules

Adding contrib modules with composer

Making changes within Drupal

Overriding the Arizona Quickstart codebase

In order to take advantage of the automated upstream updates for Quickstart, it is best to not override the az_quickstart installation profile source code, however, sometimes it has to be done.

Examples for when to do this:

  • Altering migration files
  • Front-porting a feature to a live site before it is accepted in Arizona Digital
  • You disagree with Arizona Digital on something that is hard-coded.

Disclaimer: Arizona Digital cannot provide support for overridden codebases sustainably, therefore the policy is that codebases with overrides are not supported.

The Quickstart composer configuration allows patching composer projects (which az-digital/az_quickstart is one of), here's how:

Inside your site's codebase

  1. Create a folder at the site root called "patches"
  2. In the patches folder create a folder called "composer"

Outside your site's codebase, clone a copy of az-digital/az_quickstart

Important! Once cloned, you must check out a version equal or greater than the site you would like to patch's codebase via git  For example, if your site is on Quickstart version 2.2.8, then you must check out that version or any later version 2.2.9 or 2.3.x)

  1. Alter the config
  2. Export it
  3. Overwrite the config in a Quickstart clone.
  4. Make a patch (the patch file can be pretty large, or you can make separate patches per issue)
git diff main > name-of-patch-file.diff

(replace main in the command above with the tag or branch you checked out.)

  1. Put the patch in patches/composer folder within your Pantheon site codebase.
  2. Add the patch to your site specific composer.json patches section.
"extra": {
    "patches": {
        "az-digital/az_quickstart": "patches/composer/name-of-patch-file.diff"
    }
}
  1. Run composer update.
  2. Repeat for each override.