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. Remove the 'core' and 'vendor' directories. Also remove all of the files
  68    in the top-level directory, except any that you added manually.
  69
  70    If you made modifications to files like .htaccess, composer.json, or
  71    robots.txt you will need to re-apply them from your backup, after the new
  72    files are in place.
  73
  74    Sometimes an update includes changes to default.settings.php (this will be
  75    noted in the release notes). If that's the case, follow these steps:
  76
  77    - Locate your settings.php file in the /sites/* directory. (Typically
  78      sites/default.)
  79
  80    - Make a backup copy of your settings.php file, with a different file name.
  81
  82    - Make a copy of the new default.settings.php file, and name the copy
  83      settings.php (overwriting your previous settings.php file).
  84
  85    - Copy the custom and site-specific entries from the backup you made into the
  86      new settings.php file. You will definitely need the lines giving the
  87      database information, and you will also want to copy in any other
  88      customizations you have added.
  89
  90    You can find the release notes for your version at
  91    https://www.drupal.org/project/drupal. At bottom of the project page under
  92    "Downloads" use the link for your version of Drupal to view the release
  93    notes. If your version is not listed, use the 'View all releases' link. From
  94    this page you can scroll down or use the filter to find your version and its
  95    release notes.
  96
  97 4. Download the latest Drupal 8.x.x release from https://www.drupal.org to a
  98    directory outside of your web root. Extract the archive and copy the files
  99    into your Drupal directory.
 100
 101    On a typical Unix/Linux command line, use the following commands to download
 102    and extract:
 103
 104      wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
 105      tar -zxvf drupal-x.y.z.tar.gz
 106
 107    This creates a new directory drupal-x.y.z/ containing all Drupal files and
 108    directories. Copy the files into your Drupal installation directory:
 109
 110      cp -R drupal-x.y.z/* drupal-x.y.z/.htaccess /path/to/your/installation
 111
 112    If you do not have command line access to your server, download the archive
 113    from https://www.drupal.org using your web browser, extract it, and then use
 114    an FTP client to upload the files to your web root.
 115
 116 5. Re-apply any modifications to files such as .htaccess, composer.json, or
 117    robots.txt.
 118
 119 6. Run update.php by visiting http://www.example.com/update.php (replace
 120    www.example.com with your domain name). This will update the core database
 121    tables.
 122
 123    If you are unable to access update.php do the following:
 124
 125    - Open settings.php with a text editor.
 126
 127    - Find the line that says:
 128      $settings['update_free_access'] = FALSE;
 129
 130    - Change it into:
 131      $settings['update_free_access'] = TRUE;
 132
 133    - Once the update is done, $settings['update_free_access'] must be reverted
 134      to FALSE.
 135
 136 7. Go to Administration > Reports > Status report. Verify that everything is
 137    working as expected.
 138
 139 8. Ensure that $settings['update_free_access'] is FALSE in settings.php.
 140
 141 9. Go to Administration > Configuration > Development > Maintenance mode.
 142    Disable the "Put site into maintenance mode" checkbox and save the
 143    configuration.
 144