Upgrade best practices

[swguy]

I have found that the following steps make upgrading a less painful process:

When you're maintaining your site:
0. Use templates whereever possible. Be aware of the extra_datafiles and extra_definitions directories too.
1. Every time you customize a core file, copy the original file to <filename>.orig. That way you can easily find all the customizations you need to apply on an upgrade.
2. Every time you apply a mod, keep a copy of the list of the new files you had to install, and use the step above for modifications to existing files (other than templates).
3. As you change files, make notes in a change log so you can see what has changed at a glance.
4. Maintain a pristine copy of the current release, so you have a known good baseline to compare against if your changes go bad.

When you're ready to upgrade:
0. Create a pristine read-only copy of the new release. You will use this when comparing files,
so you have a known baseline.

1. start with the full release, and apply your "custom" template directories:
./includes/languages/english/custom
./includes/languages/english/html_includes/custom
./includes/modules/custom
./includes/templates/custom
./includes/extra_datafiles
./includes/languages/english/extra_definitions/

2. Copy individual files from maintaining step 2 above.

3. Look at the release changelog in the docs directory. Go through the files one by one and see if you've changed them yourself by looking at your old release's ".orig" files, your templates and your personal change log. If you have, apply your changes - compare your old copy, the previous release's copy and the current release's copy of the file to determine what changes are required.

This is not as bad as it sounds. For instance, in 1.3.6, there were over 50 changes in the admin folder which probably didn't require any merging at all for you since you haven't changed them.

4. Rename your admin folder back to "admin." Back up your database, and go to
http://<yoursite>/zc_install to run the upgrade. Name the admin folder back
to its secret name and start testing.

5. Create a new change log for this version, and go back to the "maintenance" procedure above. Keep an eye on the support threads for any contribs you use to see if there are changes for this release.

This works well for me (my 1.3.6 upgrade was less than three hours) but I would be interested in hearing what other Zenners consider to be upgrade (and maintenance) best practices.

Good luck,
Scott

[qhome]

Very good detailed steps.

Often when I make changes to a file and can't do it with zen-magic (admin area usually). I will make copy of the file first and rename the extension_ORIG. Then when upgrading, I globally search for all files named ORIG and back up the replacement version of those since they obviously have customizations in them. Then upload all files, and compare the changes to the new original file with my customized version. There are usually few or no changes to those files anyway.

Takes me a bit less time than 3 hours to do the upgrade but it also depends on whats changed and testing out all the contribs to ensure that they work with the new version.

[profitshock]

That is some excellent advice Scott.

If there was one thing I could add for others to consider, it would be this.

Never underestimate the importance of a back-up.

We all know that the first step we all take before starting any upgrade or update is to back-up our databases and files. Right?

But do we really know that our backup works?

The next thing to do before you start changing and adding files would be to TEST that your back-up actually works. i.e. that you can set up a 'new' shop with it. This is a step many forget but doing this I think serves three important purposes.

1. It proves you DO have a working back-up that you CAN reinstall if needed. Having that ability can save some embarrasment.
2. It can also highlight potential problem areas during your upgrade like permissions, typos and general server/ftp gremlins.

and finally

3. It puts you in the right mindset for the upgrade ahead and helps you understand that it may take some time to get right first time. Especially if you have installed a few contributions.

The more contributions you have, the longer your update will take. If time permits allow a yourself a day or two. Better still a week so you can test everything works.

Kev Polley

[swguy]

Originally Posted by profitshock

But do we really know that our backup works?

The next thing to do before you start changing and adding files would be to TEST that your back-up actually works. i.e. that you can set up a 'new' shop with it.

This is a very powerful suggestion. If you have a test system at (say) 1.3.5, and you're wanting to upgrade to 1.3.6, a good ide a would be to follow profitshock's advice, and do your backup (db and code) and then build a brand new 1.3.5 system for comparison out of this. Then use your old 1.3.5 database as the upgrade starting point, and upgrade the database with 1.3.6 code; then apply your changes to get a full 1.3.6 shop. Then if there are discrepancies in behavior of your new shop, you can easily test your old shop's behavior.

Good luck,
Scott