[documentation] [Documentation bug] Suggest clarifications of update.txt for Drupal 5.0

Thu Sep 7 05:15:38 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

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

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.