www.aleph1.co.uk Git - yaffs-website/blob - web/core/UPDATE.txt

   1 INTRODUCTION
   2 ------------
   3 This document describes how to update your Drupal site between 8.x.x minor and
   4 patch versions; for example, from 8.1.2 to 8.1.3, or from 8.3.5 to 8.4.0.
   5
   6 To upgrade from a previous major version (for example, Drupal 6 or 7), the
   7 process involves importing site configuration and content from your old site
   8 into a new Drupal 8 site. The tools and process are currently experimental,
   9 rather than being fully supported, so be sure to test in a development
  10 environment. You will need to use the core Migrate Drupal UI module which
  11 provides a user interface for the Migrate and Migrate Drupal modules included
  12 in core. See https://www.drupal.org/upgrade/migrate for details, and
  13 https://www.drupal.org/node/2167633 for known issues.
  14
  15 First steps and definitions:
  16
  17   * If you are upgrading to Drupal version x.y.z, then x is known as the major
  18     version number, y is known as the minor version number, and z is known as
  19     the patch version number. The download file will be named
  20     drupal-x.y.z.tar.gz (or drupal-x.y.z.zip). Previous Drupal versions used
  21     only x.y (MAJOR.MINOR) to designate their versions.
  22
  23   * All directories mentioned in this document are relative to the directory of
  24     your Drupal installation.
  25
  26   * Make a full backup of all files, directories, and your database(s) before
  27     starting, and save it outside your Drupal installation directory.
  28     Instructions may be found at
  29     https://www.drupal.org/upgrade/backing-up-the-db
  30
  31   * It is wise to try an update or upgrade on a test copy of your site before
  32     applying it to your live site. Even minor updates can cause your site's
  33     behavior to change.
  34
  35   * Each new release of Drupal has release notes, which explain the changes made
  36     since the previous version and any special instructions needed to update or
  37     upgrade to the new version. You can find a link to the release notes for the
  38     version you are upgrading or updating to on the Drupal project page
  39     (https://www.drupal.org/project/drupal).
  40
  41 UPDATE PROBLEMS
  42 ----------------
  43 If you encounter errors during this process,
  44
  45   * Note any error messages you see.
  46
  47   * Restore your site to its previous state, using the file and database backups
  48     you created before you started the update process. Do not attempt to do
  49     further updates on a site that had update problems.
  50
  51   * Consult one of the support options listed on https://www.drupal.org/support
  52
  53 More in-depth information on updating and upgrading can be found at
  54 https://www.drupal.org/upgrade
  55
  56 MINOR AND PATCH VERSION UPDATES
  57 -------------------------------
  58 To update from one 8.x.x version of Drupal to any later 8.x.x version, after
  59 following the instructions in the INTRODUCTION section at the top of this file:
  60
  61 1. Log in as a user with the permission "Administer software updates".
  62
  63 2. Go to Administration > Configuration > Development > Maintenance mode.
  64    Enable the "Put site into maintenance mode" checkbox and save the
  65    configuration.
  66
  67 3. Determine if your project is managed by Composer.
  68
  69    On a typical Unix/Linux command line, this can be determined by running the
  70    following command (replace /PATH/TO/composer with the appropriate location
  71    for your system):
  72
  73      /PATH/TO/composer info drupal/core
  74
  75    If this is successful, your project is managed by Composer.
  76
  77    If you don't have Composer installed or access to the command line, you can
  78    check the contents of composer.json. If "drupal/core" is present in the
  79    "require" section of your composer.json file, then the project is managed by
  80    Composer.
  81
  82    If the project is not managed by Composer, follow the steps under "UPDATING
  83    CODE WITHOUT COMPOSER", otherwise go to "UPDATING CODE WITH COMPOSER".
  84
  85 UPDATING CODE WITH COMPOSER
  86 ---------------------------
  87 1. On a typical Unix/Linux command line, run the following command from the root
  88    directory (replace /PATH/TO/composer with the appropriate location for your
  89    system):
  90
  91      /PATH/TO/composer update
  92
  93    Note, if Composer is not installed you will need to install it in order to
  94    update Drupal.
  95
  96    Note, if you want to only update drupal/core the following command will
  97    probably work:
  98
  99      /PATH/TO/composer update drupal/core symfony/* --with-all-dependencies
 100
 101 2. Check the release notes for the updated version of Drupal to find out if
 102    there is a change to default.settings.php.
 103
 104    You can find the release notes for your version at
 105    https://www.drupal.org/project/drupal. At bottom of the project page under
 106    "Downloads" use the link for your version of Drupal to view the release
 107    notes. If your version is not listed, use the 'View all releases' link. From
 108    this page you can scroll down or use the filter to find your version and its
 109    release notes.
 110
 111    If there is a change to default.settings.php, follow these steps:
 112
 113    - Locate your settings.php file in the /sites/* directory. (Typically
 114      sites/default.)
 115
 116    - Make a backup copy of your settings.php file, with a different file name.
 117
 118    - Make a copy of the new default.settings.php file, and name the copy
 119      settings.php (overwriting your previous settings.php file).
 120
 121    - Copy the custom and site-specific entries from the backup you made into the
 122      new settings.php file. You will definitely need the lines giving the
 123      database information, and you will also want to copy in any other
 124      customizations you have added.
 125
 126 3. Determine if there are any modifications to files such as .htaccess or
 127    robots.txt and re-apply them. The Drupal Scaffold composer plugin
 128    (https://github.com/drupal-composer/drupal-scaffold) can help you with
 129    excluding files you'd like to always preserve when updating Drupal.
 130
 131 4. Go to the "UPLOADING THE CODE" section
 132
 133 UPDATING CODE WITHOUT COMPOSER
 134 ------------------------------
 135 1. Remove the 'core' and 'vendor' directories. Also remove all of the files
 136    in the top-level directory, except any that you added manually.
 137
 138    If you made modifications to files like .htaccess, composer.json, or
 139    robots.txt you will need to re-apply them from your backup, after the new
 140    files are in place.
 141
 142    This should leave you with the modules, profiles, sites, and themes
 143    directories. These directories should only contain code that you've used to
 144    extend Drupal.
 145
 146 2. Download the latest Drupal 8.x.x release from https://www.drupal.org/download
 147    to a directory outside of your web root. Extract the archive and copy the
 148    files into your Drupal directory.
 149
 150    Copy all the files, but do not accidentally overwrite your modules, profiles,
 151    sites, or themes directories.
 152
 153    On a typical Unix/Linux command line, use the following commands to download
 154    and extract:
 155
 156      wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
 157      tar -zxvf drupal-x.y.z.tar.gz
 158
 159    This creates a new directory drupal-x.y.z/ containing all Drupal files and
 160    directories. Copy the files into your Drupal installation directory:
 161
 162      cp -R drupal-x.y.z/* drupal-x.y.z/.htaccess /path/to/your/installation
 163
 164    If you do not have command line access to your server, download the archive
 165    from https://www.drupal.org using your web browser and extract it locally.
 166
 167 3. Check the release notes for the updated version of Drupal to find out if
 168    there is a change to default.settings.php.
 169
 170    You can find the release notes for your updated version at
 171    https://www.drupal.org/project/drupal. At bottom of the project page under
 172    "Downloads" use the link for your updated version of Drupal to view the
 173    release notes. If your updated version is not listed, use the 'View all
 174    releases' link. From this page you can scroll down or use the filter to find
 175    your updated version and its release notes.
 176
 177    If there is a change to default.settings.php, follow these steps:
 178
 179    - Locate your settings.php file in the /sites/* directory. (Typically
 180      sites/default.)
 181
 182    - Make a backup copy of your settings.php file, with a different file name.
 183
 184    - Make a copy of the new default.settings.php file, and name the copy
 185      settings.php (overwriting your previous settings.php file).
 186
 187    - Copy the custom and site-specific entries from the backup you made into the
 188      new settings.php file. You will definitely need the lines giving the
 189      database information, and you will also want to copy in any other
 190      customizations you have added.
 191
 192 4. Re-apply any modifications to files such as .htaccess or robots.txt.
 193
 194    If you have added requirements in composer.json, it is recommended that you
 195    re-add the requirements using Composer instead of applying the changes by
 196    hand. For example, on a typical Unix/Linux command line, to reinstall the
 197    Address module and its dependencies run (replace /PATH/TO/composer with the
 198    appropriate location for your system):
 199
 200      /PATH/TO/composer require drupal/address
 201
 202    If you do not have command line access to your server, you will need to run
 203    the Composer commands locally before uploading the file system to your
 204    server.
 205
 206 5. Go to the "UPLOADING THE CODE" section
 207
 208 UPLOADING THE CODE
 209 ------------------
 210 1. If you updated the code in a different environment from where it is running
 211    you need to upload the files to your web root including the vendor/
 212    directory.
 213
 214 2. Go to the "UPDATING THE DATABASE" section
 215
 216 UPDATING THE DATABASE
 217 ---------------------
 218 1. Run update.php by visiting http://www.example.com/update.php (replace
 219    www.example.com with your domain name). This will update the core database
 220    tables.
 221
 222    If you are unable to access update.php do the following:
 223
 224    - Open settings.php with a text editor.
 225
 226    - Find the line that says:
 227      $settings['update_free_access'] = FALSE;
 228
 229    - Change it into:
 230      $settings['update_free_access'] = TRUE;
 231
 232    - Once the update is done, $settings['update_free_access'] must be reverted
 233      to FALSE.
 234
 235 2. Go to Administration > Reports > Status report. Verify that everything is
 236    working as expected.
 237
 238 3. Ensure that $settings['update_free_access'] is FALSE in settings.php.
 239
 240 4. Go to Administration > Configuration > Development > Maintenance mode.
 241    Disable the "Put site into maintenance mode" checkbox and save the
 242    configuration.