Upgrade Instructions Considered Necessary
Some thoughts on upgrading open source server software
Yesterday I spent a couple of hours avoiding real work by upgrading my software. Specifically I upgraded MySQL 4.1, Apache 2, and PHP here on cafe.elharo.com after noticing that MySQL had crashed. I didn’t do any major version upgrades, just moved everything up to the latest point release of the branch I was using. Along the way I noticed big, gaping holes in the documentation for all three. Not one of them had any upgrade instructions. They all had poorly written instructions for a first time install (Apache was probably the least bad here, PHP the worst) and a couple had instructions for moving between versions (e.g. 1.3 to 2.0 or 4.1 to 5.0) but not one had anything to say about how you should upgrade from 4.1.1 to 4.1.2 while keeping your data, configuration, and extension modules intact. Since point releases often fix security holes, these are the most critical upgrades. I had to go to IRC to figure out how to upgrade MySQL, where I was told it would happen by “magic,” which would be nice if it were true, except it wasn’t.
Word to software vendors: most of your customers are not starting from scratch. While it is critical to provide good instructions for first time users, it is equally critical to provide upgrade instructions for the majority of your customer base that is upgrading old systems. This is especially true for systems with relatively complicated installs like PHP and Apache. Some of the pieces were in place. Apache figured out to keep some of the old data when doing “make install” but the README still should have told me it would do that. However, my first attempt to upgrade Apache failed because I didn’t have exactly the same options to ./configure I had used a year ago when I installed it for the first time. The PHP “make install” broke my Apache config, which then had to be edited manually. MySQL’s “make install” failed to find my old data files, and I had to learn quite a bit more about MySQL just to get it to load the old data.
I don’t think it would be all that hard to write decent upgrade instructions for any of these products. Based on my experience, it’s mostly just a slight tweak of the normal install instructions; along with some words of caution about which files to back up and a little advice on how to figure out your orginal compile options that you now need to duplicate. Time to file a few RFEs in the relevent Bugzillas.
