upgrading

Goals

Here we'll discuss

• upgrading zwiki
• downgrading zwiki

Quick upgrade procedure

1. Find out what you've got and what you need to upgrade to

   Check your current zwiki version by visiting .../SOMEPAGE/zwiki_version (or look in /Control_Panel/Products or ZWiki/version.txt). Check the current requirements . Check the ReleaseNotes, KnownIssues and latest zwiki.org functionality to find out where zwiki is at. Especially, check the upgrade notes sections of ReleaseNotes. The larger your version jump, the more likely it is you may need to take some extra step.

2. Back up

   If you're in any doubt, and wiki uptime is important, make a backup of Data.fs at this point for convenient quick roll-back. The wise will of course have a system backup plan in place as well. Zwiki upgrades/downgrades have never yet caused data loss or any serious problem, but there's always a first time. It's also a good idea to copy your old Products/ZWiki directory to Products/old/ZWiki, again for convenience if you need to do a quick roll-back.

3. Install new Zwiki version

   Check the requirements and make sure you have the appropriate Zope version for the Zwiki version you're installing. If you are stuck with an older version of Zope, you can check ZopeWiki:CompatibilityMatrix to find the latest version of Zwiki approved for that release (probably 0.34) and download that one instead.

4. Extra steps

   Again, check the Upgrade Notes in ReleaseNotes, for each release since the one you upgraded from, for any extra steps or things to be aware of. Finally, it's not strictly necessary but a good practice to visit SOMEPAGE/upgradeAll at this point. This will upgrade properties on and re-render all pages, preemptively, so it doesn't have to be done when a user next visits the page. You can monitor this in the zope EventLog.

More upgrade notes

upgradeAll

Zwiki does most data upgrades transparently when viewing pages, but some, more expensive or invasive upgrades and integrity checks are done only when you manually visit SOMEPAGE/upgradeAll (you'll need Manage properties permission on the wiki folder).

This upgrades and pre-renders all pages in the wiki, checks the page hierarchy, etc. It's usually not necessary to run this, but after a big upgrade or if you see problems it's probably a good idea. It's harmless to do it every time. In a large wiki, it can take quite a while; you can monitor its progress in the event log . (If you are curious about exactly what happens during automatic or manual upgrades, here is the code .)

Product code

This is a standard zope product upgrade; it is normally painless. Any existing wikis should keep working. If they don't, downgrade zwiki again. Your wiki content will almost certainly not be harmed.

Pages

• Page objects will be auto-upgraded if needed, usually when they are first viewed after the upgrade. If you later downgrade Zwiki, it's possible you could see glitches or problems due to the upgraded pages.
• Pages cache their rendered output. After a major upgrade, or if you see rendering problems, it may be worth clearing out these render caches to make sure all your pages are rendered by the latest code. upgradeAll does this.
• if you have Zwiki help pages in your wiki, they may be out of date; you should update them, or delete them and link to http://zwiki.org, or delete them and visit SOMEPAGE/setupPages to install the default wiki pages again.
• Page ids are checked for conformance with the page name, and will be changed if necessary.
• Issue pages with the old IssueNoXXXX ... names will be renamed to the new #N ... style.

DTML pages

If you are using DTML code in some of your wiki pages - eg the old RecentChanges? page - they may break due to:

• API changes - update them or replace them with the latest versions from Products/ZWiki/content/. Or,
• DTML no longer enabled by default - just delete them so that the built-in forms will be used. Or, if you have read configuring and still want DTML enabled, add the allow_dtml property described there.

Page hierarchy

Should be preserved. You might see a hierarchy where before there was only a flat list.

Catalog

If you are using a ZCatalog in your wiki, you might need or want to update it after a zwiki upgrade. You can visit SOMEPAGE/setupCatalog (or /setupTracker) to add any required new indexes and metadata. This won't remove old obsolete ones, though. To be sure of a clean, up-to-date catalog you could remove the old one first - unless you are in a CMF/Plone site, where it's shared.

Customized skin templates

If you have customized zwiki's skin (cf CustomizingTheSkin ) or you are upgrading from a very old version, you may need to update or remove your custom page templates/dtml methods to fix problems, or to see the latest features.

• Removing expendable templates - This is simplest. Delete (or rename) them. Now your wiki will be using the zwiki defaults, and future upgrades will be simpler.
• Upgrading a template - If it's still working and looking ok, leave it alone. Otherwise: compare your customized version with the latest version in ZWiki/skins or on zwiki.org, and either merge the desired enhancements with your version, or port your customizations to the latest version. Replace your custom template with the result.

CMF/Plone

Occasionally you might need to re-install Zwiki in your CMF site(s) to see the latest changes, like the new actions in 0.25. This will be noted in the release notes' upgrade notes section when necessary.

In Plone 2 this can be done by clicking Zwiki upgrade in plone setup -> install products. Actually, this may be broken; if so click uninstall and then reinstall.

Wiki templates

If you have wiki templates installed in /Control_Panel/Products/ZWiki, they are not affected, though if they include DTML pages or skin templates these may need updating due to API changes.

allowed_page_types

If you configured the allowed_page_types property a very long time ago, you may need to replace the page type ids in there as described in configuring.

Downgrading Zwiki

You might want to do this if you upgrade and hit a problem that you can't solve and which hasn't appeared in KnownIssues yet. There are three scenarios:

• restore ZODB and downgrade Zwiki

  Before upgrading, you backed up Data.fs and Products/ZWiki. Restore both of these and restart zope. This is like going back in time. Easy, wasn't it ?

• downgrade Zwiki

  Restore the old Products/ZWiki directory, either from backup or by downloading the version you were using previously from http://zwiki.org/releases , and restart zope. Everything should work as it did before the upgrade.

• downgrade Zwiki, but problems remain due to data changes

  This almost never happens, but possibly a new version could upgrade some pages or data structures in a way that's backwards-incompatible, causing errors after downgrade. In this event you could: restore an earlier Data.fs from backup; delete the problem pages; look at the wiki folders Undo tab in the ZMI and try to undo all the transactions since upgrade; fix the problem using the zope debug prompt; or ask for help .

Recap

You've learned...

• how to upgrade a Zwiki installation
• how to avoid problems by downgrading

Next is configuring.