Posted by mfer on December 7, 2006 at 8:35pm
| Project: | Drupal core |
| Version: | 5.x-dev |
| Component: | update system |
| Category: | bug report |
| Priority: | normal |
| Assigned: | Unassigned |
| Status: | closed (fixed) |
Issue Summary
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.
Comments
#1
I didn't write this to complain.... at some point in the next day I should have a proposed patch with some word smithing.
#2
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.
#3
#4
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
#5
Overall this looks like an improvement, but the bit about cookies/session IDs seems too technical to me -- and doesn't really add value.
#6
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.
#7
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.
#8
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?
#9
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
#10
@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
#11
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.
#12
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.
#13
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
#14
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.
#15
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.
#16
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
#17
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.
#18
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
#19
Those following this thread may have an interest in this issue which may entail additional changes to UPGRADE.txt
http://drupal.org/node/99011
#20
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
#21
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.)
#22
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' ...
#23
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.
#24
patch adds the change from sites-directory style to "sites" directory style naming.
#25
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."
#26
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.
#27
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
#28
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.
#29
Here are a few more tweaks while I'm at it.
#30
Bah, correct version this time.
#31
Committed to CVS HEAD.
#32
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.
#33