Zen Cart Maintenance/Upgrade Best Practices

Relevance: Any version of Zen Cart™

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

Before you touch any code:

1. Look in Admin to see if there's a setting to do what you want to do before changing any files. There are a LOT of settings to turn things off and on and move them to the left and right. Here are some specific pages you should check before changing any files:
   • Configuration > My Store
   • Configuration > Product Listing
   • Configuration > Product Info
   • Configuration > Layout Settings
   • Configuration > Index Listing (there are also settings for the New Products, Featured Products and All Products pages)
   • Catalog > Product Types, then press the Edit Layout button on the right hand side
   • Tools > Layout Boxes Controller (for sideboxes)
2. Try to use CSS to move things instead of modifying one of the template files where possible.
3. If you need to change the code, start by changing the template files. Don't modify the files in template_default; instead, create your own template and modify only the files you need to change. This will mean less work when you upgrade. Follow the guidelines in the Zen Cart template tutorial.
4. If the functionality you need to modify is not in a template, see if it is in an overridable file. Follow the guidelines in the Zen Cart Overrides tutorial.

When you're maintaining your site:

1. Use templates wherever possible.
2. Be aware of the extra_* directories:
   • includes/languages/english/extra_definitions
   • includes/extra_datafiles
   • includes/extra_cart_actions
   • includes/extra_configures
   • includes/functions/extra_functions
3. 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.
4. 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).
5. As you change files, make notes in a change log so you can see what has changed at a glance.
6. 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:

1. Create a pristine read-only copy of the new release. You will use this when comparing files, so you have a known baseline.
2. 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/
   
   

3. Copy individual files from maintaining step 2 above.
4. 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.
5. Back up your database, and go to http://<yoursite>/zc_install to run the upgrade.
6. 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 tip was developed in October 2006, and was first submitted to the Zen Cart Support Forum in this thread on October 31, 2006.

---