Index: UPGRADE.txt =================================================================== RCS file: /cvs/drupal/drupal/UPGRADE.txt,v retrieving revision 1.25 diff -u -r1.25 UPGRADE.txt --- UPGRADE.txt 4 Oct 2010 07:20:38 -0000 1.25 +++ UPGRADE.txt 20 Oct 2010 23:58:14 -0000 @@ -1,114 +1,324 @@ // $Id: UPGRADE.txt,v 1.25 2010/10/04 07:20:38 webchick Exp $ -UPGRADING ---------- +INTRODUCTION +------------ +This document describes how to: -Prior to upgrading, you should ensure that: + * Update your Dupal site from one minor 7.x version to another + minor 7.x version; for example, from 7.9 to 7.10 (first section below). - * Your system meets or exceeds Drupal's minimum requirements 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). - * You have read through this entire document. + * Upgrade your Drupal site's major version from 6.x to 7.x (second section + below). -If you are upgrading from one major version to another (i.e., 6.x to 7.x), -you must first upgrade to the latest version of your current release. +First steps and definitions: -Let's begin! + * If you are upgrading or updating to Drupal version x.y, x is known as the + major version number, y is known as the minor version number, and the + download file will be named drupal-x.y.tar.gz -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. + * The "Don't hack core" principle should be respected -- if you have modified + core files outside of the 'sites' subdirectory, this document will not + describe how you should re-apply your changes -- it is assumed that you know + how to do this. See http://drupal.org/node/144376 for more information. - 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. + * When directories are mentioned in this document, they are always relative + to the directory where you have installed Drupal. - For multisite configurations, the configuration file is located in a - structure like the following: + * Make a full backup of your web site's files and directories before starting, + as well as the database your Drupal site is using. Instructions for backing + up your database can be found at http://drupal.org/upgrade/backing-up-the-db - sites/default/settings.php - sites/example.com/settings.php - sites/sub.example.com/settings.php - sites/sub.example.com.path/settings.php + * Read through this entire document before you start. - More information on multisite configuration is located in INSTALL.txt. -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. +MINOR VERSION UPDATES +--------------------- +(Major version upgrades are described in the section below.) -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 - option is at http://www.example.com/?q=admin/config/development/maintenance - (replace www.example.com with your installation's domain name and path). +To update from one minor 7.x version of Drupal to another 7.x version, after +following the instructions in the INTRODUCTION section above: -4. If using a custom or contributed theme, switch to a core theme such as - Bartik or Garland. +1. Log in as a user with the permission "Administer software updates". + IMPORTANT! Do not close your browser until the final step is complete. -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). +2. Navigate to Administer->Configuration->Development->Maintenance mode. Check + the "Put site into maintenance mode" checkbox and click "Save configuration". -6. Remove all old files and directories from the Drupal installation directory. +3. Remove all old core files and directories from the Drupal installation + directory, EXCEPT for the 'sites' subdirectory and any custom files you have + added elsewhere. -7. Unpack the new files and directories into the Drupal installation directory. + If you have made modifications to files like .htaccess or robots.txt, you + need to re-apply these modifications, taken from your backup, after the + new files are in place. -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. +4. Download the latest Drupal release from http://drupal.org/ to a + directory outside of your web root, extract the files from the archive, and + copy the files into your Drupal directory. -9. Verify the new configuration file to make sure it has correct information. + On a typical Unix/Linux command line, this can be accomplished using the + following commands to download and extract: -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. + wget http://drupal.org/files/projects/drupal-x.y.tar.gz + tar -zxvf drupal-x.y.tar.gz - Note: if you are unable to access update.php do the following: + This will create a new directory drupal-x.y/ containing all Drupal files + and directories. Then to copy the files into your Drupal installation + directory: - - Open your settings.php file with a text editor. + cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation - - There is a line that says $update_free_access = FALSE; - Change it to $update_free_access = TRUE; + To avoid permission problems you may also need to change the ownership + of the new files by using the command: - - Once update.php is done, you must change the settings.php file - back to its original form with $update_free_access = FALSE; + chown -R user:group /path/to/your/installation -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 6.x to 7.x, modules from previous versions will not be compatible - and updated versions will be required. + Replace user and group with the ones your webserver runs as. - - For contributed modules, check http://drupal.org/project/modules - for the version of a module matching your version of Drupal. + If you don't have shell access to your server, you can download from + http://drupal.org/ to your PC using your web browser, unpack the files with a + program like winrar or 7-zip, and then use an FTP client to upload the files + to your web root. - - For custom modules, review http://drupal.org/update/modules to - ensure that a custom module is compatible with the current version. + If you are using a hosting panel like Cpanel, you may need to follow their + specific instructions for how to put your files on your site. -12. Re-enable custom and contributed modules and re-run update.php - to update custom and contributed database tables. +5. Re-apply any custom modifications to files such as .htaccess. -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 - compatible with your version of Drupal. +6. Run update.php by visiting http://www.example.com/update.php (replace + www.example.com with your Drupal installation's domain name). This + step will update the core database tables to the new Drupal installation. - - For contributed themes, check http://drupal.org/project/themes - for the version of a theme matching your version of Drupal. + Note: if you are unable to access update.php do the following: - - For custom themes, review http://drupal.org/update/theme to ensure - that a custom theme is compatible with the current version. + - Open your sites/default/settings.php file with a text editor. -14. Finally, return your site to "Online" mode so your visitors may resume - browsing. As in step #3, this option is available in your administration - screens at http://www.example.com/?q=admin/config/development/maintenance - (replace www.example.com with your installation's domain name and path). + - There is a line that says: + $update_free_access = FALSE; -For more information on upgrading, visit + 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; + +7. Assuming all went well with the database update, check your site to verify + that everything is working as expected. + + If there is a problem, follow the instructions at the bottom of this file + (section: Upgrade Problems). + +8. Finally, visit Administer->Configuration->Development->Maintenance mode + again. Un-check the "Put site into maintenance mode" checkbox, then click + "Save configuration" and your visitors may resume browsing again. + + +MAJOR VERSION UPGRADES +---------------------- +(Minor version updates are described in the section above.) + +To upgrade from a previous major version of Drupal to Drupal 7.x, after +following the instructions in the INTRODUCTION section above: + +1. Upgrade to the latest available version of Drupal 6.x, following the + instructions in the UPGRADE.txt file in your Drupal 6.x installation. If you + are currently running Drupal 5.x, you will need to upgrade to 6.x, and if you + are not yet running the latest 6.x version, you will need to update to the + latest 6.x version. + +2. Prepare for the upgrade by ensuring that: + + * Your system meets or exceeds minimum requirements for Drupal 7 as + specified at http://drupal.org/requirements + + * You have done an inventory of all your installed non-core modules, + checking which have a Drupal 7-compatible version and which do not: + + - For contributed modules, visit http://drupal.org/project/modules and + change 'Filter by compatibility:' to 7.x, then click the Search button + to check for modules matching your version of Drupal. + + - For custom modules, review http://drupal.org/update/modules to + ensure that your custom module is compatible with the current version. + + - Check each module's project page for any special procedures to follow + when upgrading to Drupal version 7, and read any UPGRADE.txt files found + in the Drupal 6 or 7 releases of the module. You may find that your module + has been included in the core of Drupal 7, has been discontinued, or has + not yet been upgraded for Drupal 7. See http://drupal.org/node/895314 for + a list of modules that have been moved into the core of Drupal 7. + + - If there is a problem or a conflict with this document, consult one of + the support options listed on http://drupal.org/support + + * You have done an inventory of all your installed non-core themes, + checking which have a Drupal 7-compatible version and which do not: + + - For contributed themes, visit http://drupal.org/project/themes and + change 'Filter by compatibility:' to 7.x, then click the Search button + to check for themes matching your version of Drupal. + + - For custom themes, review http://drupal.org/update/theme and + http://drupal.org/theme-guide to ensure that your custom theme + is compatible with the current version. + + - Check each theme's project page for any special procedures to follow + when upgrading to Drupal version 7, and read any UPGRADE.txt files found + in the Drupal 6 or 7 releases of the theme. You may find that your theme + has been discontinued, or has not yet been upgraded for Drupal 7. + + - If there is a problem or a conflict with this document, consult one of + the support options listed on http://drupal.org/support + + * At this point, with your assessment, if you find that there are modules or + themes that you need that you cannot upgrade to Drupal 7, do not proceed + with this upgrade. You might consider contributing to the modules or themes + that are not yet ready for Drupal 7. + +3. Log in as user ID 1 (also known as the site maintenance account). + IMPORTANT! Do not close your browser until the final step is complete. + +4. Navigate to Administer->Site configuration->Site maintenance. Check the + "Off-line" radio button and click "Save configuration". + +5. Switch to the core theme Garland, if you are using a different theme. The + easiest way to do this is to navigate to Administer->Site building->Themes, + and click the "Reset to defaults" button at the bottom. + +6. Navigate to Administer->Site building->Modules and disable + all modules not listed under 'Core - required' or 'Core - optional'. You + may have to go through this several times due to some modules that can't be + disabled while others still depend on them. + + Any modules that you do not plan to enable in your Drupal 7 site should also + be uninstalled after they are disabled -- do this by clicking on the + Uninstall tab on the Modules page. (Uninstalling removes database tables + and other information related to the modules, to keep your database compact.) + +7. Back on the command line or in your FTP client, remove the + sites/default/default.settings.php file, so that it can be overwritten by + the Drupal 7 version. + +8. Remove all old core files and directories from the Drupal installation + directory, EXCEPT for the 'sites' subdirectory and any custom files you have + added elsewhere. + + If you have made modifications to files like .htaccess or robots.txt, you + need to re-apply these modifications, taken from your backup, after the + new files are in place. + +9. Remove any modules from sites/all/modules and other sites/*/modules + directories that you don't plan to enable in Drupal 7. Also remove modules + whose functionality has been moved into the core of Drupal 7. You can leave + the Drupal 6 versions of other modules in place, even though they are + incompatible with Drupal 7. The benefit of leaving them is that Drupal 7 will + list them and show their dependencies, even though they can't be enabled. This + may help you in the process of upgrading them in a non-conflicting order. + + Follow the same process with custom and contributed themes. + +10. Download the latest Drupal release from http://drupal.org/ to a + directory outside of your web root, extract the files from the archive, and + copy the files into your Drupal directory. + + On a typical Unix/Linux command line, this can be accomplished using the + following commands to download and extract: + + wget http://drupal.org/files/projects/drupal-x.y.tar.gz + tar -zxvf drupal-x.y.tar.gz + + This will create a new directory drupal-x.y/ containing all Drupal files + and directories. Then to copy the files into your Drupal installation + directory: + + cp -R drupal-x.y/* drupal-x.y/.htaccess /path/to/your/installation + + To avoid permission problems you may also need to change the ownership + of the new files by using the command: + + chown -R user:group /path/to/your/installation + + Replace user and group with the ones your webserver runs as. + + If you don't have shell access to your server, you can download from + http://drupal.org/ to your PC using your web browser, unpack the files with a + program like winrar or 7-zip, and then use an FTP client to upload the files + to your web root. + + If you are using a hosting panel like Cpanel, you may need to follow their + specific instructions for how to put your files on your site. + +11. Re-apply any custom modifications to files such as .htaccess, settings.php, + or robots.txt. + +12. Make sure that your settings file (usually sites/default/settings.php) + is writeable, so that the update process can convert it to the Drupal 7 + format. + +13. Run update.php by visiting http://www.example.com/update.php (replace + www.example.com with your Drupal installation's domain name). This + step will update the core database tables to the new Drupal installation. + + Note: if you are unable to access update.php do the following: + + - Open your settings.php (sites/default/settings.php or a different + sites/*/settings.php file) with a text editor. + + - There is a line that says: + $update_free_access = FALSE; + + 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; + +14. Update and re-enable your non-core modules one by one, following this + procedure: + - Check your notes to see if any special upgrade instructions apply + - Fully remove the old module directory inside sites/all/modules/ + - Download, unpack and move the new module directory to sites/all/modules/ + - Re-run update.php and check for any message output + + Following this procedure for every module may be time consuming if you + have many modules to re-enable, so it is possible to do more than one module + at the same time, especially if they are unrelated or don't have dependencies. + However, this also increases the likelihood something will go wrong. + + If you have many modules to upgrade, you might consider making intermediate + database backups. That way, if something goes wrong with one of the upgrades, + you can revert without having to start completely over. + +15. If applicable, return the site to its original theme following the same + procedure as in #14, putting the theme in sites/all/themes/. + +16. Assuming all went well with the database updates, check your site to verify + that everything is working as expected. + + If there is a problem, follow the instructions at the bottom of this file + (section: Upgrade Problems). + +17. Finally, visit Administer->Configuration->Development->Maintenance mode + Un-check the "Put site into maintenance mode" checkbox, then click + "Save configuration" and your visitors may resume browsing again. + +To Get started with Drupal 7 administration, visit +http://drupal.org/getting-started/7/admin + + +UPGRADE PROBLEMS +---------------- +If you have errors when you run the update.php script: + +1. Note any error messages you see. + +2. Restore your site to its previous state, using the file and database backups + you created before you started the upgrade or update process. Do not attempt + to do further updates or upgrades on a site that had update problems. + +3. Consult one of the support options listed on http://drupal.org/support. + + +-------------------------------------- +For more in depth information on upgrading, visit the Drupal handbook at http://drupal.org/upgrade