$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.
