I'm a newbie trying out the process for upgrading to Drupal 5.0. The upgrade.txt file is concise but it is confusing for people who haven't gone through the process. Below I reproduce the existing version of the update.txt file, then I give a suggested re-write of the steps to make them clearer. I've also included questions that arose in my mind as I tried the process. I may have misunderstood how the process is supposed to work. -Bart

--------------- EXISTING VERSION -----------

// $Id: UPGRADE.txt,v 1.3 2006/07/10 19:27:52 dries Exp $

UPGRADING
---------

1. Backup your database and Drupal directory - especially your
sites-directory which contains your configuration file and
any added modules and themes.

2. Log on as the user with user ID 1.

3. Remove all the old Drupal files then unpack the new Drupal
files into the directory that you run Drupal from.

4. Modify the new configuration file to make sure
it has the latest and correct information.

5. Run update.php by visiting http://www.example.com/update.php.

--------------- SUGGESTED RE-WRITE and QUESTIONS -------------

1. Back up your database and the directory containing the existing Drupal files. Particularly important to back up is the configuration file (DRUPAL_DIRECTORY/sites/default/settings.php). It's also important to have any added themes and modules backed up; these are located in the themes and modules sub-directories.

QUESTION: Why is it important to back up the added themes and modules? I don't see that they are used in the upgrade process. Is it just for insurance in case the upgrade fails?

2. Access your Drupal site, and log on as the user with user ID 1 (the first user you added during the installation - the administrator).

QUESTION: Do you mean the user should log on to Drupal -- even though he or she is going to be deleting all the Drupal files?

3. Remove all the old Drupal files, and then unpack the new Drupal
files into the directory from which you run Drupal.

QUESTION: Do you mean delete EVERYTHING in the Drupal directory? All files and sub-directories? Including the modules and themes directories? If so, maybe add a sentence explaining it: "The added modules and themes will be re-added during the update process."

4. Edit the new configuration file (DRUPAL_DIRECTORY/sites/default/settings.php) to make sure it has the latest and correct information. For example, you will probably re-set the values for $db_url and $base_url. Check the old configuration file in the backup you made for the proper settings.

5. Run update.php by visiting http://YOUR_SITE_URL/update.php.

Comments

bart@drupal.energybulletin.org’s picture

bart@drupal.energybulletin.org commented

After consulting the Drupal books by Mercer and Douglass, I created the following suggested revision to upgrade.txt. - Bart

  1. Disable contributed modules in your Drupal site and revert to a default theme. Make a list of contributed modules and themes.
  2. Back up your database and the directory containing the Drupal files. Important information for the upgrade resides in the configuration files(s), such as <drupal_directory>/sites/default/settings.php.
  3. Access your Drupal site, and log on as the user with user ID 1 (the first user you added during the installation - the administrator).
  4. Remove all the old Drupal files that came with the original installation. Do not remove added files, such as any user-uploaded files.
  5. Unpack the new Drupal files into the directory from which you run Drupal.
  6. Edit the new configuration file(s), such as <drupal_directory>/sites/default/settings.php, to make sure it has the latest and correct information. For example, you will probably re-set the values for $db_url and $base_url. Check the old configuration file in the backup you made for the proper settings.
  7. Run update.php by accessing http://<your_site_url>/update.php.
  8. Download and add contributed modules and themes for your site, once they have been upgraded for the new release of Drupal.
sepeck’s picture

sepeck commented

Rather then relying on potentially copyrighted material in a book, perhaps we can use and distill the information that already exists in the handbook on Drupal.org?
http://drupal.org/upgrade/tutorial-introduction
or from the Best practices
http://drupal.org/node/29161

bart@drupal.energybulletin.org’s picture

bart@drupal.energybulletin.org commented

That would be another good source of information.

To clarify, though, the text was not copied from the published books. The concepts were absorbed and put in my own language, so there is no infringement of copyright.

-Bart

Gary Feldman’s picture

Gary Feldman commented

This sequence seems wrong:

2. Log on as the user with user ID 1.

3. Remove all the old Drupal files then unpack the new Drupal
files into the directory that you run Drupal from.

as does the corresponding sequence in the first followup. The answer to

QUESTION: Do you mean the user should log on to Drupal -- even though he or she is going to be deleting all the Drupal files?

is surely no. If you deleted all the old Drupal files then you'd be logged on to nothing.

I believe that item 2 should be along the lines of:

"Connect to your Drupal web site using a mechanism for managing files (FTP, remote shell, a file manager provided by your ISP, etc.). If you have remote shell access, you're better off copying the compressed tar file to your site and unpacking it there, but if not, you'll have to unpack it locally and then use FTP or similar to copy the directories and files."

Gary

sepeck’s picture

sepeck commented

Incorrect. You MUST logon onto your Drupal site BEFORE you remove and replace the files. This is how upgrades have worked for a very long time.

You can bypass the session check but this requires editing the update.php file where this is documented.

bart@drupal.energybulletin.org’s picture

bart@drupal.energybulletin.org commented

Gary, it seemed counter-intuitive to me too -- replacing the Drupal files while you're logged onto the site, but apparently that's the way it is. As long as you're not clicking on links or issuing commands through the browser, the files aren't being accessed.

I like the idea of referencing the online documentation cited by sepeck. Maybe add a few lines like the following at the end of upgrade.txt:

For more detailed information, see the Drupal online handbooks:
http://drupal.org/upgrade/tutorial-introduction
http://drupal.org/node/29161

Gary Feldman’s picture

Gary Feldman commented

Why must you logon?

If the point is to set up the session cookies, doesn't that imply that you better not exit the browser or do anything else that might delete the cookies? If so, that needs to be said, because it's not unreasonable to want to close the browser if you're going to switch to an FTP client for the next step. In general, counterintuitive steps should be explained, even if it's in a footnote or sidebar.

How does it work if you're running multiple servers off of one installation tree? If it's multiple sites at the same domain (e.g. http://example.com/site1 and http://example.com/site2)? I've been using the latter configuration on my test system, and I'm reasonably certain I've never been able to be signed into multiple sites at once.

Is there a way to recover if you skip this step?

Better yet, can that requirement be removed? The fewer steps, and the fewer gotchas, the easier it will be (but that's for another issue).

Gary

sepeck’s picture

sepeck commented

Drupal upgrades have used this update method for several years now. Please review the links provided. I'd like to keep it fairly simple if at all posible.

You MUST logon because there is security built into the process.

You can bypass the session check but this requires editing the update.php file where this is documented.

As to multi-site, I open all the site's in my web browser and logon to all of them with UID1. Then follow the update steps. Replace files, etc... I am unsure why you would not be able to logon to multi sites in your installation.

drumm’s picture

drumm
he/him
Location NY, US
commented

You can login after updating the files, but will probably encounter stacks of PHP warnings and such that may or may not be ignorable. This happens because the updated PHP code is assuming that the database is updated.

Logging into multiple sites on the same server at once can be achieved by changing the PHP configuration directives (in php.ini, .htaccess, or settings.php) relating to how session cookies are handled. We don't explicitly set these so it can be inconsistent when using different server environments. I haven't bothered to actually figure out what specific the configurations are. To prevent session hijacking, Drupal changes the session id on logout and login. If the same cookie is used to store the session id on two different sites, then the second site also sees the session id change and loses the logged-in session.

bart@drupal.energybulletin.org’s picture

bart@drupal.energybulletin.org commented

Revised version (taking into account the comments in this thread):

BEGIN

Below is an outline of the steps to upgrade Drupal to a new version. We strongly recommend that you read the complete information about upgrading Drupal available at drupal.org. For example:
http://drupal.org/upgrade/tutorial-introduction
http://drupal.org/node/29161

  1. Disable contributed modules in your Drupal site and revert to a default theme (bluemarine). Make a list of contributed modules and themes.
  2. Back up your database and the directory containing the Drupal files. Important information for the upgrade resides in the configuration files(s), such as <drupal_directory>/sites/default/settings.php.
  3. Access your Drupal site, and log on as the user with user ID 1 (the first user you added during the installation - the administrator). DO NOT CLOSE THE BROWSER UNTIL THE UPGRADE IS COMPLETE.
  4. Remove all the old Drupal files that came with the original installation. Do not remove added files, such as any user-uploaded files.
  5. Put the new Drupal files into the directory structure where the old files resided. A simple way to do this is to unpack the Drupal upgrade package in the directory from which you run Drupal.
  6. Edit the new configuration file(s), such as /sites/default/settings.php, to make sure it has the latest and correct information. For example, you will probably re-set the values for $db_url and $base_url. Check the old configuration file in the backup you made for the proper settings.
  7. Run update.php by accessing http://<your_site_url>/update.php> with your browser. After the update has completed, you can close the browser.
  8. Download and add contributed modules and themes for your site, once they have been upgraded for the new release of Drupal.

The upgrade information at drupal.org explains how to recover from errors and how to practice the upgrade on a test site (recommended for production sites).

END

------------------------------------------------------

The background information from Neil (drumm), Steven (sepeck) and Gary is very good, but I think the right home for it is in the online handbooks. There the information can be updated easily. Background information and corner cases can be organized so that they don't cause confusion.

The beauty of the humble update.txt file is that it

  • is short enough so that a reader can understand the whole process quickly
  • serves as a reminder to experienced people
  • points people online for the complete story

.If this file tries to cover too much, it becomes unwieldy and confusing.

-Bart

mfer’s picture

mfer commented
Status: Active » Closed (duplicate)

Some good suggestions. Please see http://drupal.org/node/102011 where there is a patch to this. All feedback is appreciated.

Chill35’s picture

Chill35 commented

Disable contributed modules in your Drupal site.

That's something I forgot to do once and it created many problems for me. It's very important! And we're not told that we have to do that.

I like the improvements a lot.

Some people seem to forget that MOST people don't spend their time updating and installing Drupal, they'll do one or the other once in a while so they forget how they did it before.

dokumori’s picture

dokumori commented
Project: Documentation » Drupal core
Version: » 7.x-dev
Component: Installation » documentation

Changed the component to reflect the new component categorization. See http://drupal.org/node/301443
-dokumori