Chris@0: INTRODUCTION
Chris@0: ------------
Chris@0: This document describes how to update your Drupal site between 8.x.x minor and
Chris@0: patch versions; for example, from 8.1.2 to 8.1.3, or from 8.3.5 to 8.4.0.
Chris@0: 
Chris@0: To upgrade from a previous major version (for example, Drupal 6 or 7), the
Chris@0: process involves importing site configuration and content from your old site
Chris@0: into a new Drupal 8 site. The tools and process are currently experimental,
Chris@0: rather than being fully supported, so be sure to test in a development
Chris@0: environment. You will need to use the core Migrate Drupal UI module which
Chris@0: provides a user interface for the Migrate and Migrate Drupal modules included
Chris@0: in core. See https://www.drupal.org/upgrade/migrate for details, and
Chris@0: https://www.drupal.org/node/2167633 for known issues.
Chris@0: 
Chris@0: First steps and definitions:
Chris@0: 
Chris@0:   * If you are upgrading to Drupal version x.y.z, then x is known as the major
Chris@0:     version number, y is known as the minor version number, and z is known as
Chris@0:     the patch version number. The download file will be named
Chris@0:     drupal-x.y.z.tar.gz (or drupal-x.y.z.zip). Previous Drupal versions used
Chris@0:     only x.y (MAJOR.MINOR) to designate their versions.
Chris@0: 
Chris@0:   * All directories mentioned in this document are relative to the directory of
Chris@0:     your Drupal installation.
Chris@0: 
Chris@0:   * Make a full backup of all files, directories, and your database(s) before
Chris@0:     starting, and save it outside your Drupal installation directory.
Chris@0:     Instructions may be found at
Chris@0:     https://www.drupal.org/upgrade/backing-up-the-db
Chris@0: 
Chris@0:   * It is wise to try an update or upgrade on a test copy of your site before
Chris@0:     applying it to your live site. Even minor updates can cause your site's
Chris@0:     behavior to change.
Chris@0: 
Chris@0:   * Each new release of Drupal has release notes, which explain the changes made
Chris@0:     since the previous version and any special instructions needed to update or
Chris@0:     upgrade to the new version. You can find a link to the release notes for the
Chris@0:     version you are upgrading or updating to on the Drupal project page
Chris@0:     (https://www.drupal.org/project/drupal).
Chris@0: 
Chris@0: UPDATE PROBLEMS
Chris@0: ----------------
Chris@0: If you encounter errors during this process,
Chris@0: 
Chris@0:   * Note any error messages you see.
Chris@0: 
Chris@0:   * Restore your site to its previous state, using the file and database backups
Chris@0:     you created before you started the update process. Do not attempt to do
Chris@0:     further updates on a site that had update problems.
Chris@0: 
Chris@0:   * Consult one of the support options listed on https://www.drupal.org/support
Chris@0: 
Chris@0: More in-depth information on updating and upgrading can be found at
Chris@0: https://www.drupal.org/upgrade
Chris@0: 
Chris@0: MINOR AND PATCH VERSION UPDATES
Chris@0: -------------------------------
Chris@0: To update from one 8.x.x version of Drupal to any later 8.x.x version, after
Chris@0: following the instructions in the INTRODUCTION section at the top of this file:
Chris@0: 
Chris@0: 1. Log in as a user with the permission "Administer software updates".
Chris@0: 
Chris@0: 2. Go to Administration > Configuration > Development > Maintenance mode.
Chris@0:    Enable the "Put site into maintenance mode" checkbox and save the
Chris@0:    configuration.
Chris@0: 
Chris@17: 3. Determine if your project is managed by Composer.
Chris@0: 
Chris@17:    On a typical Unix/Linux command line, this can be determined by running the
Chris@17:    following command (replace /PATH/TO/composer with the appropriate location
Chris@17:    for your system):
Chris@0: 
Chris@17:      /PATH/TO/composer info drupal/core
Chris@17: 
Chris@17:    If this is successful, your project is managed by Composer.
Chris@17: 
Chris@17:    If you don't have Composer installed or access to the command line, you can
Chris@17:    check the contents of composer.json. If "drupal/core" is present in the
Chris@17:    "require" section of your composer.json file, then the project is managed by
Chris@17:    Composer.
Chris@17: 
Chris@17:    If the project is not managed by Composer, follow the steps under "UPDATING
Chris@17:    CODE WITHOUT COMPOSER", otherwise go to "UPDATING CODE WITH COMPOSER".
Chris@17: 
Chris@17: UPDATING CODE WITH COMPOSER
Chris@17: ---------------------------
Chris@17: 1. On a typical Unix/Linux command line, run the following command from the root
Chris@17:    directory (replace /PATH/TO/composer with the appropriate location for your
Chris@17:    system):
Chris@17: 
Chris@17:      /PATH/TO/composer update
Chris@17: 
Chris@17:    Note, if Composer is not installed you will need to install it in order to
Chris@17:    update Drupal.
Chris@17: 
Chris@17:    Note, if you want to only update drupal/core the following command will
Chris@17:    probably work:
Chris@17: 
Chris@17:      /PATH/TO/composer update drupal/core symfony/* --with-all-dependencies
Chris@17: 
Chris@17: 2. Check the release notes for the updated version of Drupal to find out if
Chris@17:    there is a change to default.settings.php.
Chris@17: 
Chris@17:    You can find the release notes for your version at
Chris@17:    https://www.drupal.org/project/drupal. At bottom of the project page under
Chris@17:    "Downloads" use the link for your version of Drupal to view the release
Chris@17:    notes. If your version is not listed, use the 'View all releases' link. From
Chris@17:    this page you can scroll down or use the filter to find your version and its
Chris@17:    release notes.
Chris@17: 
Chris@17:    If there is a change to default.settings.php, follow these steps:
Chris@0: 
Chris@0:    - Locate your settings.php file in the /sites/* directory. (Typically
Chris@0:      sites/default.)
Chris@0: 
Chris@0:    - Make a backup copy of your settings.php file, with a different file name.
Chris@0: 
Chris@0:    - Make a copy of the new default.settings.php file, and name the copy
Chris@0:      settings.php (overwriting your previous settings.php file).
Chris@0: 
Chris@0:    - Copy the custom and site-specific entries from the backup you made into the
Chris@0:      new settings.php file. You will definitely need the lines giving the
Chris@0:      database information, and you will also want to copy in any other
Chris@0:      customizations you have added.
Chris@0: 
Chris@17: 3. Determine if there are any modifications to files such as .htaccess or
Chris@17:    robots.txt and re-apply them. The Drupal Scaffold composer plugin
Chris@17:    (https://github.com/drupal-composer/drupal-scaffold) can help you with
Chris@17:    excluding files you'd like to always preserve when updating Drupal.
Chris@0: 
Chris@17: 4. Go to the "UPLOADING THE CODE" section
Chris@17: 
Chris@17: UPDATING CODE WITHOUT COMPOSER
Chris@17: ------------------------------
Chris@17: 1. Remove the 'core' and 'vendor' directories. Also remove all of the files
Chris@17:    in the top-level directory, except any that you added manually.
Chris@17: 
Chris@17:    If you made modifications to files like .htaccess, composer.json, or
Chris@17:    robots.txt you will need to re-apply them from your backup, after the new
Chris@17:    files are in place.
Chris@17: 
Chris@17:    This should leave you with the modules, profiles, sites, and themes
Chris@17:    directories. These directories should only contain code that you've used to
Chris@17:    extend Drupal.
Chris@17: 
Chris@17: 2. Download the latest Drupal 8.x.x release from https://www.drupal.org/download
Chris@17:    to a directory outside of your web root. Extract the archive and copy the
Chris@17:    files into your Drupal directory.
Chris@17: 
Chris@17:    Copy all the files, but do not accidentally overwrite your modules, profiles,
Chris@17:    sites, or themes directories.
Chris@0: 
Chris@0:    On a typical Unix/Linux command line, use the following commands to download
Chris@0:    and extract:
Chris@0: 
Chris@0:      wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
Chris@0:      tar -zxvf drupal-x.y.z.tar.gz
Chris@0: 
Chris@0:    This creates a new directory drupal-x.y.z/ containing all Drupal files and
Chris@0:    directories. Copy the files into your Drupal installation directory:
Chris@0: 
Chris@0:      cp -R drupal-x.y.z/* drupal-x.y.z/.htaccess /path/to/your/installation
Chris@0: 
Chris@0:    If you do not have command line access to your server, download the archive
Chris@17:    from https://www.drupal.org using your web browser and extract it locally.
Chris@0: 
Chris@17: 3. Check the release notes for the updated version of Drupal to find out if
Chris@17:    there is a change to default.settings.php.
Chris@0: 
Chris@17:    You can find the release notes for your updated version at
Chris@17:    https://www.drupal.org/project/drupal. At bottom of the project page under
Chris@17:    "Downloads" use the link for your updated version of Drupal to view the
Chris@17:    release notes. If your updated version is not listed, use the 'View all
Chris@17:    releases' link. From this page you can scroll down or use the filter to find
Chris@17:    your updated version and its release notes.
Chris@17: 
Chris@17:    If there is a change to default.settings.php, follow these steps:
Chris@17: 
Chris@17:    - Locate your settings.php file in the /sites/* directory. (Typically
Chris@17:      sites/default.)
Chris@17: 
Chris@17:    - Make a backup copy of your settings.php file, with a different file name.
Chris@17: 
Chris@17:    - Make a copy of the new default.settings.php file, and name the copy
Chris@17:      settings.php (overwriting your previous settings.php file).
Chris@17: 
Chris@17:    - Copy the custom and site-specific entries from the backup you made into the
Chris@17:      new settings.php file. You will definitely need the lines giving the
Chris@17:      database information, and you will also want to copy in any other
Chris@17:      customizations you have added.
Chris@17: 
Chris@17: 4. Re-apply any modifications to files such as .htaccess or robots.txt.
Chris@17: 
Chris@17:    If you have added requirements in composer.json, it is recommended that you
Chris@17:    re-add the requirements using Composer instead of applying the changes by
Chris@17:    hand. For example, on a typical Unix/Linux command line, to reinstall the
Chris@17:    Address module and its dependencies run (replace /PATH/TO/composer with the
Chris@17:    appropriate location for your system):
Chris@17: 
Chris@17:      /PATH/TO/composer require drupal/address
Chris@17: 
Chris@17:    If you do not have command line access to your server, you will need to run
Chris@17:    the Composer commands locally before uploading the file system to your
Chris@17:    server.
Chris@17: 
Chris@17: 5. Go to the "UPLOADING THE CODE" section
Chris@17: 
Chris@17: UPLOADING THE CODE
Chris@17: ------------------
Chris@17: 1. If you updated the code in a different environment from where it is running
Chris@17:    you need to upload the files to your web root including the vendor/
Chris@17:    directory.
Chris@17: 
Chris@17: 2. Go to the "UPDATING THE DATABASE" section
Chris@17: 
Chris@17: UPDATING THE DATABASE
Chris@17: ---------------------
Chris@17: 1. Run update.php by visiting http://www.example.com/update.php (replace
Chris@0:    www.example.com with your domain name). This will update the core database
Chris@0:    tables.
Chris@0: 
Chris@0:    If you are unable to access update.php do the following:
Chris@0: 
Chris@0:    - Open settings.php with a text editor.
Chris@0: 
Chris@0:    - Find the line that says:
Chris@0:      $settings['update_free_access'] = FALSE;
Chris@0: 
Chris@0:    - Change it into:
Chris@0:      $settings['update_free_access'] = TRUE;
Chris@0: 
Chris@0:    - Once the update is done, $settings['update_free_access'] must be reverted
Chris@0:      to FALSE.
Chris@0: 
Chris@17: 2. Go to Administration > Reports > Status report. Verify that everything is
Chris@0:    working as expected.
Chris@0: 
Chris@17: 3. Ensure that $settings['update_free_access'] is FALSE in settings.php.
Chris@0: 
Chris@17: 4. Go to Administration > Configuration > Development > Maintenance mode.
Chris@0:    Disable the "Put site into maintenance mode" checkbox and save the
Chris@0:    configuration.