Beta-breaker: UPGRADE.txt is missing some instructions

Seems logical to me.

Initial patch attached.

Nice. I made a few changes.

1. Rolled in the bug fix from http://drupal.org/node/152964, which highlights a critical issue where following these instructions that can cause you to completely hose your site. Not good!

2. Re-numbered all of the steps accordingly.

3. Made some other minor language tweaks (re-enable, rather than re-install).

More...

1. For some reason we were wrapping these at like 64 characters, rather than 80. Changed. Also removed some double-spaces between sentences. We use single.

2. In doing so, it forced me to actually read the entire file, and I found another nasty surprise -- after deleting your Drupal directory and replacing it with a brand new one, it tells you:

 If the original .htaccess or robots.txt files have
    been modified, copy the backed up versions of these files to the
    installation directory as well.

Would've been nice to have known that I was supposed to back up these files *before* I deleted everything, hm? ;) Added another sentence to step 1.

3. The part about changing the variable had periods on the ends of sentences, so it would read:

Change it to $update_free_access = TRUE;.

Even though my inner grammar geek wants these to be complete sentences, of course putting a period there will kill someone's site. :P Removed.

Even better.

Shouldn't we modify step #1 to include mention of the new file default.settings.php? Currently, there is just a mention of settings.php.

Good idea. How's this?

    Note: for a single site setup the configuration file is the "settings.php"
    file located at sites/default/settings.php. The default.settings.php file
    contains a clean copy for restoration purposes, if required.

I gotta go work on some other stuff now, but if you find any other problems and/or want to tweak the text more, feel free!

I added sections regarding custom module and custom theme code that may need updating, including references to http://drupal.org/update/modules and http://drupal.org/update/theme .

iirc there's been security/bug fixes in .htaccess - and some people will have sites than run from 4.5 or 4.6 where there must've been more changes.

so:

 If the original .htaccess or robots.txt files have
    been modified, copy the backed up versions of these files to the
    installation directory as well.

Means they'd be overwriting those security and/or bug fixes - could keep going forever potentially. Same goes for settings.php as well.

I'd change it to

If you have modified versions of the original .htaccess or robots.txt files, copy any changes from your backed up versions to the installation directory.

Then maybe a link to relevant drupal.org issues for changes if they're known off-hand.

Let's fix this to include in the beta! I read the patch and noticed the following:

- step 3: I would not say "mask errors". This is not the real purpose... "let the database updates run without interruption" might be a better explanation. You are not masking errors, but avoiding them, this is a pretty important distinction.
- step 8: I am with catch that custom .htaccess, robots.txt and settings.php changes should not be restored by restoring the file itself, but copying over the changes themsefs. Although I don't think catch's suggestion is clear enough. A more verbose explanation would be fine.
- step 10: **No way!** I have new code on an old database, so it is impossible to go in and enable modules, the site is broken and putting out errors on all pages... Why would I do it anyway? We used to suggest updating core first and then contrib stuff in a second update.php run, right? Why disable modules, if after adding them back, we enable them again? Also we copy back stuff in step 8, and only suggest to ensure that the modules are up to date *after* we said they should be enabled. This is messy.

It would be great to fast-track a fix for this issue, being a true beta-breaker.

I don't think this is perfect yet, but it's a starting point for further refinement:

New step 3:

3.  Place the site in "Off-line" mode, to let the database updates run without
    interruption and avoid displaying errors to end users of the site.

(Note: it actually does both. As soon as you update core to a major version there are errors all _over_ the place about undefined functions, missing tables, etc. But I agree that the first and foremost reason is so that database updates run without interruption.)

New step 8:

8.  Copy the backed up "files" and "sites" directories to the Drupal
    installation directory. If other system files such as .htaccess or
    robots.txt were customized, re-create the modifications in the new versions
    of the files using the backups taken in step #1.

New beginning of step 10:

10. Run update.php by visiting http://www.example.com/update.php (replace
    www.example.com with your Drupal installation's domain name and path). This
    step will update the core database tables to the new Drupal installation.

New step 11:

Ensure that the versions of all custom and contributed modules and themes
    match the new Drupal version to which you have updated. For a major update,
    such as from 5.x to 6.x, modules from previous versions will not be
    compatible and updated versions will be required.

      - For contributed modules, check http://drupal.org/project/Modules
        for the version of a module matching your version of Drupal.

      - For custom modules, review http://drupal.org/update/modules
        to ensure that a custom module is compatible with the current
        version.

New Step 12:

12. Re-enable custom and contributed modules and re-run update.php to update
    custom and contributed database tables.

(following items renumbered accordingly.)

This truly gets better. But people are still asked to copy back their "sites" directory just before running update.php, which means they copy back their old modules. This should not have a side effect if they properly disabled all modules. But if not, they are better off not having those modules hanging around there.

Also it might be quite "disastrous" (psychologically at least) to go through all this update hassle and then find out that some required contrib module is not updated. So having this "ensure you have updated stuff" note at the end might be too late.

Otherwise this is looking real nice, thanks for keeping up the effort.

I had problems staying logged in as uid 1, this might be an artefact of my buggy test environment but I would mention the free_access variable in settings.php esp because it's new.

I would be cautious with copying back sites, you might have a module lurking in there forgotten to switch off causing havoc.

I would urge people (for the reasons Gabor mention) to read the whole thing before starting.

Thanks for the feedback, Gabor!

I'm out for a few hours, so if someone could take a stab in my absence so we don't further hold up the beta, that'd be great. Otherwise, I'll re-roll this evening.

New patch attached, based off webchick's latest. Includes a pre-amble about what they should do prior to starting the UPDATE, some revised text tweaks, and a link to where Off-line mode lives (which needs to be checked by someone with D6 - I don't have a copy so used D5's location). I think including Off-line (and Online)'s URL is important since, unlike custom themes and modules, it's a relatively hidden use-it-once-then-forget-it feature.

(Also, note the use of ?q= in the Off-line URL was deliberate, to prevent the need for Clean URL considerations.)

First off, there's a referential error in step #2. It says that you access update.php in step #11, and it's actually step #10.

And in reading through the patched version, and it might be good to mention in Step #2 that there is a workaround if you don't have access to log in as UID = 1. Say for example that you have someone else set up your Drupal site, but eventually you take over control and want to update the site yourself -- there seems to be a workaround to this scenario, but it isn't mentioned until Step #10.

Here's Step #2:

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 (step #11) which can only be run by this
    user. Do not close your browser until the final step is complete.

And isn't this special note in Step 10 referring to the fact that you wouldn't have access to update.php when you're not UID = 1?
And if so, then isn't it actually possible to run update.php without being UID=1 as long as you make this change?

    Note: if you are unable to access update.php do the following:

      - Open your settings.php with a text editor.

      - There is a line that says $update_free_access = FALSE; Change it to
        $update_free_access = TRUE;

      - As soon as the update.php script is done, you must change the
        settings.php file back to its original form with
        $update_free_access = FALSE;

So in step #2, it isn't entirely true that update.php "can only be run by this user."

So here' what I would propose changing Step #2 to:

2.  If possible, log on as the user with user ID 1, which is the first account
    created and the main administrator account. User ID 1 will be able to
    automatically access update.php in step #10. There are special instructions
    in step #10 if you are unable log on as UID = 1. Do not close your browser
    until the final step is complete.

Here's a patch off of Morbus Iff's latest consolidation with my suggested change for #2 included.

Re: "a link to where Off-line mode lives (which needs to be checked by someone with D6 - I don't have a copy so used D5's location)"
Yes, the link to http://www.example.com/?q=admin/settings/site-maintenance is correct for D6.

Oops. I said "UID=1" in my proposed change in Step #2 -- instead of "user ID 1"
Fixed in this patch.

I can't repatch right now, but error Kent: "#10 if you are unable log on". Missing "to".

Thanks Morbus
New patch adds missing "to."
Now correctly reads "#10 if you are unable to log on"

As far as I see, all our concerns are addressed, so committed. Thanks!