Here we'll discuss
- upgrading zwiki
- downgrading zwiki
Quick upgrade procedure
- 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.
- 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.
- 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.
- 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
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
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 .)
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.
- 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/setupPagesto 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
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_dtmlproperty described there.
Should be preserved. You might see a hierarchy where before there was only a flat list.
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.
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.
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.
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 .
- how to upgrade a Zwiki installation
- how to avoid problems by downgrading
Next is configuring.