Index: UPGRADE.txt =================================================================== RCS file: /cvs/drupal/drupal/UPGRADE.txt,v retrieving revision 1.24 diff -u -r1.24 UPGRADE.txt --- UPGRADE.txt 11 Aug 2010 01:06:44 -0000 1.24 +++ UPGRADE.txt 31 Aug 2010 20:10:57 -0000 @@ -1,44 +1,75 @@ // $Id: UPGRADE.txt,v 1.24 2010/08/11 01:06:44 dries Exp $ -UPGRADING +HOW TO UPGRADE FROM ONE DRUPAL VERSION TO ANOTHER +------------------------------------------------- + +PREPARATION --------- Prior to upgrading, you should ensure that: - * Your system meets or exceeds Drupal's minimum requirements as shown at + * Your system meets or exceeds Drupal's minimum requirements for the new + version you are upgrading to, as shown at http://drupal.org/requirements. * You have a backup of all your relevant data (#1). - * Custom and contributed modules have been checked for compatibility (#11). - * Custom and contributed themes have been checked for compatibility (#11). + * Custom and contributed modules and themes have been checked for + compatibility (#11), if you are upgrading to a new major version (e.g. 6.x + to 7.x). + * If you are making a major version upgrade, you have first upgraded to the + latest minor version in the old series. For example, if you are upgrading + from 6.12 to 7.2, you should first upgrade from 6.12 to 6.19 (or the latest + 6.x version), and then upgrade from 6.19 to 7.2. * You have read through this entire document. -Let's begin! +TERMINOLOGY +----------- + +Here are some terms used elsewhere in this file: + +Configuration file + For a single site setup, the configuration file is the "settings.php" + file located at sites/default/settings.php. The default.settings.php file + contains a clean copy for restoration purposes, if required. + + For multisite configurations, the configuration files are located in one or + more of the following locations: + sites/default/settings.php + sites/example.com/settings.php + sites/sub.example.com/settings.php + sites/sub.example.com.path/settings.php + More information on multisite configuration is located in INSTALL.txt. + +Minor/major version upgrade + A major version upgrade is, for example, upgrading from Drupal 6.x to 7.x. A + minor version upgrade is, for example, upgrading from Drupal 7.2 to 7.3. Some + steps (as noted below) are usually not necessary when making a minor version + upgrade, although if a minor version upgrade includes a security fix that + removes some faulty Drupal functionality that a contributed or custom theme or + module was relying on, your site could break if that module or theme is + left enabled. + +Drupal installation directory + The directory where all the Drupal files are installed. It should contain + subdirectories such as modules, themes, includes, .... + +STEPS FOR UPGRADING +------------------- 1. Back up your Drupal database and site root directory. Be especially sure to back up your "sites" directory which contains your configuration file, added modules and themes, and your site's uploaded files. If other files have modifications, such as .htaccess or robots.txt, back those up as well. - - Note: for a single site setup, the configuration file is the "settings.php" - file located at sites/default/settings.php. The default.settings.php file - contains a clean copy for restoration purposes, if required. - - For multisite configurations, the configuration file is located in a - structure like the following: - - sites/default/settings.php - sites/example.com/settings.php - sites/sub.example.com/settings.php - sites/sub.example.com.path/settings.php - - More information on multisite configuration is located in INSTALL.txt. + If you are using the "files" directory to store uploaded files (from an + earlier version of Drupal), back this directory up as well. 2. If possible, log on either as a user with the "Administer software updates" permission or as the user with user ID 1, which is the first account created (also known as the site maintenance account). Only these accounts - will be able to automatically access update.php in step #10. There are - special instructions in step #10 if you are unable to log on as one of - these users. Do not close your browser until the final step is complete. + will be able to automatically access update.php in step #10, although there + are also special instructions in step #10 if you are unable to log on as one + of these users. At a minimum, you need to be logged in as a user who has + permission to access the site in maintenance mode. Do not close your browser + or log out until the final step is complete. 3. Place the site in "Offline" mode, to let the database updates run without interruption and avoid displaying errors to end users of the site. This @@ -46,29 +77,37 @@ (replace www.example.com with your installation's domain name and path). 4. If using a custom or contributed theme, switch to a core theme such as - Bartik or Garland. + Bartik or Garland. This step is usually not necessary for minor version + upgrades. 5. Disable all custom and contributed modules. This includes any modules that are not listed under 'Core - required' or 'Core - optional' on http://www.example.com/?q=admin/build/modules (replace www.example.com with - your installation's domain name and path). + your installation's domain name and path). This step is usually not + necessary for minor version upgrades. 6. Remove all old files and directories from the Drupal installation directory. 7. Unpack the new files and directories into the Drupal installation directory. -8. Copy your backed up "files" and "sites" directories to the Drupal - installation directory. If other system files such as .htaccess or - robots.txt were customized, re-create the modifications in the new - versions of the files using the backups taken in step #1. - -9. Verify the new configuration file to make sure it has correct information. +8. Copy your backed up "sites" directory to the Drupal installation directory, + as well as the "files" directory if you backed that up. If other system + files such as .htaccess or robots.txt were backed up in step #1, re-create + your customizations in the new versions of the files. + +9. Rather than just using the configuration file(s) from your previous + installation, start with a copy of the default configuration file in + sites/default/default.settings.php, and customize it from your backed up + configuration file(s), putting the new files in the same locations as the + old ones. 10. Run update.php by visiting http://www.example.com/update.php (replace www.example.com with your Drupal installation's domain name and path). This - step will update the core database tables to the new Drupal installation. + step will update the core database tables for compatibility with the new + Drupal version. - Note: if you are unable to access update.php do the following: + Note: if you are unable to access update.php as the user you are logged in + as, do the following: - Open your settings.php with a text editor. @@ -76,12 +115,18 @@ Change it to $update_free_access = TRUE; - Once update.php is done, you must change the settings.php file - back to its original form with $update_free_access = FALSE; + back to its original form with $update_free_access = FALSE; Note that + you may want to wait until after step #12 to do this. + +11. Ensure that the versions of all custom and contributed modules match the new + Drupal version. This step is usually not necessary for minor version + upgrades, but for a major version upgrade, you will need new versions. New + major versions of Drupal may have also incorporated one or more of your + contributed modules into the core of Drupal. In that case, you may need to + download a helper module that will migrate your stored settings and data + from the contributed module to the new Drupal core module. -11. Ensure that the versions of all custom and contributed modules match the - new Drupal version to which you have updated. For a major update, such as - from 5.x to 6.x, modules from previous versions will not be compatible - and updated versions will be required. + To find compatible versions, information, and upgrade helper modules: - For contributed modules, check http://drupal.org/project/modules for the version of a module matching your version of Drupal. @@ -89,8 +134,8 @@ - For custom modules, review http://drupal.org/update/modules to ensure that a custom module is compatible with the current version. -12. Re-enable custom and contributed modules and re-run update.php - to update custom and contributed database tables. +12. Re-enable custom and contributed modules that you disabled in step #5, and + run update.php (see step #10) to update their database tables. 13. Return the site to its original theme (if you switched to a core theme in step #4). If your site uses a custom or contributed theme, make sure it is @@ -107,5 +152,5 @@ screens at http://www.example.com/?q=admin/config/development/maintenance (replace www.example.com with your installation's domain name and path). -For more information on upgrading visit -the Drupal handbook at http://drupal.org/upgrade +For more information on upgrading visit the Drupal handbook at +http://drupal.org/upgrade