Review and test the upgrade guide for Drupal 7

adding tag for tracking

Taking this issue for the next couple of hours. Will update with notes on my progress with upgrading a site according to the instructions.

Did a read through of the entire book outline having to do with upgrading Drupal, and I see the challenge before us. My sense is that it needs a complete rewrite, to have maybe 3 "top"-level items instead of the 10 that have specifically to do with upgrading + the 3 that are alternate approaches. The top 3 in the upgrade outline, each its own single page, would be:

1. how to upgrade Drupal through SFTP/phpMyAdmin (probably the most applicable instructions to web hosts out there)
2. how to upgrade the site via the command line using 'mysql', 'mysqldump', 'tar -zxvf', and whatnot
3. upgrading Drupal using the command line using a CVS checkout

I'd like each document to include the following sections:

• a backup strategy (make it part of the official steps to upgrade, not merely "recommended")
• an upgrade planning strategy, including how to research whether contributed modules are available in the version the maintainer is upgrading to
• MAYBE mention that upgrading is an opportunity to do a site audit and to organize the site's files properly, like moving contributed modules out of the Drupal root and into sites/all/modules
• MAYBE a staging site strategy, to try an upgrade out before proceeding on the live site
• things to check afterwards, such as going to the Drupal status report

The document and follow-ups at http://becircle.com/how_upgrade_drupal_5_drupal_6 have the right approach to a thorough and sustainable upgrade procedure, and I'd like to see a condensed version in the handbook.

Relinquishing the issue, though I will come back to it this week.

I just wanted to note that a while back I submitted a rewrite of the D6 upgrade.txt file because I found the original was somewhat confusing and ambiguous (http://drupal.org/node/368516).

I'd update it again for D7 but it's not looking like anyone has the time to review it so I'm not sure if there would be much value.

I will throw my 2 cents in here and suggest that fields in core is probably going to dramatically complicate the upgrade path for D6 > D7. Very difficult to tell at this point exactly what that will look like.

Here is a conversation about this issue in the queue...

#366364: Upgrade path for D6 CCK fields

And a specific quote from that issue (bjaspan)...

I do not think this can be a normal hook_upgrade_N() function because it is unlikely that all field modules a site is using will be available to upgrade all at once, so the upgrade process will require multiple passes. Thus, it should be a module with a UI, perhaps showing all the D6 fields & modules, the D7 fields and modules they map to, and the status of each (upgraded/not upgraded).

Emphasis added.

I've got a preliminary checklist page for d7 upgrade : http://drupal.org/node/548922

If anyone else is working on this, wants to work on this, has completed it -- lets flesh it out together.

I'll help out - going to comb through the formatting, compare with upgrade.txt, etc. - will save changes as new revisions so if there's multiple people workin on it it'll be happytimes.

Just thought I would chime in here (partially at the request of emma jane).

I've talked to a couple of people including Richard Eriksson about this but have not posted this publicly.

Basically, I want everyone to know that you can feel free to take liberally from http://becircle.com/how_upgrade_drupal_5_drupal_6 if there is copy/text there that will help fill in content for portions of this documentation. At very least some of that content can be used as a 'stub' for some of the sections of the upgrade guide.

For what its worth, I think the skeleton at http://drupal.org/node/548922 is looking good, but will need to be broken into separate pages and lots of bullets that are there now could use some expansion.

e.g. for each of the following say where you find this information out.
___ Determine which version of Drupal is running on the site
admin/reports/updates - explain
___ Identify and write down the modules that are on the site
admin/build/modules - explain
___ Identify and write down the modules that are active and are NOT used on the site
admin/build/modules - explain
___ Understand which theme is active on the site
admin/build/themes - explain
___ Determine if any modules or themes have been customized
diffing modules - explain
___ Determine if Drupal base code has been customized
diffing core - explain

I've started some of this work. See the revision notes for the handbook pages.

crap - just reading this last comment, andremolnar you are totally duplicating the work i've done over the last couple days. :-/ not really sure how i'm going to integrate the changes now, but will try not to totally overwrite the stuff you've done. if you want to take this on instead, just say so and i'll happily move onto something else!

Ok, all my work to date has been integrated, I did some major reformatting and rewriting of the language of the pages I edited to match up with the Styleguide guidelines. Just a suggestion, it would be a REALLY good idea to update content to the style and formatting guidelines as we go so it doesn't have to be redone later. If you're not familiar with the guide, it's really helpful and detailed: http://drupal.org/node/338208.

I may do a little more work on this, but I'm going to switch and focus on patch reviews till code freeze, and then will come back to more documentation work. Onwards! :-)

Perhaps the upgrade documentation should also be broken out by OS and web server, or at least web server, as it is with the installation requirements, eg

For Apache on *nix:
For Apache on Windows:
for IIS on Windows:

Command line stuff is quite different across OSes, .htaccess (Apache) and web.config (IIS) are different, etc.

arianek. Sorry, I'm not sure which bits I duplicated (had you created unpublished pages?). I didn't do anything really new (besides creating the sub-pages). I simply started to organize the stub content that had been entered on the upgrade page.

At any rate, as a general rule I'm on board with 'be bold' when editing wiki type documentation. If anyone has issue with any of my edits (big or small) be bold and blow them away (provided that it improves the overall quality of documentation ;). I won't be upset.

@chicagomom can you think of specific parts of the upgrade process that are OS specific? I'm not sure I can off the top of my head. Still, if there are, then it might be best to include notes in those specific areas rather than maintain multiple upgrade docs that are 98% the same.

That is wonderful news - and very gracious on behalf of becircle. Thank you!

@andremolnar - no i'd been reworking the content locally (as i thought bekasu and i were the only ones working on this section) and was about to update, when i saw it had been broken up into pages - it's fine though, i didn't have too difficult of a time piecing in the bits i'd rewritten and reformatted, and i don't think i deleted any of the content you'd added, so altogether i think things are looking improved! anyway i'm switching gears to help with patches again till code freeze, so it will be a couple weeks at least until i check back in on this.

@andremolnar you're correct - it's mostly things like cp is not a valid command in a Windows environment. But rather than having Windows user instructions hanging off the "main" documentation though, it would be better to just note within the documentation what to do if you're using Windows. Eg

Use a basic copy (and paste) to copy all the files (including the .htaccess or web.config file) from your Drupal directory to the backup directory:

Unix: cp -rp /path/to/drupal_site /path/to/backup_dir

-rp = recursive and preserve permissions

Windows: robocopy c:/path/to/drupal_site c:/path/to/backup_dir /MIR

(or whatever your local install drive letter is)

/MIR - copy directories and subdirs including empty ones

One thing the current documentation is not good at is telling users when the documentation is referring to Unix-specific commands. Even a label would help. Option 2 on the above-mentioned page, for example, goes through creating a tar archive - not something you can do with Windows unless you have specific add-on utilities installed.

This applies here as well. And also on this page, "IV method 1: Use the contributed database insertion script on this page: also refers to Unix-specific commands, but it's not identified as such.

I'm almost finished dismantling the HOWTO section on install, upgrade, etc. Many pages have been moved to the "Archive" book, but some have moved over to the Install and Upgrade guides. Please use content as appropriate, shuffle pages into the right place, or put the page in the "Archive" book if it is no longer relevant.

I dropped off the face of the earth for the past two weeks as a couple of unexpected projects took over. I will be back on this in the coming week.

I finally cleaned up and expanded half the pages.

Still TODO:
New Site Preparation: http://drupal.org/node/570160 - Needs to be expanded and handbook writing stylized.
Actual Upgrade: http://drupal.org/node/570162 - Needs to be expanded and handbook writing stylized.
After Upgrade Checklist: http://drupal.org/node/570164 - Needs to be expanded and handbook writing stylized.

Maybe someone can help me track down a link or be willing to write a handbook page:
On http://drupal.org/node/550130 I added this line (among many others)
Has the module moved to Drupal core? Drupal 7 core has incorporated several key contributed modules into its release. For a full list see [link]

The problem is that I can't find the new core module inclusions documented on any handbook page and changelog.txt doesn't specifically name all the modules.

Help as much as you can.

I've created a related issue: http://drupal.org/node/615634 "Update CHANGELOG.txt to explicitly name new core modules and core modules that have been removed."
That issue is required for completing upgrade documentation as new core modules that have been moved in from contrib will impact on the upgrade path for people currently using those contributed modules in their 6.x site.

Need to use clean urls for documentation otherwise people cannot know where they are. The tree map is helpful but clean urls would be so much more as they are more easily searchable and stickable http://drupal.org/node/15365

The other thing is that the actual documentation is at http://drupal.org/node/548922 and its not mentioned in the actual description but way down in one of the comments. Even if this was conceived about a year back it would have been better to have a URL/node reserved for the same and made sticky. This would have been easier to know things around.

It would be nice/better to see this happening down the road as well.

The upgrade.txt page http://drupal.org/node/550126 should have had also the upgrade txt file attached or linked to the cvs/svn/git version of the file (if the file is being updated all the time.)

i'm thinking this should be one of the primary items to focus on, cool if i priority +? (feel free to reset if not)