With the release of Drupal 8, core development has successfully transitioned to a regular release cycle. Drupal releases use the semantic versioning scheme to indicate whether a release is a major, minor or patch release. Since we're committed to making sure our tutorials are kept up-to-date with the latest and greatest version of Drupal we figured it would be a good idea if you knew how to keep your Drupal 8 site up-to-date with the latest point releases as well.
This tutorial will cover:
- How to determine the type of update
- The standard update procedure
- Update Drupal using Drush
- Update Drupal using Composer
This tutorial won't cover:
- How to perform a major version Drupal upgrade, for example, from Drupal 6 or 7 to Drupal 8. For that, see our Drupal 8 Migration Guide.
But first, read on to learn about the different types of updates and releases that apply to Drupal 8.
Evaluate an update release of Drupal
Drupal's version number is composed of three parts. As of this writing, version 8.2.4 is the current recommended release. The first digit, 8, indicates the major version of Drupal. The second digit is the minor version, and the third digit the patch level. New patch-level releases are available monthly, while minor versions are currently released every six months. Since we keep our tutorials up-to-date with the most recent recommended version of Drupal, you can read more about the minor version releases on our blog for the 8.0.0, 8.1.0, and 8.2.0 releases.
First and foremost it's worth noting the differences between updating and upgrading. Typically, a transition between major versions, say between Drupal 6 or 7 and Drupal 8, requires an upgrade or a migration. Unlike an update, performing an upgrade is typically no small undertaking. On our blog we walked through a simple Drupal 7 to Drupal 8 migration which might give you a sense of what could be involved in the process. But since the Drupal upgrade process is typically quite complex, we have an entire series of tutorials devoted to the topic. So if your version of Drupal is a major version behind you can start learning about the upgrade/migration process with our Drupal 8 Migration Guide.
Drupal's release cycle now dictates that new minor versions are scheduled for release about every six months. This timeline helps organizations build their update plan into their development process. Minor releases may contain new experimental modules containing features that add additional functionality but aim to maintain backward compatibility within the major version. As a result, minor version updates are usually a relatively straightforward process. We'll cover three different ways to go about a minor version update below.
Patch releases may occur monthly, but only contain security and bug fixes. As such, the impact of a patch release is genuinely quite minimal, but may be important to address in a timely fashion, especially in the case of a security release. The process for upgrading Drupal is the same for both minor and patch releases.
Once you've determined whether your update is a minor or patch update, it's a good idea to read the release notes. These will provide a high-level overview of the changes that have gone into the new version. With this knowledge in hand you're ready to begin the actual mechanics of the update process. There are several different methods of updating your site outlined below. While I would recommend being familiar with all of the methods, they accomplish the same thing.
Regardless of which method you wind up using to update your Drupal site it is always a good idea to make sure you have a fresh backup available. Functional Drupal sites are composed of three components: code, files and a database. Hopefully the codebase for your site is already stored in some type of version control system. If it isn't, our Introduction to Git series would be a good place to start. There are several techniques you could use to backup the public (and private) files directories and your site's database. First, the Backup and Migrate module can be used to create and download backups right from within your web browser.
For sites running Drupal 8.3 and lower, Drush 8 has an option for generating a complete site backup with the archive-dump command. Running
drush archive-dump from within your Drupal 8.3 and lower site will generate a SQL file with your database backup and a tarball containing your entire codebase along with the files directories.
Method #1: Standard update procedure
After creating a backup of your site, the standard update procedure involves putting your site into maintenance mode.
Put your site into maintenance mode
You can do this by visiting Administration > Configuration > Development or
admin/config/development/maintenance from within your site.
Remove old code
With your site in maintenance mode you're now ready to update the codebase to the new release. The following steps should be run on a local development or staging site and then deployed to the live site using your regular deployment process.
After changing directories to the root of your Drupal site, remove the core and vendor directories, as well as any top level files you haven't added manually.
rm -rf core vendor rm -f *.* .*
Apply new code and patches
Next move the Drupal files you've downloaded for the new release into place.
With the new Drupal code in place you can now reapply any modifications you have made to files like
composer.json or any patches you've manually applied. Our projects typically include a text file that lists these modifications or patches for quick and easy reference during an update.
Update the database
By default, access to the
update.php file in your codebase is blocked. In order to run that script from a browser to complete our site update we need to explicitly allow access. In your settings.php file locate the
update_free_access setting, change it to
TRUE and save the file. Now you can visit yoursite.com/update.php in a browser and run the database update script.
Once the update script has finished you'll either see confirmation that it has been completed successfully, or a series of logged errors where the update failed.
With the update complete don't forget to flip the
update_free_access setting back to
FALSE to prevent others from being able to access your site's update.php through a browser.
$settings['update_free_access'] = FALSE;
Ta-da! You've just updated your Drupal site.
Method #2: Update Drupal with Drush 8
Now that we've walked through the standard update procedure, let's walk through the same process using Drush 8.
We've already mentioned how the Drush 8 command,
drush archive-dump, can be used to create a backup of our codebase, files and database for Drupal sites running 8.3 and lower. We can use another Drush 8 command to put our site into maintenance mode. (Note: the
sset alias also works in Drush 9.)
drush sset system.maintenance_mode 1 drush cr
With this in place we can then update the codebase by running two commands
composer update drush pm-updatecode drupal
We will still need to make sure any of our customizations to files like .htaccess and robots.txt are recreated. With these changes in place, database updates can be performed using:
Assuming our updates complete successfully, the final step is to move the site out of maintenance mode and rebuild the registry and caches.
drush sset system.maintenance_mode 0 drush cache-rebuild
Method #3: Update Drupal with a Composer template
Another option for updating your Drupal code is to use this Drupal Composer Template to manage your codebase. The scaffolding provided by this project can be used to set up Composer templates for your Drupal projects. Once installed, this project allows you to manage, update and add dependencies (including contributed modules). Updating the Drupal codebase is accomplished by running:
composer update drupal/core webflo/drupal-core-require-dev symfony/* --with-dependencies
Important: See the project's README for further notes and steps regarding updating Drupal core using this template, as steps might change as the template undergoes development.
Since this project can help manage contributed modules as well as Drupal core, it's recommended that you avoid using it in combination with the Drush 8 command
Following the best practices of the Composer project to manage your Drupal installation will also impact what third party code you store in your repository, and how. Since that's beyond the scope of this tutorial, I'd recommend becoming thoroughly familiar with the recommendations in the project's README before deciding on this approach.
- Drupal core release cycle overview (Drupal.org)
- Drupal 8 backwards compatibility and internal API policy (Drupal.org)
- Drupal composer project (GitHub.com)