- Patch #1431918 by Liam Morland: user_multiple_role_edit() doc needs more detail.
[project/drupal.git] / UPGRADE.txt
1 INTRODUCTION
2 ------------
3 This document describes how to:
4
5   * Update your Drupal site from one minor 7.x version to another minor 7.x
6     version; for example, from 7.8 to 7.9, or from 7.6 to 7.10.
7
8   * Upgrade your Drupal site's major version from 6.x to 7.x.
9
10 First steps and definitions:
11
12   * If you are upgrading to Drupal version x.y, then x is known as the major
13     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   * All directories mentioned in this document are relative to the directory of
17     your Drupal installation.
18
19   * Make a full backup of all files, directories, and your database(s) before
20     starting, and save it outside your Drupal installation directory.
21     Instructions may be found at http://drupal.org/upgrade/backing-up-the-db
22
23   * It is wise to try an update or upgrade on a test copy of your site before
24     applying it to your live site. Even minor updates can cause your site's
25     behavior to change.
26
27   * Each new release of Drupal has release notes, which explain the changes made
28     since the previous version and any special instructions needed to update or
29     upgrade to the new version. You can find a link to the release notes for the
30     version you are upgrading or updating to on the Drupal project page
31     (http://drupal.org/project/drupal).
32
33 UPGRADE PROBLEMS
34 ----------------
35 If you encounter errors during this process,
36
37   * Note any error messages you see.
38
39   * Restore your site to its previous state, using the file and database backups
40     you created before you started the upgrade process. Do not attempt to do
41     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 MINOR VERSION UPDATES
48 ---------------------
49 To update from one minor 7.x version of Drupal to any later 7.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    Enable the "Put site into maintenance mode" checkbox and save the
56    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    If you made modifications to files like .htaccess or robots.txt, you will
62    need to re-apply them from your backup, after the new files are in place.
63
64    Sometimes an update includes changes to default.settings.php (this will be
65    noted in the release notes). If that's the case, follow these steps:
66
67    - Make a backup copy of your settings.php file, with a different file name.
68
69    - Make a copy of the new default.settings.php file, and name the copy
70      settings.php (overwriting your previous settings.php file).
71
72    - Copy the custom and site-specific entries from the backup you made into the
73      new settings.php file. You will definitely need the lines giving the
74      database information, and you will also want to copy in any other
75      customizations you have added.
76
77 4. Download the latest Drupal 7.x release from http://drupal.org to a
78    directory outside of your web root. Extract the archive and copy the files
79    into your Drupal directory.
80
81    On a typical Unix/Linux command line, use the following commands to download
82    and extract:
83
84      wget http://drupal.org/files/projects/drupal-x.y.tar.gz
85      tar -zxvf drupal-x.y.tar.gz
86
87    This creates a new directory drupal-x.y/ containing all Drupal files and
88    directories. Copy the files into your Drupal installation directory:
89
90      cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
91
92    If you do not have command line access to your server, download the archive
93    from http://drupal.org using your web browser, extract it, and then use an
94    FTP client to upload the files to your web root.
95
96 5. Re-apply any modifications to files such as .htaccess or robots.txt.
97
98 6. Run update.php by visiting http://www.example.com/update.php (replace
99    www.example.com with your domain name). This will update the core database
100    tables.
101
102    If you are unable to access update.php do the following:
103
104    - Open settings.php with a text editor.
105
106    - Find the line that says:
107      $update_free_access = FALSE;
108
109    - Change it into:
110      $update_free_access = TRUE;
111
112    - Once the upgrade is done, $update_free_access must be reverted to FALSE.
113
114 7. Go to Administration > Reports > Status report. Verify that everything is
115    working as expected.
116
117 8. Ensure that $update_free_access is FALSE in settings.php.
118
119 9. Go to Administration > Configuration > Development > Maintenance mode.
120    Disable the "Put site into maintenance mode" checkbox and save the
121    configuration.
122
123 MAJOR VERSION UPGRADE
124 ---------------------
125 To upgrade from a previous major version of Drupal to Drupal 7.x, after
126 following the instructions in the INTRODUCTION section at the top of this file:
127
128 1. Check on the Drupal 7 status of your contributed and custom modules and
129    themes. See http://drupal.org/node/948216 for information on upgrading
130    contributed modules and themes. See http://drupal.org/node/895314 for a list
131    of modules that have been moved into core for Drupal 7, and instructions on
132    how to update them. See http://drupal.org/update/modules for information on
133    how to update your custom modules, and http://drupal.org/update/theme for
134    custom themes.
135
136    You may decide at this point that you cannot upgrade your site, because
137    needed modules or themes are not ready for Drupal 7.
138
139 2. Update to the latest available version of Drupal 6.x (if your current version
140    is Drupal 5.x, you have to upgrade to 6.x first). If you need to update,
141    download Drupal 6.x and follow the instructions in its UPGRADE.txt. This
142    document only applies for upgrades from 6.x to 7.x.
143
144 3. In addition to updating to the latest available version of Drupal 7.x core,
145    you must also upgrade all of your contributed modules for Drupal to their
146    latest Drupal 6.x versions.
147
148 4. Log in as user ID 1 (the site maintenance user).
149
150 5. Go to Administer > Site configuration > Site maintenance. Select
151    "Off-line" and save the configuration.
152
153 6. Go to Administer > Site building > Themes. Enable "Garland" and select it as
154    the default theme.
155
156 7. Go to Administer > Site building > Modules. Disable all modules that are not
157    listed under "Core - required" or "Core - optional". It is possible that some
158    modules cannot be disabled, because others depend on them. Repeat this step
159    until all non-core modules are disabled.
160
161    If you know that you will not re-enable some modules for Drupal 7.x and you
162    no longer need their data, then you can uninstall them under the Uninstall
163    tab after disabling them.
164
165 8. On the command line or in your FTP client, remove the file
166
167      sites/default/default.settings.php
168
169 9. Remove all old core files and directories, except for the 'sites' directory
170    and any custom files you added elsewhere.
171
172    If you made modifications to files like .htaccess or robots.txt, you will
173    need to re-apply them from your backup, after the new files are in place.
174
175 10. If you uninstalled any modules, remove them from the sites/all/modules and
176    other sites/*/modules directories. Leave other modules in place, even though
177    they are incompatible with Drupal 7.x.
178
179 11. Download the latest Drupal 7.x release from http://drupal.org to a
180    directory outside of your web root. Extract the archive and copy the files
181    into your Drupal directory.
182
183    On a typical Unix/Linux command line, use the following commands to download
184    and extract:
185
186      wget http://drupal.org/files/projects/drupal-x.y.tar.gz
187      tar -zxvf drupal-x.y.tar.gz
188
189    This creates a new directory drupal-x.y/ containing all Drupal files and
190    directories. Copy the files into your Drupal installation directory:
191
192      cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation
193
194    If you do not have command line access to your server, download the archive
195    from http://drupal.org using your web browser, extract it, and then use an
196    FTP client to upload the files to your web root.
197
198 12. Re-apply any modifications to files such as .htaccess or robots.txt.
199
200 13. Make your settings.php file writeable, so that the update process can
201    convert it to the format of Drupal 7.x. settings.php is usually located in
202
203      sites/default/settings.php
204
205 14. Run update.php by visiting http://www.example.com/update.php (replace
206    www.example.com with your domain name). This will update the core database
207    tables.
208
209    If you are unable to access update.php do the following:
210
211    - Open settings.php with a text editor.
212
213    - Find the line that says:
214      $update_free_access = FALSE;
215
216    - Change it into:
217      $update_free_access = TRUE;
218
219    - Once the upgrade is done, $update_free_access must be reverted to FALSE.
220
221 15. Backup your database after the core upgrade has run.
222
223 16. Replace and update your non-core modules and themes, following the
224    procedures at http://drupal.org/node/948216
225
226 17. Go to Administration > Reports > Status report. Verify that everything is
227    working as expected.
228
229 18. Ensure that $update_free_access is FALSE in settings.php.
230
231 19. Go to Administration > Configuration > Development > Maintenance mode.
232    Disable the "Put site into maintenance mode" checkbox and save the
233    configuration.
234
235 To get started with Drupal 7 administration, visit
236 http://drupal.org/getting-started/7/admin