UPDATE.txt 9.96 KB
Newer Older
1 2
INTRODUCTION
------------
3 4 5 6 7 8 9
This document describes how to update your Drupal site between 8.x.x minor and
patch versions; for example, from 8.1.2 to 8.1.3, or from 8.3.5 to 8.4.0.

To upgrade from a previous major version (for example, Drupal 6 or 7), the
process involves importing site configuration and content from your old site
into a new Drupal 8 site. The tools and process are currently experimental,
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 12 13
provides a user interface for the Migrate and Migrate Drupal modules included
in core. See https://www.drupal.org/upgrade/migrate for details, and
https://www.drupal.org/node/2167633 for known issues.
14

15
First steps and definitions:
16

17 18 19 20 21
  * If you are upgrading to Drupal version x.y.z, then x is known as the major
    version number, y is known as the minor version number, and z is known as
    the patch version number. The download file will be named
    drupal-x.y.z.tar.gz (or drupal-x.y.z.zip). Previous Drupal versions used
    only x.y (MAJOR.MINOR) to designate their versions.
22

23 24
  * All directories mentioned in this document are relative to the directory of
    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 29
    Instructions may be found at
    https://www.drupal.org/upgrade/backing-up-the-db
30 31 32 33

  * It is wise to try an update or upgrade on a test copy of your site before
    applying it to your live site. Even minor updates can cause your site's
    behavior to change.
34

35 36 37 38
  * Each new release of Drupal has release notes, which explain the changes made
    since the previous version and any special instructions needed to update or
    upgrade to the new version. You can find a link to the release notes for the
    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 49
    you created before you started the update process. Do not attempt to do
    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 57 58
MINOR AND PATCH VERSION UPDATES
-------------------------------
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 65
   Enable the "Put site into maintenance mode" checkbox and save the
   configuration.
66

67
3. Determine if your project is managed by Composer.
68

69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109
   On a typical Unix/Linux command line, this can be determined by running the
   following command (replace /PATH/TO/composer with the appropriate location
   for your system):

     /PATH/TO/composer info drupal/core

   If this is successful, your project is managed by Composer.

   If you don't have Composer installed or access to the command line, you can
   check the contents of composer.json. If "drupal/core" is present in the
   "require" section of your composer.json file, then the project is managed by
   Composer.

   If the project is not managed by Composer, follow the steps under "UPDATING
   CODE WITHOUT COMPOSER", otherwise go to "UPDATING CODE WITH COMPOSER".

UPDATING CODE WITH COMPOSER
---------------------------
1. On a typical Unix/Linux command line, run the following command from the root
   directory (replace /PATH/TO/composer with the appropriate location for your
   system):

     /PATH/TO/composer update

   Note, if Composer is not installed you will need to install it in order to
   update Drupal.

   Note, if you want to only update drupal/core the following command will
   probably work:

     /PATH/TO/composer update drupal/core symfony/* --with-all-dependencies

2. Check the release notes for the updated version of Drupal to find out if
   there is a change to default.settings.php.

   You can find the release notes for your version at
   https://www.drupal.org/project/drupal. At bottom of the project page under
   "Downloads" use the link for your version of Drupal to view the release
   notes. If your version is not listed, use the 'View all releases' link. From
   this page you can scroll down or use the filter to find your version and its
   release notes.
110

111
   If there is a change to default.settings.php, follow these steps:
112

113 114 115
   - Locate your settings.php file in the /sites/* directory. (Typically
     sites/default.)

116 117 118 119 120 121 122 123 124
   - Make a backup copy of your settings.php file, with a different file name.

   - Make a copy of the new default.settings.php file, and name the copy
     settings.php (overwriting your previous settings.php file).

   - Copy the custom and site-specific entries from the backup you made into the
     new settings.php file. You will definitely need the lines giving the
     database information, and you will also want to copy in any other
     customizations you have added.
125

126 127 128 129 130 131 132 133 134 135 136
3. Determine if there are any modifications to files such as .htaccess or
   robots.txt and re-apply them. The Drupal Scaffold composer plugin
   (https://github.com/drupal-composer/drupal-scaffold) can help you with
   excluding files you'd like to always preserve when updating Drupal.

4. Go to the "UPLOADING THE CODE" section

UPDATING CODE WITHOUT COMPOSER
------------------------------
1. Remove the 'core' and 'vendor' directories. Also remove all of the files
   in the top-level directory, except any that you added manually.
137

138 139 140 141 142 143 144 145 146 147 148 149 150 151
   If you made modifications to files like .htaccess, composer.json, or
   robots.txt you will need to re-apply them from your backup, after the new
   files are in place.

   This should leave you with the modules, profiles, sites, and themes
   directories. These directories should only contain code that you've used to
   extend Drupal.

2. Download the latest Drupal 8.x.x release from https://www.drupal.org/download
   to a directory outside of your web root. Extract the archive and copy the
   files into your Drupal directory.

   Copy all the files, but do not accidentally overwrite your modules, profiles,
   sites, or themes directories.
152

153 154
   On a typical Unix/Linux command line, use the following commands to download
   and extract:
155

156 157
     wget https://www.drupal.org/files/projects/drupal-x.y.z.tar.gz
     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 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182
   from https://www.drupal.org using your web browser and extract it locally.

3. Check the release notes for the updated version of Drupal to find out if
   there is a change to default.settings.php.

   You can find the release notes for your updated version at
   https://www.drupal.org/project/drupal. At bottom of the project page under
   "Downloads" use the link for your updated version of Drupal to view the
   release notes. If your updated version is not listed, use the 'View all
   releases' link. From this page you can scroll down or use the filter to find
   your updated version and its release notes.

   If there is a change to default.settings.php, follow these steps:

   - Locate your settings.php file in the /sites/* directory. (Typically
     sites/default.)

   - Make a backup copy of your settings.php file, with a different file name.
183

184 185 186 187 188 189 190 191 192
   - Make a copy of the new default.settings.php file, and name the copy
     settings.php (overwriting your previous settings.php file).

   - Copy the custom and site-specific entries from the backup you made into the
     new settings.php file. You will definitely need the lines giving the
     database information, and you will also want to copy in any other
     customizations you have added.

4. Re-apply any modifications to files such as .htaccess or robots.txt.
193

194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218
   If you have added requirements in composer.json, it is recommended that you
   re-add the requirements using Composer instead of applying the changes by
   hand. For example, on a typical Unix/Linux command line, to reinstall the
   Address module and its dependencies run (replace /PATH/TO/composer with the
   appropriate location for your system):

     /PATH/TO/composer require drupal/address

   If you do not have command line access to your server, you will need to run
   the Composer commands locally before uploading the file system to your
   server.

5. Go to the "UPLOADING THE CODE" section

UPLOADING THE CODE
------------------
1. If you updated the code in a different environment from where it is running
   you need to upload the files to your web root including the vendor/
   directory.

2. Go to the "UPDATING THE DATABASE" section

UPDATING THE DATABASE
---------------------
1. Run update.php by visiting http://www.example.com/update.php (replace
219 220
   www.example.com with your domain name). This will update the core database
   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 233
   - Once the update is done, $settings['update_free_access'] must be reverted
     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 242
   Disable the "Put site into maintenance mode" checkbox and save the
   configuration.