Index: UPGRADE.txt =================================================================== RCS file: /cvs/drupal/drupal/UPGRADE.txt,v retrieving revision 1.26 diff -u -r1.26 UPGRADE.txt --- UPGRADE.txt 22 Oct 2010 00:31:59 -0000 1.26 +++ UPGRADE.txt 22 Oct 2010 17:19:28 -0000 @@ -5,7 +5,8 @@ This document describes how to: * Update your Drupal site from one minor 7.x version to another minor 7.x - version; for example, from 7.9 to 7.10. + version; for example, from 7.9 to 7.10. It's also OK to skip several minor + versions; for instance, you can go directly from 7.1 to 7.5. * Upgrade your Drupal site's major version from 6.x to 7.x. @@ -15,16 +16,23 @@ version number, and y is known as the minor version number. The download file will be named drupal-x.y.tar.gz. - * The "Don't hack core" principle is respected. If you modified core files - outside of the 'sites' directory, see http://drupal.org/node/144376. - - * All directories mentioned in this document are always relative to the - directory of your Drupal installation. + * All directories mentioned in this document are relative to the directory of + your Drupal installation. * Make a full backup of all files, directories, and your database(s) before - starting. Instructions may be found at - http://drupal.org/upgrade/backing-up-the-db + starting, and save it outside your Drupal installation directory. + Instructions may be found at http://drupal.org/upgrade/backing-up-the-db + + * If you are performing a major version upgrade, make sure to check on the + status of your contributed and custom modules and themes before you decide + it is time to start. See http://drupal.org/node/948216 for a description of + the decision and upgrade process. Also, if you have installed any of the + modules that have moved into core for Drupal 7 (listed on + http://drupal.org/node/895314), there may be additional steps you need to + follow. (More information on that page.) + * It is wise to try a major upgrade on a test copy of your site, making notes + as you go, before upgrading your live site. UPGRADE PROBLEMS ---------------- @@ -43,13 +51,12 @@ MINOR VERSION UPDATES --------------------- -To update from one minor 7.x version of Drupal to another 7.x version, after +To update from one minor 7.x version of Drupal to any later 7.x version, after following the instructions in the INTRODUCTION section at the top of this file: 1. Log in as a user with the permission "Administer software updates". - IMPORTANT! Do not close your browser until the final step is complete. -2. Go to Administer » Configuration » Development » Maintenance mode. +2. Go to Administer > Configuration > Development > Maintenance mode. Enable the "Put site into maintenance mode" checkbox and save the configuration. @@ -59,6 +66,12 @@ If you made modifications to files like .htaccess or robots.txt, you will need to re-apply them from your backup, after the new files are in place. + Sometimes, an update also includes changes to settings.php. If so, this is + stated in the release announcement for the update. If that's the case, + replace your old settings.php with the new one, and copy the site-specific + entries (especially the lines2 giving the database name, user, and password) + from the old settings.php to the new settings.php. + 4. Download the latest Drupal 7.x release from http://drupal.org to a directory outside of your web root. Extract the archive and copy the files into your Drupal directory. @@ -82,7 +95,8 @@ 6. Run update.php by visiting http://www.example.com/update.php (replace www.example.com with your domain name). This will update the core database - tables. + tables. IMPORTANT! Do not close your browser until the final step is + complete. If you are unable to access update.php do the following: @@ -96,12 +110,12 @@ - Once the upgrade is done, $update_free_access must be reverted to FALSE. -7. Go to Administration » Reports » Status report. Verify that everything is +7. Go to Administration > Reports > Status report. Verify that everything is is working as expected. 8. Ensure that $update_free_access is FALSE in settings.php. -9. Go to Administration » Configuration » Development » Maintenance mode. +9. Go to Administration > Configuration > Development > Maintenance mode. Disable the "Put site into maintenance mode" checkbox and save the configuration. @@ -114,45 +128,44 @@ 1. Update to the latest available version of Drupal 6.x. If your current version is Drupal 5.x, you have to upgrade to 6.x first. - Download Drupal 6.x and follow the instructions in UPGRADE.txt instead. + Download Drupal 6.x and follow the instructions in its UPGRADE.txt instead. This document only applies for upgrades from 6.x to 7.x. -2. Check the availability of your modules and themes for Drupal 7.x. See - http://drupal.org/node/948216 - -3. Log in as user ID 1 (the site maintenance user). +2. Log in as user ID 1 (the site maintenance user). -4. Go to Administer » Site configuration » Site maintenance. Select "Off-line" +3. Go to Administer > Site configuration > Site maintenance. Select "Off-line" and save the configuration. -5. Go to Administer » Site building » Themes. Enable "Garland" and select it as - default theme. +4. Go to Administer > Site building > Themes. Enable "Garland" and select it as + the default theme. -6. Go to Administer » Site building » Modules. Disable all modules that are not +5. Go to Administer > Site building > Modules. Disable all modules that are not listed under "Core - required" or "Core - optional". It is possible that some modules cannot be disabled, because others depend on them. Repeat this step until all non-core modules are disabled. - In case you already know that you will not re-enable some modules for Drupal + If you already know that you will not re-enable some modules for Drupal 7.x and you no longer need their data, then you can uninstall them under the - Uninstall tab afterwards. See http://drupal.org/node/895314 for a list of - modules whose functionality has been moved into core for Drupal 7.x. + Uninstall tab after disabling them. -7. On the command line or in your FTP client, remove the file + Also, make sure you have followed the instructions in the INTRODUCTION + section above about contributed modules. + +6. On the command line or in your FTP client, remove the file sites/default/default.settings.php -8. Remove all old core files and directories, EXCEPT for the 'sites' directory +7. Remove all old core files and directories, EXCEPT for the 'sites' directory and any custom files you added elsewhere. If you made modifications to files like .htaccess or robots.txt, you will need to re-apply them from your backup, after the new files are in place. -9. If you uninstalled any modules, remove them from the sites/all/modules and +8. If you uninstalled any modules, remove them from the sites/all/modules and other sites/*/modules directories. Leave other modules in place, even though they are incompatible with Drupal 7.x. -10. Download the latest Drupal 7.x release from http://drupal.org to a +9. Download the latest Drupal 7.x release from http://drupal.org to a directory outside of your web root. Extract the archive and copy the files into your Drupal directory. @@ -171,14 +184,14 @@ from http://drupal.org using your web browser, extract it, and then use an FTP client to upload the files to your web root. -11. Re-apply any modifications to files such as .htaccess or robots.txt. +10. Re-apply any modifications to files such as .htaccess or robots.txt. -12. Make your settings.php file writeable, so that the update process can +11. Make your settings.php file writeable, so that the update process can convert it to the format of Drupal 7.x. settings.php is usually located in sites/default/settings.php -13. Run update.php by visiting http://www.example.com/update.php (replace +12. Run update.php by visiting http://www.example.com/update.php (replace www.example.com with your domain name). This will update the core database tables. @@ -194,27 +207,17 @@ - Once the upgrade is done, $update_free_access must be reverted to FALSE. -14. Backup your database after the core upgrade has run. - -15. Replace your non-core modules, following this procedure: - - - Check your notes for any special upgrade instructions. - - Entirely delete the old module directory in sites/all/modules/. - - Download, extract, and move the new module directory to sites/all/modules/. - -16. Go to Administration » Modules. Re-enable your non-core modules. - -17. Re-run update.php. +13. Backup your database after the core upgrade has run. -18. If applicable, return the site to its original theme following the same - procedure as in 15., but putting the theme in sites/all/themes/. +14. Replace and update your non-core modules and themes, following the + procedures at http://drupal.org/node/948216 -19. Go to Administration » Reports » Status report. Verify that everything is +15. Go to Administration > Reports > Status report. Verify that everything is is working as expected. -20. Ensure that $update_free_access is FALSE in settings.php. +16. Ensure that $update_free_access is FALSE in settings.php. -21. Go to Administration » Configuration » Development » Maintenance mode. +17. Go to Administration > Configuration > Development > Maintenance mode. Disable the "Put site into maintenance mode" checkbox and save the configuration.