UPGRADE.txt 5.15 KB
Newer Older
1 2 3
INTRODUCTION
------------
This document describes how to:
4

5 6
  * Update your Drupal site from one minor 8.x version to another minor 8.x
    version; for example, from 8.8 to 8.9, or from 8.6 to 8.10.
7

8
  * Migrate your Drupal site to version 8.x.
9

10
First steps and definitions:
11

12 13
  * If you are upgrading to Drupal version x.y, then x is known as the major
    version number, and y is known as the minor version number. The download
14
    file will be named drupal-x.y.tar.gz (or drupal-x.y.zip).
15

16 17
  * All directories mentioned in this document are relative to the directory of
    your Drupal installation.
18

19
  * Make a full backup of all files, directories, and your database(s) before
20 21 22 23 24 25
    starting, and save it outside your Drupal installation directory.
    Instructions may be found at http://drupal.org/upgrade/backing-up-the-db

  * 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.
26

27 28 29 30 31
  * 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
    (http://drupal.org/project/drupal).
32

33 34 35
UPGRADE PROBLEMS
----------------
If you encounter errors during this process,
36

37
  * Note any error messages you see.
38

39 40 41
  * Restore your site to its previous state, using the file and database backups
    you created before you started the upgrade process. Do not attempt to do
    further upgrades on a site that had update problems.
42

43
  * Consult one of the support options listed on http://drupal.org/support
44

45
More in-depth information on upgrading can be found at http://drupal.org/upgrade
46

47 48
MINOR VERSION UPDATES
---------------------
49
To update from one minor 8.x version of Drupal to any later 8.x version, after
50
following the instructions in the INTRODUCTION section at the top of this file:
51

52
1. Log in as a user with the permission "Administer software updates".
53

54
2. Go to Administration > Configuration > Development > Maintenance mode.
55 56
   Enable the "Put site into maintenance mode" checkbox and save the
   configuration.
57

58
3. Remove all old core files and directories, except for the 'sites' directory
59
   and any custom files you added elsewhere.
60

61 62 63
   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.
64

65 66 67 68 69 70 71 72 73 74 75 76
   Sometimes an update includes changes to default.settings.php (this will be
   noted in the release notes). If that's the case, follow these steps:

   - 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.
77

78
4. Download the latest Drupal 8.x release from http://drupal.org to a
79 80
   directory outside of your web root. Extract the archive and copy the files
   into your Drupal directory.
81

82 83
   On a typical Unix/Linux command line, use the following commands to download
   and extract:
84

85 86
     wget http://drupal.org/files/projects/drupal-x.y.tar.gz
     tar -zxvf drupal-x.y.tar.gz
87

88 89
   This creates a new directory drupal-x.y/ containing all Drupal files and
   directories. Copy the files into your Drupal installation directory:
90

91
     cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
92

93 94 95
   If you do not have command line access to your server, download the archive
   from http://drupal.org using your web browser, extract it, and then use an
   FTP client to upload the files to your web root.
96

97 98
5. Re-apply any modifications to files such as .htaccess, composer.json, or
   robots.txt.
99

100
6. Run update.php by visiting http://www.example.com/update.php (replace
101 102
   www.example.com with your domain name). This will update the core database
   tables.
103

104
   If you are unable to access update.php do the following:
105

106
   - Open settings.php with a text editor.
107

108
   - Find the line that says:
109
     $settings['update_free_access'] = FALSE;
110 111

   - Change it into:
112
     $settings['update_free_access'] = TRUE;
113

114 115
   - Once the upgrade is done, $settings['update_free_access'] must be
     reverted to FALSE.
116

117 118
7. Go to Administration > Reports > Status report. Verify that everything is
   working as expected.
119

120
8. Ensure that $settings['update_free_access'] is FALSE in settings.php.
121

122
9. Go to Administration > Configuration > Development > Maintenance mode.
123 124 125
   Disable the "Put site into maintenance mode" checkbox and save the
   configuration.

126 127 128
MAJOR VERSION MIGRATION
-----------------------
Upgrading from a prior major version of Drupal to Drupal 8.x is not possible.
129
The process now requires a migration to a Drupal 8.x site, using the Migrate
130
module in Drupal core.
131

132
Note that migration support in Drupal 8 is currently only partially implemented.