Index: UPGRADE.txt =================================================================== --- UPGRADE.txt (revision 759) +++ UPGRADE.txt (working copy) @@ -1,31 +1,183 @@ // $Id: UPGRADE.txt,v 1.25 2010/10/04 07:20:38 webchick Exp $ +PRESUMPTIONS +------------------- +This document outlines the following 2 scenarios: -UPGRADING ---------- + * To Upgrade your Drupal site from version 6.x to 7.x + * To Update your Dupal site from one minor version to another + of Drupal 7, e.i. from 7.9 to 7.10 + +This document makes the following assumptions: -Prior to upgrading, you should ensure that: + * An upgrade is when you bring your site from one major version to next, + e.i. from Drupal 6.19 to Drupal 7.0 + * An Update is when you bring your site from one minor version to another + within the same major version e.i. from Drupal 6.18 to 6.19 or 7.0 to 7.2 + * You understand the difference between Upgrade and Update as stated above + * In the notation drupal-x.y.tar.gz, x = Major and y = Minor version + * The "Don't hack core" principle is respected. If you don't understand + why or what it is, please see http://drupal.org/node/144376 + + In short it means, if you have modified core files outside of the sites/ + directory (e.i. .htaccess or robot.txt) you are assumed to know what you + are doing and how to re-apply them outside of these instructions. This + document may advice you though when or when not to do it. - * 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. + * This document assume Drupal is installed in the web root, on Apache + web server also known as the Document Root. If you have installed Drupal + in a subdirectory of your web root, you need to adjust accordingly when + the document mentions web root, Document Root or Drupal Installation + directory. The same are tru for paths, like sites/default/ always start + from the directory Drupal is installed in to. -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. + * You have taken a full back up of your web sites files and directories. + + * You have read through this entire document, before you start to + update/upgrade your site. -Let's begin! +----------------------------------------------------------------------------- +HOW TO UPDATE BETWEEN TWO MINOR VERSIONS OF DRUPAL 7 (e.i. from 7.9 TO 7.10) +----------------------------------------------------------------------------- +If you are looking for instructions to upgrade your site from Drupal 6 to +Drupal 7, you will find them further down in this document. -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. +To perform the update: - 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. +1. Log in as a user with the permission "Administer software updates" + enabled. This should be a user belonging to the ADMINISTRATOR ROLE, + preferably user ID 1 (also known as the site maintenance account). + IMPORTANT! Do not close your browser until the final step is complete. +2. In Navigation menu, go to Administer->Site configuration->Site maintenance + and change Site status to "Off-line". + +3. Back up your Drupal database in case something goes wrong. In depth + information about this can be found here: + http://drupal.org/upgrade/backing-up-the-db + +4. Remove all old core files and directories from the Drupal installation + directory, EXCEPT for the sites/ directory and any custom created + directory and file outside of it. If you have made modifications to files + like .htaccess and robot.txt you need to re-apply these modifications, + taken from your backup, after the new files are in place. + +5. Download the latest Drupal release from http://drupal.org/ to a + directory outside of your web root. The files are in .tar.gz format and + can be extracted using most compression tools. + + On a typical Unix/Linux command line, assuming you have shell access, use: + + 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. Move the contents inside of that directory into your + web server's document root or your public HTML directory: + + mv drupal-x.y/* drupal-x.y/.htaccess /path/to/your/web_root + + 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/web_root + + Replace user and group with the once your webserver is running as. + + On Windows you may prefere to download from http://drupal.org/ using your + web browser, unpack the files with a program like winrar or 7-zip and then + use a ftp client to upload the files to your web root. + + If using a hosting panel like Cpanel you may need to follow their + specific instruction of how to put your files on your site. + +6. If you need to re-apply any custom modifications e.i. to .htaccess + this is a good time for it. + +7. 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 sites/default/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; + +8. Finally, return to Administer->Site configuration->Site maintenance + and change Site status to "Online" so your visitors may resume + browsing. + +----------------------------------------------------------------------------- + HOW TO UPGRADE FROM DRUPAL VERSION 6.x TO 7.x +----------------------------------------------------------------------------- +If you need to upgrade from version 5.x you first have to upgrade to +version 6.x following the instructions in that release. + +Before starting the upgrade process, ensure that: + + * You have updated to the latest minor version of your current release. + * 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 and + themes checking which have a Drupal 7 compatible version and which + have not. It's suggested you make a list of both categories. + + - For contributed modules, visit http://drupal.org/project/modules and + change 'Filter by compatibility:' to 7.x, then click 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 the modules project page for any special procedure to follow + when upgrading to Drupal 7 version, read any upgrade.txt files found + in the new versions of the module. If it's a CCK module, be sure to + also read the upgrade.txt file supplied with the Drupal 6 version. + + - If you find a conflict with this document, consult the Drupal + community as you may not be the first facing the situation. + + * Do the same as above with all your non core themes: + + - For contributed themes, visit http://drupal.org/project/themes and + change 'Filter by compatibility:' to 7.x, then click 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. + + - Take note of any special procedure to follow when upgrading, as and if + stated on the themes page. If it conflict with this document consult + the Drupal community as you may not be the first facing the situation. + + * At this point you may judge if an upgrade will render the result you + expect? If not, you could find out if you can contribute in some way to + help the incompatible module getting there. + +To perform the upgrade: + +1. Log in as a user with the permission "Administer software updates" + enabled. This should be a user belonging to the ADMINISTRATOR ROLE, + preferably user ID 1 (also known as the site maintenance account). + IMPORTANT! Do not close your browser until the final step is complete. + +2. In Navigation menu, go to Administer->Site configuration->Site maintenance + and change Site status to "Off-line". + +3. In case something goes wrong and you need to re run the upgrade procedure, + back up your database and your old configuration file(s). + + For a single site setup, the configuration file is at + sites/default/settings.php + For multisite configurations, the configuration file is located in a structure like the following: @@ -35,43 +187,103 @@ sites/sub.example.com.path/settings.php More information on multisite configuration is located in INSTALL.txt. + + Remove the sites/default/default.settings.php file as it will be replaced + with a fresh and clean copy from the new release. Leaving it there may + block the new file in case a read only bit is set. + + In depth information about backup can be found here: + http://drupal.org/upgrade/backing-up-the-db -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. +4. If using any other theme than the core theme Garland, + In Navigation menu, go to Administer->Site building->Themes to get a page + listing all available themes. At bottom of page, click the + "Reset to defaults" button. This will deactivate all themes except for + Garland and also reset the Administration theme to system default. -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). +5. In Navigation menu, go to Administer->Site building->Modules and disable + all modules not listed under 'Core - required' or 'Core - optional'. You may + have to make several turn due to some modules can't be disabled while others + still depend on them. -4. If using a custom or contributed theme, switch to a core theme such as - Bartik or Garland. +6. Remove all files and directories from the Drupal installation directory, + EXCEPT for the sites/ directory which we will deal specially with below. + You should also keep any custom created directory and files outside of + sites/, as an example, if you still have a files/ directory in + drupal root, originating from an older setup, leave it in place. + + It may appear to be in error leaving your old Drupal 6 modules in + sites/all/modules as they are incompatible with Drupal 7? In fact, it + doesn't matter and you are free to remove them if you like. The benefit + of leaving them is that Drupal 7 will list them and show their dependencies + while they can't be enabled. This may help you in the process of upgrading + them in a non conflicting order. + + However, modules not yet installed are listed too, hence to avoid confusion + we recomend to remove all such modules. Be careful though, because if you + once have enabled a module it also got installed and may have tables and + configuration data in the database. To simply disable it doesn't mean it + automatically gets uninstalled. Hence, to avoid problems further down + the road you should make an explicit uninstal of every module you don't + want to carry over to Drupal 7. + + Certain modules have also moved in to Core in Drupal 7 and you are + recommended to also remove these, and this is IMPORTANT, you are not + supposed to uninstall any of these as Core or complementary modules may + make use of the data. The modules moed in to Drupal 7 Core are: + adminrole, cck, token + + You probably also want to remove contributed themes in sites/all/themes + while you probably want to keep any custom theme in same directory for + manual upgrade later. + +7. Download the latest Drupal 7 release from http://drupal.org/ to a + directory outside of your web root. The files are in .tar.gz format and + can be extracted using most compression tools. + + On a typical Unix/Linux command line, use: -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). + wget http://drupal.org/files/projects/drupal-x.y.tar.gz + tar -zxvf drupal-x.y.tar.gz -6. Remove all old files and directories from the Drupal installation directory. + This will create a new directory drupal-x.y/ containing all Drupal files + and directories. Move the contents inside of that directory into your + web server's document root or your public HTML directory: -7. Unpack the new files and directories into the Drupal installation directory. + mv drupal-x.y/* drupal-x.y/.htaccess /path/to/your/web_root + + 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/web_root + + Replace user and group with the once your webserver is running as. -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. + On Windows you may prefer to download from http://drupal.org/ using your + web browser, unpack the files with a program like winrar or 7-zip and then + use a ftp client to upload the files to your web root. -9. Verify the new configuration file to make sure it has correct information. + If using a hosting panel like Cpanel you may need to follow their + specific instruction of how to put your files on your site. + + Note that as long as you don't change the directory structure and apply + the files in the root folder, none of your old directories or files you + want to preserve are going to be overwritten. + +8. If you need to re-apply any custom modifications e.i. to .htaccess + this may be a good time for it. However, unless you are an expert and + really know what you are doing, we suggest you wait until your new site + is up running and confirmed to run properly. + +9. Verify the configuration file sites/default/settings.php to make sure it + has correct information for connection to your database. + 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. - Note: if you are unable to access update.php do the following: + Note: if you get an 'Access Denied' error do the following: - Open your settings.php file with a text editor. @@ -81,34 +293,35 @@ - Once update.php is done, you must change the settings.php file back to its original form with $update_free_access = FALSE; -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. +12. Start to re-enable your non core modules and update their database tables + one by one, following this procedure: + - check your notes if any special upgrade demands 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 watch any message output. + + Following this procedure for every module may be time consuming if you + have many modules to re-enable. You make do more than one module at the + time before running update.php, especially if they are unrelated or don't + have dependencies. However, it also increase the likelihood something will + go wrong. You have to lean on your own judgement here. - - For contributed modules, check http://drupal.org/project/modules - for the version of a module matching your version of Drupal. +13. If applicable return the site to its original theme following the same + procedure as in #12 except for using sites/all/themes/ as base. - - For custom modules, review http://drupal.org/update/modules to - ensure that a custom module is compatible with the current version. +14. Check so everything appears to work. + + If you run into problem consult the Drupal community by doing a search + in the Forum and the Issue queue. A good search tag to use is + "D7 upgrade path" which may generate more relevant hits then just "Upgrade". -12. Re-enable custom and contributed modules and re-run update.php - to update custom and contributed database tables. +15. Finally, if all is well we need to revert the Site Status: "Off-line" we + sat in #2 but in Drupal 7 this have changed. We now need to visit + Administer->Configuration->Maintenance mode (you'll find the latter in + the Development block) and there un-tick "Put site into maintenance mode" + checkbox, click "save Configuration" and your visitors may resume + browsing again. -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. - - - For contributed themes, check http://drupal.org/project/themes - for the version of a theme matching your version of Drupal. - - - For custom themes, review http://drupal.org/update/theme to ensure - that a custom theme is compatible with the current version. - -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). - -For more information on upgrading, visit +-------------------------------------- +For more in depth information on upgrading, visit the Drupal handbook at http://drupal.org/upgrade