Goals

Here we'll discuss

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

DTML pages

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

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.

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:

Recap

You've learned...

Next is configuring.