The UPGRADE.txt file in the beta 2 lists a 5 step method to upgrade drupal. While, this 5 step method seems fairly straight forward and to the point a number of people have complained that it is unclear. This unclarity has led to upgrade issues.

In an attempt to make the upgrading more user friendly the UPGRADE.txt file needs to have some additional detail added.

Some of the concerns have surrounded core vs non-core modules, the difference between overwriting a drupal install vs removing the files and putting new files in it's place, and a discrepancy between the UPGRADE.txt file and http://drupal.org/upgrade.

CommentFileSizeAuthor
#30 upgrade_1.patch1.87 KBChrisKennedy
#29 upgrade_0.patch1.48 KBChrisKennedy
#28 upgrade.patch1.48 KBChrisKennedy
#24 upgrade.txt4.patch3.72 KBmfer
#20 upgrade.txt3.patch3.62 KBmfer
#13 upgrade.txt2.patch3.35 KBmfer
#10 upgrade.txt1.patch2.83 KBmfer
#4 upgrade.txt.patch2.62 KBmfer
Support from Acquia helps fund testing for Drupal Acquia logo

Comments

mfer’s picture

mfer CreditAttribution: mfer commented

I didn't write this to complain.... at some point in the next day I should have a proposed patch with some word smithing.

Steel Rat’s picture

Steel Rat CreditAttribution: Steel Rat commented

For me the process is unclear for the following reasons:

1) No mention of what to do with modules.

2) No specifics on what to remove/replace.

It seems like a lot of assumptions are made about who might be performing upgrades. If the process is essentially the same as upgrading from 4.6 to 4.7, then all those steps should be included, in detail, in the 5.0 upgrade docs included with the download.

This was my first Drupal upgrade attempt, and it did not go well, lol. The primary reason being, no mention of what to do with modules.

Heine’s picture

Heine CreditAttribution: Heine commented
Version: 5.0-beta2 » 5.x-dev
mfer’s picture

mfer CreditAttribution: mfer commented
Status: Active » Needs review
FileSize
upgrade.txt.patch2.62 KB

This is my first go at a patch with more detailed instructions.

I am wondering if there needs to be something written about contributed themes like number 4 for contributed modules.

The text reads:

// $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
   added modules and themes, any contributed modules
   in your modules-directory, and your files-directory which 
   contains uploaded files.

2. Log on as the user with user ID 1.  (User ID 1 is the first 
   account created and the main administrator account.)  User
   ID 1 needs to be logged in so that you have a session cookie 
   for user ID 1 in your browser when you access the new version
   of the update.php file which can only be run by user ID 1.
   
   Note: If you are unable to access update.php as user ID 1
   do the following:

   - With a text editor find the update.php file on your system. 
   It should be in the main Drupal directory that you installed 
   all the files into.
   
   - There is a line near top of update.php that says 
   $access_check = TRUE;. Change it to $access_check = FALSE;.
   
   - As soon as the script is done, you must change the update.php 
   script back to its original form to $access_check = TRUE;.

3. Remove all of the files from the old Drupal installation
   and unpack the new Drupal files into the directory you run
   Drupal from.  Copy the contents of your files-directory from 
   your backup to your newly upgraded Drupal installation.
   
4. (Optional) Re-install contributed modules.

   Note:  Make sure the version of a module matches your 
   version of Drupal.  Modules from previous versions are 
   not compatible with with the current version.  Check 
   http://drupal.org/project/Modules for the version of a
   module to match your version of Drupal.

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

6. Run update.php by visiting http://www.example.com/update.php.
   This step will update the database to the new Drupal
   installation.

For more information on upgrading visit the Drupal handbook at
http://drupal.org/upgrade
Dries’s picture

Dries CreditAttribution: Dries commented

Overall this looks like an improvement, but the bit about cookies/session IDs seems too technical to me -- and doesn't really add value.

bobbia’s picture

bobbia CreditAttribution: bobbia commented

When you visit http://www.example.com/update.php, you get a "page not found" ;) . I would suggest the following to item 6:

6. Run update.php by going to your home page, then adding /update.php to the end of your home page's URL (for example, http://www.example.com/update.php). You should see a page called "Drupal database update". Follow the steps on this page. This step will update the database to the new Drupal installation.

ChrisKennedy’s picture

ChrisKennedy CreditAttribution: ChrisKennedy commented

Here's a question for you - why don't we have a menu item in the "Site building" section with something like "Site update" that links to update.php? Then we could say something like "Go to Administration -> Site Building -> Site update" to update your database. It could be set to show only when uid == 1.

pcwick’s picture

pcwick CreditAttribution: pcwick commented

I think this is looking good. Some thoughts.

- The "configuration file" referred to in 1 and 5 seems to be most often referred to other Drupal documentation and in the forums by its title "settings.php" and I think this would be preferable in this document.

- I think the document will read more smoothly if the "Note" about editing "update.php" follows item 6.

- In item 4, I think it is more accurate to say "Modules from previous versions may not be compatible with the current version." Note there is an extra "with" in this sentence.

- I believe I have seen mentioned that the module list in 5.0 will indicate when new module versions are available and I wonder if this will change the instructions in 4?

- In my way of thinking 3 contains three steps. I prefer:

3. Remove all of the original files and directories from the Drupal installation directory.

4. Unpack the new Drupal files and directories into the Drupal installation directory.

5. Copy the backed up "files" and "sites" directories to the Drupal installation directory. If the original .htaccess or robots.txt files have been modified, copy the backed up versions of these files to the installation directory directory as well.

- From time to time, I read suggestions that one disable contributed modules prior to upgrade. I wonder if this is something that should be done every time, only if there are problems, or never?

pcwick’s picture

pcwick CreditAttribution: pcwick commented

Drupal 5.0 now has the sites/all/modules and sites/all/themes directories for contrib and custom modules and themes. I think this document should indicate that contrib and custom modules and themes should be reinstalled in these directories rather than in /modules and /themes directories.

See: http://drupal.org/node/101455

mfer’s picture

mfer CreditAttribution: mfer commented
FileSize
upgrade.txt1.patch2.83 KB

@ChrisKennedy - Having a link in the admin pages at "Go to Administration -> Site Building -> Site update" for user ID 1 sounds like a good idea. Though, that is not what this issue is for. It would be good to add that as a feature request.

@pcwick - Modules from previous versions of drupal ARE NOT compatible with drupal 5. For one, they did not contain a modulename.info file which is needed to even enable the module. Though, a change like this may not be the case in the future and modules may be compatible. But, drupal is not designed for backward compatibility.

Also, I don't think module installation instructions should go in the upgrade.txt file. While, the best place for contributed modules may be in the sites directory I think the UPGRADE.txt file should be just the steps needed to upgrade. We don't want to much information in the UPGRADE.txt file

Here is an updated version based on some feedback:

// $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
   added modules and themes, any contributed modules
   in your modules-directory, and your files-directory which 
   contains uploaded files.

2. Log on as the user with user ID 1.  (User ID 1 is the first 
   account created and the main administrator account.)  User
   ID 1 needs to be logged in so that you can access update.php 
   file (step 8) which can only be run by user ID 1.

3. Remove all of the old files and directories from the 
   Drupal installation directory.

4. Unpack the new Drupal files and directories into the Drupal 
   installation directory.
   
5. Copy the backed up files-directory and sites-directories to the 
   Drupal installation directory. If the original .htaccess or 
   robots.txt files have been modified, copy the backed up 
   versions of these files to the installation directory 
   directory as well.
   
6. Modify the new configuration file to make sure
   it has the latest and correct information.
   
7. (Optional) Re-install contributed modules.

   Note:  Make sure the version of a module matches your 
   version of Drupal.  Modules from previous versions are 
   not compatible with the current version.  Check 
   http://drupal.org/project/Modules for the version of a
   module to match your version of Drupal.

8. Run update.php by visiting http://www.example.com/update.php
   (replace www.example.com with your drupal installations domain 
   name).  This step will update the database to the new Drupal 
   installation.
   
   Note: If you are unable to access update.php as user ID 1
   do the following:

   - With a text editor find the update.php file on your system. 
   It should be in the main Drupal directory that you installed 
   all the files into.
   
   - There is a line near top of update.php that says 
   $access_check = TRUE;. Change it to $access_check = FALSE;.
   
   - As soon as the script is done, you must change the update.php 
   script back to its original form to $access_check = TRUE;.

For more information on upgrading visit the Drupal handbook at
http://drupal.org/upgrade
pcwick’s picture

pcwick CreditAttribution: pcwick commented

mfer, this doc is a significant improvement over what you started with. I appreciate your effort.

I agree with your point about keeping the document on focus and foregoing explanation of module installation.

I understand that 4.x version modules will not be compatible with 5.0. I have noticed that UPGRADE.txt is not updated each time Drupal is updated. I was thinking that "Modules from previous versions may not be compatible with the current version." would make the UPGRADE.txt accurate for future updates in which it may not be the case that all modules are incompatible with the new version of Drupal.

I noticed the following thread in which UPGRADE.txt is discussed.
http://drupal.org/drupal-5.0-beta2

In the thread, the following questions are asked by users confused by the upgrade process...

"Why do I need to log on before removing all my old files ?"

Your explanantion in 2 answers this question.

"Which configuration file ?"

I still think the title of the "configuration file" should be specified as "settings.php"

"What is the latest and correct information ?"

I also note that when I upgrade, I copy the backed up sites directory and do not usually modify settings.php though I do verify that it is correctly configured.

What do you think of this...

6. Verify that the settings.php file is correctly configured. In basic setups the file is located at /sites/default/settings.php. In basic setups it is the database url and the base url that must be correctly configured.

After 5.0, there will be users who have set up their sites with the automated installer, and when it comes time for them to upgrade, they will have never seen settings.php. I think it will reduce support requests to clarify 6 this way.

pcwick’s picture

pcwick CreditAttribution: pcwick commented

Another thing mentioned in the "Announcing Drupal 5 Beta 2" is that UPGRADE.txt is missing the instruction to disable contrib modules. I wanted to know if this advice is accurate so I posted this http://drupal.org/node/102570

Don't know if this belongs in the document or not.

mfer’s picture

mfer CreditAttribution: mfer commented
Category: task » bug
FileSize
upgrade.txt2.patch3.35 KB

Here is another update based on some more feedback. It now reads:

// $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
   added modules and themes, any contributed modules
   in your modules-directory, and your files-directory which 
   contains uploaded files.
   
   Note:  For a single site setup the configuration file is the 
   "settings.php" file located at sites/default/settings.php.
   For multisite configuration 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.site3/settings.php
   More information on multisite configuration is located in
   the INSTALL.txt file.

2. Log on as the user with user ID 1.  (User ID 1 is the first 
   account created and the main administrator account.)  User
   ID 1 needs to be logged in so that you can access update.php 
   file (step 8) which can only be run by user ID 1.

3. Remove all of the old files and directories from the 
   Drupal installation directory.

4. Unpack the new Drupal files and directories into the Drupal 
   installation directory.
   
5. Copy the backed up files-directory and sites-directories to the 
   Drupal installation directory. If the original .htaccess or 
   robots.txt files have been modified, copy the backed up 
   versions of these files to the installation directory 
   directory as well.
   
6. Verify the new configuration file to make sure it has the
   latest and correct information.
   
7. (Optional) Re-install contributed modules.

   Note:  Make sure the version of a module matches your 
   version of Drupal.  Modules from previous versions may 
   not be compatible with the current version.  Check 
   http://drupal.org/project/Modules for the version of a
   module to match your version of Drupal.

8. Run update.php by visiting http://www.example.com/update.php
   (replace www.example.com with your drupal installations domain 
   name).  This step will update the database to the new Drupal 
   installation.
   
   Note: If you are unable to access update.php as user ID 1
   do the following:

   - With a text editor find the update.php file on your system. 
   It should be in the main Drupal directory that you installed 
   all the files into.
   
   - There is a line near top of update.php that says 
   $access_check = TRUE;. Change it to $access_check = FALSE;.
   
   - As soon as the script is done, you must change the update.php 
   script back to its original form to $access_check = TRUE;.

For more information on upgrading visit the Drupal handbook at
http://drupal.org/upgrade
pcwick’s picture

pcwick CreditAttribution: pcwick commented

This looks really good to me. The new note under #1 seems clear. I imagine that newer users will now be able to upgrade with more confidence, and that fewer upgrade related support requests will be generated.

mfer’s picture

mfer CreditAttribution: mfer commented
Status: Needs review » Reviewed & tested by the community

Unless there is more input, which I openly welcome and would like, I am making this RTBC.

I would, also, like to see the handbook updated with some detail. Opened an issue on that at http://drupal.org/node/104016.

Chill35’s picture

Chill35 CreditAttribution: Chill35 commented
Status: Reviewed & tested by the community » Needs work

Important step missing that caused a lot of problems for me :

Disable contributed modules in your Drupal site and revert to a default theme (bluemarine).

Look at : http://drupal.org/node/82488

Chill35’s picture

Chill35 CreditAttribution: Chill35 commented

Also, please add this : DO NOT CLOSE THE BROWSER UNTIL THE UPGRADE IS COMPLETE, to step 2 because it's not clear that you have to log in AND leave the browser open until you're done with all the other steps up to 6, THEN you access the update.php file, from the page where you were, in the same browser.

pcwick’s picture

pcwick CreditAttribution: pcwick commented

One more...

Support providers seem to repeat the following advice:

"Upgrade sequentially, one release at a time. It is possible to skip releases, but it is not advised"

A recent example:
http://drupal.org/drupal-5.0-rc1#comment-181118

pcwick’s picture

pcwick CreditAttribution: pcwick commented

Those following this thread may have an interest in this issue which may entail additional changes to UPGRADE.txt

http://drupal.org/node/99011

mfer’s picture

mfer CreditAttribution: mfer commented
Status: Needs work » Needs review
FileSize
upgrade.txt3.patch3.62 KB

Some good points. I added another item between 1 and 2 based on http://drupal.org/upgrade/preparing-the-site

Added text to point out (on new number 3) to not close the browser window.

Here is the new 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
   added modules and themes, any contributed modules
   in your modules-directory, and your files-directory which 
   contains uploaded files.
   
   Note:  For a single site setup the configuration file is the 
   "settings.php" file located at sites/default/settings.php.
   For multisite configuration 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.site3/settings.php
   More information on multisite configuration is located in
   the INSTALL.txt file.

2. Disable contributed modules and switch to a core theme 
   (bluemarine or garland).

3. Log on as the user with user ID 1.  (User ID 1 is the first 
   account created and the main administrator account.)  User
   ID 1 needs to be logged in so that you can access update.php 
   file (step 8) which can only be run by user ID 1.  Do not
   close your browser until step 9 is complete.

4. Remove all of the old files and directories from the 
   Drupal installation directory.

5. Unpack the new Drupal files and directories into the Drupal 
   installation directory.
   
6. Copy the backed up files-directory and sites-directories to the 
   Drupal installation directory. If the original .htaccess or 
   robots.txt files have been modified, copy the backed up 
   versions of these files to the installation directory 
   directory as well.
   
7. Verify the new configuration file to make sure it has the
   latest and correct information.
   
8. (Optional) Re-install contributed modules.

   Note:  Make sure the version of a module matches your 
   version of Drupal.  Modules from previous versions may 
   not be compatible with the current version.  Check 
   http://drupal.org/project/Modules for the version of a
   module to match your version of Drupal.

9. Run update.php by visiting http://www.example.com/update.php
   (replace www.example.com with your drupal installations domain 
   name).  This step will update the database to the new Drupal 
   installation.
   
   Note: If you are unable to access update.php as user ID 1
   do the following:

   - With a text editor find the update.php file on your system. 
   It should be in the main Drupal directory that you installed 
   all the files into.
   
   - There is a line near top of update.php that says 
   $access_check = TRUE;. Change it to $access_check = FALSE;.
   
   - As soon as the script is done, you must change the update.php 
   script back to its original form to $access_check = TRUE;.

Note: Upgrading sequentially is recommended, one release at a time. 
It is possible to skip releases, but is not advised.

For more information on upgrading visit the Drupal handbook at
http://drupal.org/upgrade
Gary Feldman’s picture

Gary Feldman CreditAttribution: Gary Feldman commented

Please remove the hyphens between the directory name and the word directory. (Note, for example, that the original text for the first line says Drupal directory, not Drupal-directory.)

blogarithme’s picture

blogarithme CreditAttribution: blogarithme commented

There are no doubts about the meaning of Drupal. This is not the same thing for common words like 'files' or 'sites'. If you don’t like files-directory and sites-directory I propose to use quotes: "files" directory and "sites" directory. pcwick already use this syntax.

Make a search on this page to find when the word files means 'files' and when it means the 'directory named files' ...

mfer’s picture

mfer CreditAttribution: mfer commented

the original used the hyphen. Take a look at the current first step which says, "Backup your database and Drupal directory - especially your sites-directory which contains your configuration file and any added modules and themes." This is what I based using the hyphen on.

Though, a change to something like "files" directory may not be a bad idea.

mfer’s picture

mfer CreditAttribution: mfer commented
FileSize
upgrade.txt4.patch3.72 KB

patch adds the change from sites-directory style to "sites" directory style naming.

pcwick’s picture

pcwick CreditAttribution: pcwick commented

Ha, I've reread this doc several times, and only now caught a duplicate word in step 6, last sentence:

"...installation directory directory as well."

ChrisKennedy’s picture

ChrisKennedy CreditAttribution: ChrisKennedy commented
Status: Needs review » Needs work

The latest patch doesn't apply cleanly (hunk 1 fails at line 4). Let's try to get this committed asap so that it will be in before the release.

drewish’s picture

drewish CreditAttribution: drewish commented

It looks like part of this got committed on accident as part of #105164. take a look at: http://cvs.drupal.org/viewcvs/drupal/drupal/UPGRADE.txt?rev=1.4&view=markup

ChrisKennedy’s picture

ChrisKennedy CreditAttribution: ChrisKennedy commented
Status: Needs work » Needs review
FileSize
upgrade.patch1.48 KB

Ahh interesting, I guess I should have actually looked at why the patch failed.

In that case, here's a new patch that has the changes from #24 and #25.

ChrisKennedy’s picture

ChrisKennedy CreditAttribution: ChrisKennedy commented
FileSize
upgrade_0.patch1.48 KB

Here are a few more tweaks while I'm at it.

ChrisKennedy’s picture

ChrisKennedy CreditAttribution: ChrisKennedy commented
FileSize
upgrade_1.patch1.87 KB

Bah, correct version this time.

Dries’s picture

Dries CreditAttribution: Dries commented
Status: Needs review » Fixed

Committed to CVS HEAD.

Gary Feldman’s picture

Gary Feldman CreditAttribution: Gary Feldman commented

I certainly prefer the quotes, thanks. It's unfortunate, but necessary, that this be a plain text file, as having multiple fonts would provide better options.

Anonymous’s picture

(not verified) CreditAttribution: commented
Status: Fixed » Closed (fixed)