Polish UPGRADE.txt

If the instructions in the upgrade.txt are accurate and clear, the update/upgrade issue will not be really be a blocker here, as the correct meaning will be clear from the context. And, this comment seems to have come close to achieving consensus. So is this a nice to have? Sure. But a blocker? Not so much.

I suggest that this ticket focus on #2.

#3 can be hashed out in other tickets :)

It's time for the dreaded "subscribing" comment.

I just wanted to add one more vote for including instructions for changing both major and minor versions. I personally like the language of upgrade vs update, although I'm in no way stuck on it. But I think it's important that people can find both sets of instructions.

subscribe

subscribe

Has anyone double-checked that none of the core versions of contrib modules look at the contrib databases? I think that's the case, but we're implying here that modules that have gone to core can be uninstalled, we had better be certain or remove the second sentence below.

In case you already know that you will not re-enable some modules for Drupal
7.x and you no longer need their data, then you can uninstall them under the
Uninstall tab afterwards. See http://drupal.org/node/895314 for a list of
modules whose functionality has been moved into core for Drupal 7.x.

Actually, i think we had better remove that second sentence, because modules that have been moved to core like Token and CCK also live on in contrib, with parallel upgrade paths. I don't think "delete its data if it's on the list of modules incorporated into core" is a safe suggestion.

Here's a proposed "polished" UPGRADE.txt file.

There was somewhat of a mix of "don't talk about contrib modules" and "talk about modules" in this file. I decided "don't" was better, since we have a Handbook page now talking about how to upgrade modules.

So the file is a bit shorter... hopefully a bit clearer in a few places, and I think some of the comments from that other issue have been addressed. Thoughts?

Also, there were some non-ASCII characters in the last version of the file, which did not show up well on my Windows box. I replaced them with simple ASCII characters. Hopefully the patch will apply... If not, perhaps someone else can re-roll a patch from the .txt file attached?

Some comments from the previous issue, some new:

Nitpick: "Don't hack core". Remove ""
Nitpick: All directories mentioned in this document are always relative to the
Remove "always"

Minor update:

Step 1: IMPORTANT! Do not close your browser until the final step is complete.
Move to step 6 (run update.php), ref. http://drupal.org/node/295255#comment-3577288

Step 3: Add:
Sometimes, an update also includes changes to settings.php. If so, this is stated in the release announcement for the update. If that's the case, replace your old settings.php with the new one, and copy the site-specific entries (especially the line giving the database name, user, and password) from the old settings.php to the new settings.php.

Step 4: After the first sentence, add It's OK to skip several minor versions, for instance go directly from 7.1 to 7.5. (It's implicitly stated since it says "the latest 7.x release", but I think we should say it explicitly.)

Major upgrade:

Step 6: There were some discussion in the previous issue about whether this is neccessary. Should be tested. (I'll try to get time for it this weekend, if noone beats me to it.)

New step between current step 7 and step 8:
If you have installed any of the modules listed on http://drupal.org/node/895314, there may be additional steps you need to follow. (More information on that page.)
Reason: For modules moving into core, there may be special steps you need to follow to avoid losing data or having the upgrade crash and burn. For some, it may be important to uninstall completely, for others it may be vital to keep the data. (I think I had one upgrade crash when I failed to uninstall Update status before going from D5 to D6.)

At start or end of major upgrade, add:
IMPORTANT: Do major upgrades on a test copy of your site, taking notes as you go, before upgrading your live site.
Ref. #41 in the previous thread. If a user has only done minor updates before, he/she might not realise that a major upgrade is another beast entirely.

In step 6 (minor) and step 12 (major), I'm tempted to replace the details on changing settings.php with
If you are unable to access update.php, see http://drupal.org/upgrade/running-update-php.
If we do that, we can remove step 8 (minor) and step 16 (major) as well.
Does this problem occur very often? If so, I guess we should keep the info there, but if it's rare, I'd rather make the instructions more compact for the majority, and refer the minority to the handbook.

These are all good suggestions. I think I've incorporated all/most of them, though a couple of them I put into the INTRODUCTION rather than where it was suggested.

Regarding not being able to access update.php, one commenter on the previous issue asked if it was EVER possible to do a major upgrade without putting the line in update.php, so I'm inclined to leave it there... at least for major upgrades... thoughts?

Anyway, here's a new patch/file.

I like the changes here, but would like to suggest one more.

When I was new to Drupal I was terrified of accidentally deleting important information during an upgrade. So I notice that while the upgrade document says to delete everything except the sites folder, it does not give instructions on ensuring that your sites folder doesn't get overwritten when you extract the files for the new version. I'm thinking in particular of novice installers doing this through FTP and/or cPanel file manager rather than people comfortable with the command line.

I'm not sure what the recommended procedure should be, but I think we should spell it out, whether it's:
4. ...Copy the files into your Drupal installation directory, but DO NOT overwrite the sites folder when prompted
(If we're sure that there will always be a prompt, and not any situations where the default would be to overwrite.)

Or something more like
4. Rename your "sites" directory to "sites_backup". Download the latest Drupal 7.x release from http://drupal.org to a directory outside of your web root. Extract the archive and copy the files into your Drupal directory. Delete the sites directory, and change the name of "sites_backup" back to "sites".

Or perhaps the best procedure is to have them copy the sites directory outside the root and then copy it back in again, overriding the default core version. I'll defer to more experienced folks on how exactly we should tell people to do it, but I think whatever it is we should spell it out precisely, in the interest of making D7 super friendly to new users.

Well, we do say at the beginning to back up everything (files and database), so presumably if someone wrote over their sites directory, they could restore it from the backup?

subscribing

Just created #950672: Update "Drupal 6 contributed modules that are in Drupal 7 core" to address (and hopefully document) different upgrade paths for contrib modules that have been moved completely or partially to core.

Looks like a good improvement. Here are a few notes:

1) There should be consistency in whether sentences ending in a URL are closed with a period or not. Currently, this is not consistently done. For example,

  * Consult one of the support options listed on http://drupal.org/support.

More in-depth information on upgrading can be found at http://drupal.org/upgrade

The reasoning that was given to me in an earlier issue on UPGRADE.txt (ease of copy and paste) makes sense, so I think that they should always be removed.

2) The sentence about modules that were moved into core could be more concisely worded. I recommend changing:

Also, if you have installed any of the
    modules that have moved into core for Drupal 7 (listed on
    http://drupal.org/node/895314), there may be additional steps you need to
    follow. (More information on that page.)

to

Also, if you have installed any of the
    modules that have moved into core for Drupal 7, there may be additional steps 
    you need to follow. These modules, and the steps required to upgrade them, 
    are listed on http://drupal.org/node/895314

3) There is a typo in the section under minor version upgrades about settings.php. Instead of:

If that's the case,
   replace your old settings.php with the new one, and copy the site-specific
   entries (especially the lines2 giving the database name, user, and password)
   from the old settings.php to the new settings.php.

I recommend:

If that's the case,
   replace your old settings.php with the new one, and copy the site-specific
   entries (especially the lines specifying the database name, user, and password)
   from the old settings.php to the new settings.php.

4) The steps about granting free access to update.php are not all worded in the form of actions. I would change:

        - There is a line that says:
     $update_free_access = FALSE;

to

     - Find the line that reads:
     $update_free_access = FALSE;

in both places where it appears.

Other than that, I think this is good to go. My points 1,2, and 4 are debatable, but point 3 is an error in the proposed text, so marking as "needs work".

As far as BrightBold's concern in #11, I don't think that needs to be added as an explicit step, but there could be a sentence saying to restore the sites directory from a backup if it got lost somehow in the copy over. (I think that might be superfluous though.)

I moved bonobo's issue #950672: Update "Drupal 6 contributed modules that are in Drupal 7 core" to the Documentation queue, since it doesn't involve Drupal core. If the page is split, linking the additional page in this document could be a follow up issue to this one.

All good points. Here's a new file and patch.

forgot the patch itself

Well, we do say at the beginning to back up everything (files and database), so presumably if someone wrote over their sites directory, they could restore it from the backup?

Sure, I just think the way it's written, it might give a novice some false sense of security that the upgrade process was going to automatically protect the sites file, since we say "don't delete it" but then never mention it again.

I think the beauty and fantastic usability of Drupal 7 are going to attract more designers, writers, and other less technical folks, which is a good thing, so I think we should try to minimize the possibility of failure for new users.

If you can figure out where that should be mentioned, and how to mention it, let's get it in. Otherwise, I think it's fine as it is, saying to make a backup and saying not to delete it. ??

@BrightBold: I think that the recommended technique of doing a cp (or the equivalent, via FTP) should not overwrite the sites folder. In any case, they have the backup :)

@jhodgdon: Looks good to me. I think this is ready.

+++ UPGRADE.txt	23 Oct 2010 20:58:49 -0000
@@ -5,7 +5,8 @@
-    version; for example, from 7.9 to 7.10.
+    version; for example, from 7.9 to 7.10. It's also OK to skip several minor
+    versions; for instance, you can go directly from 7.1 to 7.5.

Skip the additional sentence and just replace 7.9 with 7.6.

+++ UPGRADE.txt	23 Oct 2010 20:58:49 -0000
@@ -15,16 +16,23 @@
+  * If you are performing a major version upgrade, make sure to check on the
+    status of your contributed and custom modules and themes before you decide
+    it is time to start. See http://drupal.org/node/948216 for a description of
+    the decision and upgrade process. Also, if you have installed any of the
+    modules that have moved into core for Drupal 7, there may be additional steps
+    you need to follow. These modules, and the steps required to upgrade them,
+    are listed on http://drupal.org/node/895314

This is a) too lengthy and b) does not belong into the general section, as it's a task for specific section only.

+++ UPGRADE.txt	23 Oct 2010 20:58:49 -0000
@@ -15,16 +16,23 @@
+  * It is wise to try a major upgrade on a test copy of your site, making notes
+    as you go, before upgrading your live site.

I've read that "make notes" and "check your notes" in the issue before already, but I couldn't make sense of it. What notes? (?)

+++ UPGRADE.txt	23 Oct 2010 20:58:49 -0000
@@ -36,20 +44,19 @@
-2. Go to Administer » Configuration » Development » Maintenance mode.
+2. Go to Administer > Configuration > Development > Maintenance mode.

We should be using » because that is much more clear, as it is the default separator of breadcrumb links in Drupal.

Also note that "Administer" is "Administration" now.

+++ UPGRADE.txt	23 Oct 2010 20:58:49 -0000
@@ -59,6 +66,12 @@
+   Sometimes, an update also includes changes to settings.php. If so, this is
+   stated in the release announcement for the update. If that's the case,
+   replace your old settings.php with the new one, and copy the site-specific
+   entries (especially the lines giving the database name, user, and password)
+   from the old settings.php to the new settings.php.

Can be shortened. There are two if/else conditions in this paragraph, and both mean the same condition.

+++ UPGRADE.txt	23 Oct 2010 20:58:49 -0000
@@ -82,13 +95,14 @@
 6. Run update.php by visiting http://www.example.com/update.php (replace
    www.example.com with your domain name). This will update the core database
-   tables.
+   tables. IMPORTANT! Do not close your browser until the final step is
+   complete.

Can we drop that "IMPORTANT!" ? It looks and reads poor.

To communicate important information that must be noted, it is usually wise to rethink the communication.

+++ UPGRADE.txt	23 Oct 2010 20:58:49 -0000
@@ -114,45 +128,44 @@
+   Also, make sure you have followed the instructions in the INTRODUCTION
+   section above about contributed modules.

Cross-references are bad in a step-by-step task procedure.

Powered by Dreditor.

@sun:
Maybe RTBC was premature of me, although the text was a significant improvement. I'll take your comments point-by-point.

1) I disagree about removing the sentence on skipping minor versions, actually, since this is a question that comes up a lot on IRC. People get confused and want to know whether they have to download each individual point release. We want them to not have to ask about that. I agree it could possibly be more succinct, though.

2,3) You're right about the major version information being out-of-place in the introduction, now that I think about it. What if the major version introduction were something like the following:

Before upgrading your live site from a previous major version of Drupal to Drupal 7.x, 
consider the following:

  * Check to see whether contributed modules and themes your site needs are available
    for Drupal 7 in a stable release. For guidance on making this decision, see
    http://drupal.org/node/948216

  * Check whether you have installed any modules whose functionality is now in Drupal 7 core. 
    These modules, and the steps required to upgrade them, are listed on 
    http://drupal.org/node/895314

  * If your site uses custom modules or themes, they will need to be ported to Drupal 7.
    [Link to the upgrade guide - I couldn't find it on the redesigned Drupal.org.]
 
  * Create a test site and do a trial run of the upgrade. Take notes on any problems that
    occur and check the Drupal.org issue queues to see whether there is a patch for them.

  * Make sure your site is running the latest available version of Drupal 6.x.

   If your current version is Drupal 5.x, you have to upgrade to 6.x first.
   Download Drupal 6.x and follow the instructions in its UPGRADE.txt file 
   instead. This document only applies for upgrades from 6.x to 7.x.

4) Didn't realize that about breadcrumbs...interesting.

5) What about

Check the release notes for the update to see if it includes changes
to settings.php. If so, replace your old settings.php with the new one, 
and copy the site-specific entries (especially the lines giving the 
database name, user, and password) from the old settings.php to 
the new settings.php.

6) Rather than the "IMPORTANT!", why not simply put the sentence on a new line? If that is not adequate emphasis, then perhaps an additional sentences stating the consequences of failing to do so would be good.

7) Wording like that I proposed in 2,3 above would fix this issue.

Just realized that my block of text above is wrapped at the wrong width. But it's just a proposal, anyway, so no biggie.

#22.2+3) are task steps, like any other steps. No need to invent something new. The entire procedure is a task list. Checking availability of modules and themes is just one of them.

5) is a better proposal, but can still be shortened and therefore formulated more clearly, probably even to the half of its length.

6) I'm not sure what that entire warning is good for. It assumes that people would close a Batch API screen while it's running. Entirely invalid in the first place, because no one thinks of doing that.

RE 2,3 from EvanDonovan's comment in #22 -

How about the following rework:

Before upgrading your live site from a previous major version of Drupal to Drupal 7.x, 
consider or verify the following:

  * Make sure your site is running the latest available version of Drupal 6.x. If your 
    current version is Drupal 5.x, you have to upgrade to 6.x first.
    Download Drupal 6.x and follow the instructions in its UPGRADE.txt file 
    instead. This document only applies for upgrades from 6.x to 7.x.

  * Check to see whether contributed modules and themes your site needs are available
    for Drupal 7 in a stable release. For guidance on making this decision, see
    http://drupal.org/node/948216

  * Check whether you have installed any modules whose functionality is now in Drupal 7 core. 
    These modules, and the steps required to upgrade them, are listed on 
    http://drupal.org/node/895314

  * If your site uses custom modules or themes, they will need to be ported to Drupal 7.
    For more information on porting modules, see http://drupal.org/update/modules/6/7
    For more information on porting themes, see http://drupal.org/node/254940

  * Create a test site and do a trial run of the upgrade. Take notes on your progress, and 
    document any issues that might arise. Error messages can help identify and solve problems.

Comment #7 mentioned that non-ASCII characters were not showing up well on some systems, and » is not and ASCII character. Do we want to include it for consistency with the default breadcrumbs, or use > to stay in the ASCII set? To me it seems to be similar to plain double quotes vs stylized ones. I vote for the simple greater-than sign.

All Drupal files are in UTF-8, so that is no question at all. » is a regular character.

Contrary to the epic and time-wasting discussion about usage of double quotes, » vs. > makes an actual difference, because users/readers immediately associate » with breadcrumb links.

> can mean anything ranging from something being greater than something else, a plain-text blockquote, a closing HTML tag delimiter, a navigational hierarchy, etc.pp.

» is also easy to write/enter. At least, Windows users just press (regular/left) ALT key + 175 keys on the decimal keyboard.

» shift + alt + \ on mac keyboard
( just for reference )

RE #21 and #26-#28 - Please don't put the >> character back in the file. When I looked at that version on my Windows box in GNU emacs, it wasn't a good character to look at -- rendered as A?>> or something. That is why I took it out. Probably the file wasn't properly encoded as "I can contain UTF8 characters". Anyway, what we're trying to convey is navigation here, not breadcrumbs, and > is perfectly adequate to get that across, and has no possible cross-platform rendering issues.

Regarding the other comments -- good ideas mostly at least -- I'll get another patch together shortly.

The file was encoded in ISO-8859-1 previously, which is why you saw garbled characters. That's no longer the case. It would be wrong to not use » just because of a previously existing bug, especially because it is much more clear for every reader.

Actually, our style guide for the Handbook says to use >

http://drupal.org/node/338208#paths

Re: #19 & #20, I would certainly be willing to contribute the text change, but it sounds like no one else thinks it's necessary. If this changes though I will happily take a stab at it.

Here's a new file/patch.

I believe I've addressed the relevant issues in #21 - #32. I also generally read through the file again, and tried to make everything as concise as possible.

Just did a quick read through, and this looks solid.

My only nit to pick: Instead of saying an FTP client, should we say an SFTP client?

But that is very minor.

+1 to commit.

I'm tempted to set to RTBC, but I'd like to see other folks weigh in here as well.

Two small notes:

1. Step seven under the minor update section reads:

7. Go to Administration > Reports > Status report. Verify that everything is
   is working as expected.

The word "is" is repeated twice.

2. Step 17 in the major upgrade section should be identical to step 8 in the minor update section. Right now they read:

8. Ensure that $update_free_access is FALSE in settings.php.

and

17. Ensure that $update_free_access is FALSE in settings.

I prefer the wording as it is in step 8. I guess that's up for debate, but I think they should be the same either way.

Great work on this file btw.

-Josh

This is looking really solid. I'm glad for @sun's review. Back to "needs work" for the two comments from #35, and then this should be RTBC. I agree that "settings.php" is more correct than "settings".

I hope we are all in agreement now that ">" is OK, since I don't see how that could cause confusion in this context. We are just talking about levels in the menu hierarchy, not breadcrumbs per se.

Thanks, @jhodgdon, for patiently incorporating all our comments.

I'm all about improving Drupal documentation, and am always grateful for constructive reviews of patches. More sets of eyes => better docs. :)

Anyway. Here's an update for #35. Note that the "is is" problem was repeated in the section below; both are now fixed.

Regarding #34, I don't think we should change FTP to SFTP in the text of this file. FTP is more generally recognized.

I tried an upgrade following these steps, got logged out when replacing files, and had to change settings.php as described in step 13.

Judging from #945112: Unable to stay logged in during upgrade from D6 -> D7 it looks as if we can remove the "if" from step 13. Has anyone managed to do an update without setting $update_free_access = TRUE; ?

#37 looks good and polished, +1. A lot of helpful fixes contained here. Agreed on using FTP vs SFTP -- if you know what SFTP/SSH is, then you'll obviously use it instead.

I just noticed: in #9 you removed the whole "Don't hack core" paragraph. That's not what I meant in #8, and I think it should be kept in. What I meant was that the section

* "Don't hack core". If you modified core files outside of the 'sites'
directory, see http://drupal.org/node/144376.

should be changed to

* Don't hack core. If you modified core files outside of the 'sites'
directory, see http://drupal.org/node/144376.

(ie. just remove the redundant "-signs.)

Regarding "don't hack core" ... I don't understand why that recommendation belongs in UPGRADE.txt?

Regarding the if in step 13, I am not sure it makes a huge difference whether we leave it there or remove it.

"Don't hack core", while a good rule, is probably not needed in this file, nor does the linked node actually offer much help if you have. I think this is RTBC, but I won't switch it yet, since someone else might still have some good feedback.

Looks great to me!

I like FTP vs SFTP for the reason stated above, and I don't think the "don't hack core" policy needs to be in this file. I read that policy half a dozen times when I first started using drupal, and I didn't finally heed the advice until a minor update overwrote a few hours worth of my hacks. Hopefully others are smarter than I was, but I suspect a lot of people learn the importance of that rule the same way I did. So including it here probably isn't necessary.

Anyway, I think I'm still too new around here to set the issue to RTBC, but it looks great.

Setting the patch in 37 to RTBC.

This is a huge improvement over what is there.

Pending the resolution of #945112: Unable to stay logged in during upgrade from D6 -> D7 we can remove the "if" as needed, but that's a small change and the text already contains the solution/workaround for that.

Committed to CVS HEAD. Agreed that it is a big improvement. Feel free to re-open if there are more updates.

People interested in this issue may also be interested in:
#952606: INSTALL.txt needs correction and clarification

Not sure if this is an installation bug, or a documentation issue, but I followed the instructions in Upgrade.txt to upgrade from 6.x to Drupal 7, on a fairly bare site with an Acquia distribution. The site was automatically taken online, where I had previously set it to offline for maintenance mode. (Also ended up logged out, so had to set update.php access to TRUE) If this is automatic upgrade.txt should indicate it, from the way it is written it sounds like you should expect to have to take the site back online again when you are done. (Which is the process from Drupal 6.) If this is expected behavior I have to say I wasn't crazy about it, since the site had all contributed modules turned off and was in no way ready for traffic. If it is expected, it should be documented.

Sounds like we should reopen this issue (or else open a new one)?

I think open a new issue against the install system component. Then folks like DamZ, David Rothstein, catch, chx, etc. who are familiar with the upgrade path can confirm, and if it is the case, and if we can't fix it before rc1, then move the issue back to documentation component.

Done. Here's the new issue:
#984358: Upgrade from 6.x to 7.x always pulls your site out of maintenance mode immediately
Further discussion there, please.

If you are following this issue, please check out
#984444: Page on modules now in core in D7 needs reorganization, table of contents
which is advocating a new change to UPGRADE.txt. I have already weighed in, but would like another opinion. Thanks!

@jhodgdon: Thanks - you can continue to use this issue to ping me about other UPGRADE.txt changes if you want someone else to take a look at them. Otherwise, I probably won't hear about them, since I haven't had much time to review the queue lately.