updating drupal’s minor or patch version - june 7-10, 2018updating drupal’s minor or patch...
TRANSCRIPT
Updating Drupal’s Minor or Patch Version
Keeping Drupal up-to-date
Amber Himes MatzTwin Cities Drupal Camp
June 2018
Amber Himes Matz Production Manager and Trainer
twitter.com/amberhimesmatz
@amberhimesmatz
In this session
Terms and assumptions
Standard update procedure
Tips for using Drush and Composer
Related issues and resources
Terminology
@amberhimesmatz
Update
Update
To update Drupal core’s minor or patch version, e.g. 8.4.0 to 8.5.4 or 8.5.2 to 8.5.4
@amberhimesmatz
Upgrade
Upgrade (see also “Migrate”)
To upgrade Drupal core from one major version to a higher one, e.g. 7.59 to 8.5.4 or 6.38 to 8.5.4
Today we’re
talking about
updating
(not upgrading)
@amberhimesmatz
Semantic versioning
Drupal 8 uses semantic versioning
Alias “semver”
Composer uses it, too!
@amberhimesmatz
Semantic Versioning
x.y.z
x = Major version
y = Minor version
z = Patch version
@amberhimesmatz
Semantic Versioning
x.y.z
x = Major: Breaking change. Not backwards compatible.
y = Minor: New feature(s), no breaking changes
z = Patch: bug fix, security patch, no breaking change
@amberhimesmatz
Semantic Versioning
x.y.z
x = Major: Breaking change. Not backwards compatible.
y = Minor: New feature(s), no breaking changes
z = Patch: bug fix, security patch, no breaking change
@amberhimesmatz
Release schedule
Drupal releases a minor update every 6 months
Patch releases occur as needed and may contain bug or security fixes
Evaluate the
release
@amberhimesmatz
release notes
Minor release? x.y.z
What new features does it have?
Patch release? x.y.z
Security release? Critical? Time-sensitive?
Bug fix?
Assumptions &
prerequisites
@amberhimesmatz
Assumptions
Drupal 8
@amberhimesmatz
Prereqs
You have:
Administer software updates permission, admin access, and file access
@amberhimesmatz
Assumptions
You know:
Command line basics and/or the ability to look up commands
(But these are mostly shortcuts.)
@amberhimesmatz
Assumptions
You know how to use:
Version control with Git
And you have a process for getting files to the ‘live’ site
@amberhimesmatz
Assumptions
Composer commands:
Replace command composer with PATH/TO/composer
See getcomposer.org/download
@amberhimesmatz
Assumptions
Your process may be different if:
Your hosting provider has proprietary tools for updating Drupal core
But it still helps to understand various processes and their pros and cons
@amberhimesmatz
The problem
You may have used Composer to install a new module with a dependency but you didn’t install Drupal with Composer and you’re wondering why this is so hard.
there are 3 parts
to a drupal site
@amberhimesmatz
3 parts of drupal
Code
Database
Files
@amberhimesmatz
Code
core and vendor directories
Scaffolding files (individual files one level above core directory or in sites)
Example files
Core
Core Dependencies (Composer)
Possibly customized
Possibly customizedCustom! Do not overwrite.
Custom! Do not overwrite.
Custom! Do not overwrite.
Drupal Code
@am
berh
imes
mat
z
@amberhimesmatz
Database
The database used to store a Drupal site’s content, configuration, state, and logging information.
@amberhimesmatz
Files
public and private files directories
Uploaded files, config, image derivatives, various caches, translations, etc.
Not under version control, but needs to be backed-up
@amberhimesmatz
Project files
Your project may have other special files and directories
Build scripts, backups, etc.
Backup
@amberhimesmatz
3 areas to Backup
Code
Database
Files
@amberhimesmatz
Backup code
Code
Should be version controlled. If it’s not, do it!
Check the site’s .gitignore to see what’s not backed up by version control
Backup custom .htaccess, robots.txt, etc.
@amberhimesmatz
drush sql-dump
Database backup with Drush
drush sql-dump > ../backups/
YYYY-MM-DD-filename.sql
@amberhimesmatz
drush sql-dump
Database backup with Drush
See options for sql-dump at drushcommands.com
@amberhimesmatz
drush sql-dump
Configure sql-dump with drush.yml
See https://github.com/drush-ops/drush/blob/master/examples/example.drush.yml
@amberhimesmatz
mysqldump
Database backup with mysqldump
mysqldump -u [username] -p
[dbname] | gzip -9 > ../
backups/YYYY-MM-DD-
filename.sql.gz
@amberhimesmatz
phpmyadmin
Database
PHPMyAdmin
Select database > Export
@amberhimesmatz
tools from host
See hosting provider’s dashboard for database backup buttons or tools
See also https://www.lullabot.com/articles/importexport-large-mysql-databases
@amberhimesmatz
Backup files
Files (public and private files)
sites directory <== do not overwrite!
settings.php!
sites/*/files
@amberhimesmatz
Backup files
Files
Drupal-friendly hosts will have dashboard tools for backing up “Files”
@amberhimesmatz
tar w/ gzip
tar
With gzip compression
tar -czvf ../backups/YYYY-MM-DD-files.tar.gz sites/
@amberhimesmatz
tar w/ bzip2
tar
With bzip2 compression
tar -cjvf ../backups/YYYY-MM-DD-sitename.tar.bz2 sites/
@amberhimesmatz
backup and migrate
Recommended module:
Backup and Migrate
https://www.drupal.org/project/backup_migrate
Standard update
procedure
@amberhimesmatz
Standard Update
Step 1. Log in as user with ‘Administer software updates’ permission.
@amberhimesmatz
Standard update
Step 2: Put your site in maintenance mode.
Administration > Configuration > Development > Maintenance mode
admin/config/development/maintenance
@amberhimesmatz
standard update
Enable this checkbox!
Do yourself a
favor and keep the
maintenance mode
page open in a tab
Step 3.
Determine if your
site was installed
with composer
@amberhimesmatz
Managed w/ Composer?
Run composer info drupal/core
Success? Your project is managed with Composer. Failure? It’s not.
@amberhimesmatz
Managed w/ Composer?
Look at composer.json in root directory.
Is drupal/core listed under ‘require’?
YES. Managed w/ Composer
NO. Not. (Even if listed under ‘replace’.)
If project is not
managed with
composer
@amberhimesmatz
Not composer-managed
Step 4: Remove old code
Should be done on local development or staging site and deployed to live site as usual.
@amberhimesmatz
Not composer-managed
Step 4: Remove old code
Remove core and vendor directories
rm -rf core vendor
rm -f *.* .*
@amberhimesmatz
not composer-managed
Step 5a: Download the update from drupal.org/project/drupal
wget https://www.drupal.org/files/
projects/drupal-x.y.z.tar.gz
@amberhimesmatz
not composer-managed
Step 5b. Extract the archive file.
tar -zxvf drupal-x.y.z.tar.gz
Warning! Do not overwrite
your modules,
themes, profiles, or
sites directories.
@amberhimesmatz
not composer-managed
Step 6. Apply new code.
Copy all files and directories except modules, themes, profiles, and sites from the update to your site.
Core
Core Dependencies (Composer)
Possibly customized
Possibly customizedCustom! Do not overwrite.
Custom! Do not overwrite.
Custom! Do not overwrite.
Drupal Code
@am
berh
imes
mat
z
If site is managed
with composer
@amberhimesmatz
Managed w/ Composer
Run composer update drupal/core --with-dependencies
replaces steps 4-6!
@amberhimesmatz
Standard update
Step 7. Check release notes for changes to default.settings.php
@amberhimesmatz
Standard update
If default.settings.php was changed:
1. Locate default.settings.php
2. Duplicate your settings.php with new name
3. Copy new default.settings.php to settings.php
4. Re-apply customizations from previous one
@amberhimesmatz
Standard update
Step 8. Reapply customizations to .htacess and robots.txt
(Because you backed up your original ones already, right?)
@amberhimesmatz
Standard update
Step 9. Upload new code (including vendor directory) to “live” environment using your regular deployment method.
@amberhimesmatz
Standard update
Step 10a: Open ‘live’ settings.php in text editor.
By default, access to update.php is blocked. In settings.php, find
update_free_access and set to TRUE
@amberhimesmatz
Standard update
Step 10b: Run database update(s)
Access example.com/update.php in a browser
Follow instructions
@amberhimesmatz
Standard Update
@amberhimesmatz
Standard Update
@amberhimesmatz
Standard update
Step 10c: Edit ‘live’ settings.php again.
Lock down update.php. Find
update_free_access and set to
FALSE
@amberhimesmatz
Standard update
Step 11. Verify site is working as expected.
Go to admin/reports/status
@amberhimesmatz
Standard Update
Step 12: Turn off maintenance mode
Go to admin/config/development/maintenance
Disable checkbox
Ta-Da!
YOu’ve updated
your drupal site!
No tears! Take a walk!
Ice cream time!
Tips for using
drush to update
@amberhimesmatz
Drush
NOTE:
For updating sites <= 8.4 use Drush 8
Drush 9 (> D8.4) assumes Composer-based methods to update core and contrib
@amberhimesmatz
Drush 8 (only)
Backup codebase, database, and files
drush archive-dump
https://drushcommands.com/drush-8x/core/archive-dump/
@amberhimesmatz
Drush
To put your site in maintenance mode:
drush sset system.maintenance_mode 1
drush cache-rebuild
Why?
Drupal core AND its
dependencies (vendor)
both need updating
Warning! Do not use
drush up
or drush pm-update!
No!Bad!
Don’t do it!
@amberhimesmatz
Drush
To update the database
drush updatedb
@amberhimesmatz
Drush
To take site off maintenance mode
drush sset system.maintenance_mode 0
drush cache-rebuild
Tips: updating a
site Installed w/
Drupal composer
template
@amberhimesmatz
Didn’t I just say this?
NOTE:
Do not attempt to use drush
pm-update to update a site that was created with Composer.
@amberhimesmatz
Composer template
Drupal Composer Template
https://github.com/drupal-composer/drupal-project
@amberhimesmatz
Composer template
Step 0: Put your site in maintenance mode.
cd web
drush sset system.maintenance_mode 1
drush cache-rebuild
cd ../
@amberhimesmatz
Composer template
Step 0: Check your composer.json for version constraints and update if needed.
“require”: { ...
“drupal/core”: “^8.5.3”,
...}
@amberhimesmatz
Composer Template
Step 1: Update core and its dependencies
composer update drupal/core
webflo/drupal-core-require-dev
symfony/* --with-dependencies
@amberhimesmatz
Composer template
Step 2: Determine if any scaffolding files have changed
git diff
@amberhimesmatz
Composer template
Step 3: Restore any customizations to .htaccess or robots.txt
@amberhimesmatz
Composer template
Consult the README of the project to verify instructions or troubleshoot.
But, understand that Composer docs might be a better place for some questions.
@amberhimesmatz
Composer Template
Gotcha!
Version constraints in composer.json only allow updates within a minor version. i.e. 8.3.7 -> 8.3.9 (not to 8.5.3).
@amberhimesmatz
Composer Template
Gotcha!
Incompatible dependencies in your composer.json
@amberhimesmatz
Composer Template
Important! Do not deploy development dependencies to your live site.
Run composer install --no-dev and commit changes to version control before deploying to production.
@amberhimesmatz
Composer template
Step 5. Update the database
drush updatedb
@amberhimesmatz
Composer template
big bullet
Huge bullet
super-important bullet
Step 6. Take site off maintenance mode
drush sset system.maintenance_mode 0
drush cache-rebuild
Related
drupal.org
Issues
@amberhimesmatz
Composer support
Proposal: Composer Support in Core Initiative
https://www.drupal.org/project/ideas/issues/2958021
@amberhimesmatz
Issues
Improve instructions to core/UPDATE.txt
https://www.drupal.org/project/drupal/issues/2867757
using composer to
manage your
drupal site
@amberhimesmatz
composerize Drupal
Comperize Drupal Composer plugin
Convert a non-Composer-managed Drupal project to a Composer-managed one!
https://github.com/grasmash/composerize-drupal
@amberhimesmatz
Drupal Console
Drupal Console’s composerize command
https://hechoendrupal.gitbooks.io/drupal-console/content/en/commands/composerize.html
@amberhimesmatz
Composerize module
Composerize Module
“Not ready for prime time.”
https://www.drupal.org/project/composerize
@amberhimesmatz
DIY Composerize
Free tutorial on Drupalize.Me
Use Composer with Your Drupal Project by Matthew Grasmick
https://drupalize.me/tutorial/use-composer-your-drupal-project
Keeping Track of
Updates
@amberhimesmatz
keeping track of updates
On your site:
Reports > Available updates > Settings
Enter email addresses to be notified daily or weekly
@amberhimesmatz
keeping track of updates
Subscribe to security announcements mailing list
Log in to drupal.org
On your account page: Edit > My newsletters tab
@amberhimesmatz
keeping track of updates
On Twitter:
Follow @drupalsecurity
@amberhimesmatz
keeping track of updates
Subscribe to RSS Feeds:
core security updateshttps://www.drupal.org/security/rss.xml
contributed project updates https://www.drupal.org/security/contrib/rss.xml
public service announcementshttps://www.drupal.org/security/psa/rss.xml
@amberhimesmatz
keeping track of updates
On Drupal Slack:
https://www.drupal.org/slack
Join #announcements channel
More resources
@amberhimesmatz
Security and maintenance
Drupal 8 User Guide
Chapter 13: Security and Maintenance
https://drupalize.me/series/user-guide/security-chapter
@amberhimesmatz
Tutorial
Update Drupal’s Minor Version
https://drupalize.me/tutorial/update-drupals-minor-version
@amberhimesmatz
Composer
Introduction to Composer for Drupal Users
Drupalize.Me tutorial series
https://drupalize.me/series/introduction-composer-drupal-users
Happy updating!