$Id: UPGRADING,v 1.21 2003/06/26 12:03:55 jefmcg Exp $ CONTENTS 1. How to upgrade Gallery 2. How to upgrade a modified Gallery 3. Upgrading from v1.1 (or earlier) 4. Upgrading from v1.2.x 5. Upgrading from v1.3, v1.3.1 1. HOW TO UPGRADE GALLERY In general, upgrading is very easy. You won't lose any data, you won't have to rebuild your albums. If you're running an unmodified (ie, you haven't changed the code -- changing html_wrap files don't count), relatively recent version of Gallery then the upgrade process will take all of about a minute. All your html_wrap/ and css/ changes will be preserved. 1. Make a backup of your old Gallery installation 2. Put your Gallery in config mode (ie, 'sh configure.sh') *********************************************** * MOST PROBLEMS IN THE UPGRADE PROCESS HAPPEN * * BECAUSE YOU FORGET TO DO STEP 2! * *********************************************** 3. Unpack the new Gallery on top of your old one 4. Put your Gallery in secure mode (ie, 'sh secure.sh') If a significant enough change has happened to Gallery, it will force you to go back to config mode and run through the config wizard again, but it will save all your old settings so that should be pretty easy. Once you've got the new code and have run the config wizard, you may be required to let Gallery upgrade all your albums. This is only required if we've changed the Album data format (which we do rarely). If you click on an album that requires upgrading, Gallery will automatically upgrade it for you right away. Or, you can log on as administrator and on the main Gallery page you'll see a link next to every album that requires upgrading. Click that to get into the interface where you can upgrade all albums at once (or just browse to upgrade_album.php). 2. HOW TO UPGRADE A MODIFIED GALLERY If you've only modified files in the html_wrap/ and css/ directories, then you can follow the instructions in section 1. If you've modified the .php files that come with Gallery, then your upgrade difficulty is directly proportional to the number of changes that you've made. It's best to avoid modifying the .php files because you can be sure that sooner or later we're going to change the system in a way that will cause your modifications to break. You can control much of the appearance of Gallery by making changes in the html_wrap/ and css/ directories; it's best to limit your changes to those files if at all possible. The easiest way to make this kind of upgrade is to first get an idea of the changes that you've made. Get a copy of the original version of Gallery that you installed and unpack it in some other directory (we'll call it orig_gallery). Then, diff all the files between the original gallery and the one that you've modified: % cd home [go to the dir containing both % ls gallery and orig_gallery] gallery orig_gallery % diff -r -C 3 orig_gallery gallery > my_changes This will create a file called "my_changes" that has all the changes that you made to Gallery. You can apply these changes to the latest version that you've installed by saying: % cd directory_containing_new_gallery % patch < my_changes But the odds are good that this WON'T WORK because we'll have made so many little changes to the .PHP files that the patch program won't be able to handle them all. It's worth a try, though. If you've done something that you think might be of value to the rest of the Gallery community, how about mailing that patch file to us along with a description of what it does so that we can take a look at it? We don't want your work to go to waste and we want to make it easy for you to keep upgrading Gallery. 3. UPGRADING FROM V1.1 (OR EARLIER) Many changes have gone into the codebase since v1.1. The upgrade process *should* work smoothly, unless you've modified the code. We've changed the Album data format, and the config file data format so you'll be required to re-run the config wizard, then perform an upgrade on all your albums afterwards. Do not be dismayed -- this is easy! See section 1 for details. HTML_WRAP CHANGES PHP-Nuke 5.0 integration is new in v1.1 and in order to make Gallery a seamless Nuke 5.0 module, we had to make some changes to the html_wrap/ default files. If you look at the new html_wrap/xxx.header.default files, you'll see that we include a file called "wrapper.header". This file (which also lives in html_wrap/) detects whether or not you're running inside PHP-Nuke, and if so it will Do the Right Thing. If you have problems with your customized look and feel after moving to v1.1, I suggest that you move your customized gallery.header and gallery.footer files out of the way and start again with the default ones in the html_wrap directory. CSS CHANGES In order to make sure that Gallery's style doesn't override PHP-Nuke's, we've separated gallery_style.css into two files, embedded_style and standalone_style. When Gallery is embedded, it will use the embedded_style, so be careful of what you put in there (since it can affect Nuke, also). When Gallery is running in standalone mode, it will use both the embedded_style and the standalone_style (in that order). This gives you the freedom to customize the same gallery to run in both modes. If you're upgrading from pre v1.1 and you've customized your gallery_style.css file, you'll need to pull the relevant changes out of your gallery_style.css and put them into either embedded_style or standalone_style, as appropriate. NUKE/POSTNUKE CHANGES We made a change in the Nuke support. In v1.1, if you wanted to rename your Gallery module under Nuke modules directory, you had to modify the $GALLERY_MODULENAME variable in gallery/index.php. Now, we detect the name of the module and use it automatically. When you upgrade you won't need to modify index.php any more. 4. UPGRADING FROM v1.2.x We changed the album and config data versions so you'll have to run through the album upgrade process (see SECTION 1). If you're using the random block, we now put "block-random.php" in the $safe_to_include array in index.php for you; you no longer need to edit this file anymore. 5. UPGRADING FROM v1.3, v1.3.1 We changed the album and config data versions in v1.3.2, so you'll have to run through the album upgrade process (see SECTION 1). We also introduced a new "Can View Full Images" permission. As part of the album upgrade process we assign this permission to anybody who already had the "Can View Album" permission so it should maintain your status quo. Gallery no longer requires usage of php_short_tags. If you have short_tag support enabled only for Gallery, you can change short_open_tag = On to: short_open_tag = Off in your php.ini file to disable PHP's usage of short tags. Note that you will almost certainly need to re-run the Gallery configuration wizard after doing this, since the automatically generated config.php file will still have short tags. Also note that this may break other applications you have on your site that use short tags.