When upgrading from one release of Drupal for Facebook to the next, there are several steps you must take. While not strictly required for every update, many do require these steps. Better safe than sorry, so just do this every time you download a beta update, a new dev release, or anytime you update code checked out via version control.

Here are the steps to take with every update:

  1. Get the old code out of the way. In some upgrades files move or are deleted. So if you've downloaded from the project page you don't want any possibly out-of-date files sitting around. Something like
    cd sites/all/modules
mv fb /tmp

    Will move the files out of the way.

  2. Get the new files. Either download and extract the tarball from the project page, or update with version control.
  3. Run the update.php script. You should do this every time you update any module or theme, and that includes modules/fb. Not only does it perform database updates if the modules require them, it also flushes caches, picks up new menu items, etc...
    Always backup your entire database before running the update.php script!
  4. Manually update your facebook applications! This means go to administer >> site building >> facebook applications. Click the edit link for each of your apps, and press save. This synchronizes various settings with facebook.com. If you've unchecked the "set properties automatically" option, you may need to visit a form on facebook.com to change properties. Sorry, this step cannot happen automatically via update.php (at least not for now).
  5. Enable the Drupal for Facebook Devel module, if it is not enabled already. This module will provide warnings about some common errors. Visit administer >> reports >> status report page, and make sure there are no errors or warnings. Also visit admin >> reports >> recent log entries and look for errors there.
  6. Use the site a little bit. Test your facebook connect or canvas page features, whatever you have enabled. Repeat your checks of the status report and log messages, looking again for any errors.

Finally, when you have confidence there are no problems. You can disable the Devel modules on production sites. I recommend leaving them enabled always on devel and staging sites, but not if your testing performance, as they can slow pages down.

Note that if you update settings on facebook, for example changing your canvas path or application name, you must return to admin >> site building >> facebook applications and repeat the edit...save step. Saving the application edit form performs a two-way sync, sending some values to facebook and also learning some values from facebook.

Updating beyond Beta 10

If your starting with Beta 10 or earlier, and updating to a .dev release or any release after beta 10, you may need additional changes.

Up to beta 10, the modules had several inefficient "features" which were necessary on Drupal 5.x, but not on 6.x. After beta 10, the complexity of session management is reduced, and some inbound url rewriting is happily no longer necessary.

For most users, the steps listed above will suffice. If however you know you are using canvas pages and using any of the "URL rewriting tricks" like the cookie-less session trick for iframes or a page type trick. You may need to keep the old url rewriting scheme in place. Even if using these things, I recommend trying to get your site working without them, as they add a lot of complexity that hopefully you don't truly need.

Do keep the old URL rewriting, add another line to your settings.php, something like (remember this is not recommended, just maintains backward compatibility for the minority of users who may still need it):

require "sites/all/modules/fb/fb_settings.inc"; // this line should already be there.
require "sites/all/modules/fb/fb_url_rewrite.inc"; // THIS IS THE NEW LINE.

If you have implemented your own custom_url_rewrite functions, take note: either include the fb_url_rewrite.inc file as just described, or (and this is recommended) note that fb_canvas.module now has fb_canvas_url_outbound_alter(). You're custom outbound rewrite funciton should call this, if you are implementing canvas pages.

The bottom line is good news... sites implementing connect, but not canvas pages should no longer need url rewriting! Site implementing canvas pages should need less rewriting, just the outbound!

Troubleshooting

If you've completed all these steps, and still believe that an upgrade to the modules has broken something that used to work, please let us know by describing the problem in accurate detail on the project issue queue. Of course look over the issue queue first. Someone may have reported the same problem already.

Help us help you by starting your issue queue with words like, "I have followed every step on the upgrade page and still I have this problem...".