CiviCRM upgrade 4.2.x

Upgrade Checklist

Update the Vendor branch in SVN

Get the new code in the vendor branch, loosely following this advice.

1. Download and unpack the stable version from SourceForge
2. Update the vendor branch with the latest version
   1. Download the magical perl script you're just supposed to trust not to screw this up. Then take "svn_load_dirs.pl.in" and hack off the ".in" at the end, leaving you with "svn_load_dirs.pl".
   2. Open the script, and edit the line

      my $svn = '@SVN_BINDIR@/svn';

      to reference your svn executable (probably /usr/bin/svn, but run 'which svn' to find out for sure).
   3. Place the script in the directory where you unpacked the new stable version. That is to say: The perl script should be placed one directory back from the upgrade's root directory, and not in amongst the actual files.
   4. Run the following:

      ./svn_load_dirs.pl svn+ssh://svn.wikimedia.org/svnroot/wikimedia/vendors/civicrm current [new version directory] -t [new version number]

      This script is supposed to both update current, and tag the new files appropriately, automatically.
      If that doesn't actually happen, something is wrong.
   5. Verify that in the repo, it has both updated current and tagged the new files appropriately.

Gotchas

If the vendor is horrible and doesn't enforce consistent line endings in the upgrade package, the whole thing will fail to work for no readily apparent reason.

Random guidance:

• Throw the echoed output into a text file and grep through it for anything that looks like "line endings". The problem file should appear by name shortly before the explosion.
• Fix the file in the update package you are trying to import. If you happen to use NetBeans, try the Show and change line endings plugin (in the case of files that aren't even self-consistent, you may have to change it to a different type and back again).
• Mediawiki Coding Conventions for newlines.

Also, don't sudo this perl script. If you do, and svn spits back an error that says

svn: Network connection closed unexpectedly

What it really means is: Don't sudo, because root doesn't have ssh keys.

Merge the Vendor changes into Trunk and Prod

The version of civicrm that we check out for production instances, will be in a directory here:

svn+ssh://svn.wikimedia.org/svnroot/wikimedia/branches/deployment/fundraising-civicrm/

The directories that live in prod, are named like this:

d[drupal version with no dots]c[civicrm version with no dots]

So, before we can merge any changes into prod, we will need to copy the current prod version to a new location, named properly for the upgrade we're trying to do.

svn cp svn+ssh://svn.wikimedia.org/svnroot/wikimedia/branches/deployment/fundraising-civicrm/[old prod version] svn+ssh://svn.wikimedia.org/svnroot/wikimedia/branches/deployment/fundraising-civicrm/[new prod version]

Now, you will need to check out a working copy of both trunk, and the new prod directory you just created. In each of those directories, run this command to merge the changeset between the old version and the new version, and apply those merge commands to the working directory.

svn merge svn+ssh://svn.wikimedia.org/svnroot/wikimedia/branches/deployment/fundraising-civicrm/[old prod version] svn+ssh://svn.wikimedia.org/svnroot/wikimedia/branches/deployment/fundraising-civicrm/current

Once that has been completed in both directories, commit the changes to the repository manually.

Take the Site Offline (prod only)

In addition to taking the drupal instance offline (Administer » Site Configuration » Site Maintenance), you should also disable the following prod jobs in Jenkins that will explode and send me a billion emails if the site goes offline:

1. drush qc (queue consumer)
2. ...everything else that starts with "drush".

Disable watchdogs and timeouts for MySQL

(make appropriate log entry in #wiki_tech with !log logentry or Tim Starling will be angry)

Kill the slow db query process killer.

root@db1008:~# killall -9 kill-slow-queries

Ensure that CiviCRM is not your Drupal homepage

In Administer » Site Configuration » Site Information, if the default home page value is "civicrm", change it. Probably to "node".

Disable all CiviCRM integration / extension modules (NOT CiviCRM itself)

1. GC audit
2. Recurring GC processor
3. public reporting (was not enabled on prod)
4. ...why isn't Thank You in this list?!? wrong. Look for more wrong. - a few of our modules do not have links in: Admin > Site Configuration
5. Limbo queue manager
6. Recurring payments
7. CiviAudit ← also doesn't list the dependency. Blargh.
8. Offline Contribution to CiviCRM
9. Queue2civi

Backup and then delete all previous version code files

Before you so much as touch any of the civicrm files, LOG IN TO THE INSTANCE.
If you don't log in to the instance before you start manipulating files, prepare to spend several hours rolling the repo back and forth over the upgrade revision, clearing the cache over and over, uninstalling and reinstalling civi, and grumbling heavily.

Once you've logged in to the instance (which you should have done already if you were able to disable the modules that were dependent on civicrm): If you are doing the update properly through svn, you should simply be able to svn update. If this is a production site and you're going through svn, this amounts to running an svn switch on the root of the drupal instance, to point to the new version.

Unpack the latest package and verify permissions

Verify the following:

1. [drupal root]/sites/default/files is writeable by the web server.
2. modify [drupal root]/sites/default/civicrm.settings.php: Change the following line

define( 'CIVICRM_UF', 'Drupal');

to this line

define( 'CIVICRM_UF', 'Drupal6');

and save the file.

Note: If you copying an existing installation, you will need to change another value in [drupal root]/sites/default/civicrm.settings.php:

$civicrm_root = '/path/to/drupal/installation/sites/all/modules/civicrm';

Run the Upgrade script

The link for that looks like:

http://<your_drupal_home>/?q=civicrm/upgrade&reset=1

If something goes wrong and the upgrade can't complete, but you got some distance through the upgrade, it WILL make you restore your db back to its original state and start over. If it created anything new, you will either have to drop them individually, or drop the whole DB and start over. If you choose to drop the whole DB, make sure you GRANT ALL PRIVILEGES on *.database to your user, or it will complain that it can't create triggers and make you start over. Again. New tables to drop:

• 'civicrm_setting'

Verify and Update Resource URL Settings

In the event that after the upgrade you are missing icons and stylesheets, and the javascript is all jacked up, go to Administer » Configure » Global Settings » Resource URLs. Allegedly there is a "help" thing you can click there. So far, I have not experienced this problem myself and have been able to safely cruise by this step.

Enable Components

...or not. You shouldn't have to enable anything that was enabled in the previous install, but there's probably new things to play with that you can enable in Administer » Configure » Global Settings » Enable CiviCRM Components.

Re-enable compatible CiviCRM integration / extension modules

1. Queue2civi
2. CiviAudit
3. Recurring payments
4. Limbo queue manager
5. Thank You
6. public reporting
7. Recurring Globalcollect processor
8. GC Audit

Note: All of these work for Jeremy, except public reporting. I get a white screen when I try to enable it.

Review and Update Drupal Permissions Settings

Go to Administer » User Management » Permissions, and make sure the following settings are rational:

• access CiviMail subscribe/unsubscribe pages
• view event participants
• access all custom data
• access Contact Dashboard
• access CiviEvent
• register for events
• Delete permssions
• administer recurring_globalcollect

Clear Views' cache (for sites using Views 2 integration)

The civi upgrade documentation recommends you clear the views cache through the ui, but I'd prefer you just did this at the command line, in the drupal site's root directory:

drush cc

Then choose "1" for "all".

Restore CiviCRM as the Drupal homepage if appropriate

If you had to change your homepage from "civicrm" to "node" In Administer » Site Configuration » Site Information, now would be an excellent time to change it back.

Gotchas

Navigate to the civicrm module home page in the UI. If you get a window.alert that says "Load jQuery First!" before that page (or any other page in the entirety of civicrm), change the WYSIWIG editor from TinyMCE, to CKEditor. That setting is located in CiviCRM > Administer > Administration Console > Display Preferences, in a dropdown near the bottom of the page.

>_<

Unkill the slow db query killer

root@db1008:~# nohup ./kill-slow-queries &

Put the Site Online (for production site upgrades)

If you took the site offline, return to Administer » Site Configuration » Site Maintenance to bring it online. Then, re-enable the Jenkins drush jobs you disabled earlier.

• drush qc
• ...everything else.

Review background scripts

As we're using drush for all our scheduled jobs, there is no need to upgrade "civicrm-related cron jobs" the way the civi upgrade documentation specifies. However, it would be a good idea to watch the Jenkins jobs for a little while to determine that nothing is broken.

Notes

In the event that you are going for a test install before running it on the real thing, and your cloned instance is presenting you with the drupal install screen, make sure the web server has the appropriate permissions on the cloned files. (Why it deduces you simply haven't installed the site yet, I have no idea...)

See Also

• Upgrade Drupal Sites to 4.1