Middlebury

Drupal 8 Updates

Revision as of 10:01, 15 November 2019 by Ian McBride (talk | contribs)

Before doing updates, you will need to follow the Drpual 8 Development Site Installation guide.

Exclusions

There are no exclusions at this time.

Versions

Composer allows us to peg modules and dependencies at specific versions. We do this to ensure that updates are not applied unless we specifically request them. These are common formats for versions of Drupal core and its modules.

Tagged Release

Core release 8.5.3 = composer require --no-update drupal/core:8.5.3

Module anchor_link release 8.x-1.6 = composer require --no-update drupal/anchor_link:1.6

Module twig_tweak 8.x-2.0 = composer require --no-update drupal/twig_tweak:2.0

Alpha / Beta / RC Releases

Module block_field 8.x-1.0-alpha5 = composer require --no-update drupal/block_field:1.0-alpha5

Module media_entity_audio 8.x-1.0-beta3 = composer require --no-update drupal/media_entity_audio:1.0-beta3

Module diff 8.x-1.0-rc1 = composer require --no-update drupal/diff:1.0-rc1

Development Releases

Generally, we want to avoid pegging to a development release, however this is sometimes necessary if we need to apply a patch which will only apply cleanly to the dev branch or if a module maintainer has committed a critical patch, but has not released a stable tagged release. Whenever we use a dev release, we should get the hash of the commit we've tested against and include it in the composer requirements. This prevents composer from downloading commits past that hash.

Module olark 8.x-1.x-dev = compooser require --no-update drupal/olark:1.x-dev#940ab50528b683c12ca6208daec06d38899b883a

Module token_language 8.x-1.x-dev = composer require --no-update drupal/token_language:1.x-dev#489c8ca30d165b6aaeba3e5dc65bd17b967a8b54

 

Adding Modules

  1. Adding module via composer involves first telling composer to add the module to composer.json while not performing other updates:

    composer require --no-update drupal/MODULE_NAME:VERSION
     
  2. Next we tell composer to rebuild the composer.lock file with any dependencies, and install the odule and its dependencies:

    composer update --with-dependencies nothing

Running "composer install" will install everything listed in the composer.lock file and not make any updates to it or the composer.json. This is useful after a "git pull" to install any new dependencies.

 

Updating Modules

  1. Go to https://www.middlebury.edu/institute/admin/reports/updates and click on Check Manually to fetch the latest version information. The settings on the Institute site are configured to check for all modules, including those disabled on the site.
  2. cd ~/private_html/institute
  3. git pull
  4. For each module:
    1. composer require --update-with-dependencies drupal/MODULE_NAME:VERSION (see the Versions section above)
    2. If you receive as error such as: "Could not apply patch! Skipping."
      1. Check the module's dev log to see if the named patch was incorporated into the new release
      2. If so, you can remove the patch from composer.json and run composer require again.
    3. Check to ensure that only the module and composer files were changed using git status.
    4. Check whether the module updates require database schema changes by running "drush8 updatedb". If they do:
      1. Create a new branch to test the module updates, based on the master branch.
        1. git checkout --track -b updates-20180601-MODULE_NAME
        2. git push -u origin updates-20180601-MODULE_NAME
        3. Follow steps 5-7 below but do not merge this into master. Update the scheduled downtime notes to reflect that you will deploy this change during the next Thursday downtime window.
    5. git add composer.*
    6. git add -A web/modules/contrib/MODULE_NAME
    7. git commit -m "MODULE_NAME: Upgraded module from OLD_VERSION to NEW_VERSION. For #NNN."
      1. "NNN" is the number of the issue in Github for updating the modules this week.
    8. Update the Weekly Updates Post with "Drupal MODULE_NAME NEW_VERSION" linking to the releases page on drupal.org.
  5. git checkout master
  6. git merge --no-ff -m "Fix #NNN updates." updates-20180601
  7. git push
  8. Follow the Drupal 8 Deployment process. Make sure to use the -c flag.

Updating Core

  1. cd ~/private_html/institute
  2. composer require --no-update drupal/core:VERSION
    (see the Versions section above)
  3. compsoer require --dev --no-update webflo/drupal-core-require-dev:VERSION
  4. composer update drupal/core webflo/drupal-core-require-dev --with-dependencies
  5. composer update nothing
  6. git add -A
  7. git commit -m "drupal: Upgraded core from OLD_VERSION to NEW_VERSION."
  8. Check whether the core update requires database schema changes:
    1. drush8 -y updatedb
  9. git push
  10. Follow the Drupal 8 Deployment process. Make sure to use the -c flag.

Troubleshooting Composer

If composer is not able to find any updates (this will often happen with alpha and beta releases), use this command to check to see if it is being blocked by dependency version requirements:

composer why drupal/MODULE_NAME

Another way to find out what's blocking things is `composer prohibits`:

$ composer prohibits drupal/core 8.7.0
webflo/drupal-core-require-dev 8.6.15 requires drupal/core (8.6.15) 
drupal/core 8.7.0 requires symfony/http-foundation (~3.4.27) 
middlebury/drupal8 dev-master does not require symfony/http-foundation (but v3.4.26 is installed) 
drupal/core 8.7.0 requires egulias/email-validator (^2.0) 
middlebury/drupal8 dev-master requires egulias/email-validator (^1.2)

You may need to explicitly tell composer to update that package:

composer update drupal/core webflo/drupal-core-require-dev symfony/http-foundation egulias/email-validator --with-dependencies

If it is still unclear why composer is running into conflicts, it is generally safe to blow away the composer cache and vendor/ directory and reinstall dependencies fresh:

rm -Rf vendor/*
composer clear-cache
<code style="font-family: monospace">composer update drupal/core webflo/drupal-core-require-dev --with-dependencies</code>