[documentation] [Documentation bug] Suggest clarifications of
update.txt for Drupal 5.0
bart
drupal-docs at drupal.org
Thu Sep 7 21:52:50 UTC 2006
Issue status update for
http://drupal.org/node/82488
Post a follow up:
http://drupal.org/project/comments/add/82488
Project: Documentation
Version: <none>
Component: Installation
Category: bug reports
Priority: normal
Assigned to: Anonymous
Reported by: bart at drupal.energybulletin.org
Updated by: bart at drupal.energybulletin.org
Status: active
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
* Disable contributed modules in your Drupal site and revert to a
default theme (bluemarine). Make a list of contributed modules and
themes.
* 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.
* 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.
* Remove all the old Drupal files that came with the original
installation. Do not remove added files, such as any user-uploaded
files.
* 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.
* 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.
* Run update.php by accessing http://<your_site_url>/update.php> with
your browser. After the update has completed, you can close the
browser.
* 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
bart at drupal.energybulletin.org
Previous comments:
------------------------------------------------------------------------
Tue, 05 Sep 2006 10:16:18 +0000 : bart at drupal.energybulletin.org
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.
------------------------------------------------------------------------
Wed, 06 Sep 2006 20:10:35 +0000 : bart at drupal.energybulletin.org
After consulting the Drupal books by Mercer and Douglass, I created the
following suggested revision to upgrade.txt. - Bart
* Disable contributed modules in your Drupal site and revert to a
default theme. Make a list of contributed modules and themes.
* 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.
* Access your Drupal site, and log on as the user with user ID 1 (the
first user you added during the installation - the administrator).
* Remove all the old Drupal files that came with the original
installation. Do not remove added files, such as any user-uploaded
files.
* Unpack the new Drupal files into the directory from which you run
Drupal.
* 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.
* Run update.php by accessing http://<your_site_url>/update.php.
* Download and add contributed modules and themes for your site, once
they have been upgraded for the new release of Drupal.
------------------------------------------------------------------------
Wed, 06 Sep 2006 20:14:45 +0000 : sepeck
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
------------------------------------------------------------------------
Wed, 06 Sep 2006 20:20:52 +0000 : bart at drupal.energybulletin.org
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
------------------------------------------------------------------------
Wed, 06 Sep 2006 23:28:25 +0000 : Gary Feldman
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
------------------------------------------------------------------------
Thu, 07 Sep 2006 00:38:25 +0000 : sepeck
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.
------------------------------------------------------------------------
Thu, 07 Sep 2006 05:15:38 +0000 : bart at drupal.energybulletin.org
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
------------------------------------------------------------------------
Thu, 07 Sep 2006 14:21:34 +0000 : Gary Feldman
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
------------------------------------------------------------------------
Thu, 07 Sep 2006 17:01:06 +0000 : sepeck
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.
------------------------------------------------------------------------
Thu, 07 Sep 2006 18:03:03 +0000 : drumm
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.
More information about the documentation
mailing list