Fix ambiguity in upgrade.txt

Also I'm wondering whether it's actually necessary to restore the old modules before running update.php. This writer (http://becircle.com/how_upgrade_drupal_5_drupal_6_steps_3_and_4_actual_u...) says to remove the old modules:

"Please note that by restoring your 'sites' folder you will also be restoring the 'modules' folder(s) contained within it. Since this is coming from your backup, those modules folder(s) will contain modules for Drupal 5.x. Therefore, it is a good idea to empty out the modules folder(s) you have under the sites folder before moving onto the next steps. This will reduce the likelihood that you accidentally leave and old Drupal 5.x version of a module in place and forget to replace it with its Drupal 6.x version. Or worse, by leaving the folders in place, you may accidentally merge the contents of the Drupal 6.x version of a module folder with the old Drupal 5.x version."

If this is the case, what is the point of removing the modules and then putting them back only to remove them again later?

And two more small things.

We should write "the new version of Drupal" or "the updated version of Drupal" wherever we current have "your version of Drupal". In this context, the word "your" is really ambiguous and distracting since we are actually wanting to draw attention to the need for compatibility with the new version ("your" could mean both the new and old versions).

It would also be good if there were a more meaningful heading. Right now there's nothing to indicate that this is the specific upgrade.txt file that goes with Drupal 6. During my own upgrade process I've had both the d5 and d6 installers floating around and at least once I've opened up the d5 version by mistake and didn't realize it until I started getting very confused. If there was a heading that said "Drupal 6 Upgrade Instructions" it might avoid that problem (at least when it comes to upgrading to d7).

I'm bumping up the priority on this to critical, because the more I look at this, the more I realize that this file is dangerously misleading and incomplete. Following it faithfully can lead to all sorts of painful problems or outright failure.

The problem is that it very casually suggests backing up your old modules, copying in the upgrade files, putting back your modules and running update.php.

First of all, you can't just copy back your old module files. Most people will probably realize this but it still shouldn't be written this way.

Secondly, as I'm learning now as I flounder through my first major upgrade (thank God for test sites), you can't just toss in all of the upgraded modules all at once and run update.php. From everything I'm now reading this is dead wrong. According to this Best Practices page (http://drupal.org/node/29161), you should upgrade and activate modules one at time. In fact, the upgrade.txt file for CCK goes further to say specifically to leave all of the contrib modules OUT of the directory until the core modules are running and even then only copy the main CCK module over and do the upgrade for it before moving on to the other CCK modules. It goes on to say that modules get upgraded in the database when they're in the modules directory even if they are not enabled.

If this is correct, then I think this file should be fixed ASAP (as in the next point release if possible)

Ok, I've done a major rewrite of this file (see attached) which I think has addressed the above issues.

I am definitely NOT an expert on installing or upgrading Drupal, so it really needs careful review by people who actually know what they're doing. Some things I've added are definitely an improvement but other changes may be suspect.

In particular, I'm not at all sure that the way I've broken out steps for minor and major upgrades is correct.

Missed a couple of steps.

This is my first ever attempt at doing a real patch so I have no idea whether or not I've done it correctly. But here it is, for what it's worth.