===============
Upgrading Silva
===============

Introduction
------------

This document contains generic upgrade instructions for minor and
major version upgrades of Silva. For information about particular
upgrade issues please read the ``Upgrade issues``_ section of this
document. Reading this is strongly recommended!

Upgrades
========

Minor upgrades
--------------

If you are upgrading Silva minor versions (1.1.1 to 1.1.2 for
instance), you shouldn't need to do anything special; just install the
updated Silva Products (the ``-all`` distribution) and restart
Zope.

Note that it is a good idea to remove the previous versions of the
Products before you install the new ones, even for small upgrades.

If there are problems, please try pressing ``Refresh all`` in
``service_extensions``, available in the Zope Management Interface
under the ``services`` tab in your Silva root.


Major upgrades
--------------

This section applies to major upgrades. You cannot skip upgrades, so
if you are upgrading from Silva 0.9.1 to Silva 0.9.3, you have to
first upgrade to version 0.9.2.

Steps to take during a major Silva upgrade:

- *Recommended*: It always makes sense to backup your Silva data
  before upgrading, especially when doing major upgrades. The
  simplest way to make sure you have a functional backup is to backup
  the whole ZODB. To do this, make a backup copy of var/Data.fs.

- Download the Silva-all distribution of the new major version of
  Silva you want to upgrade.

- Remove the previous versions of the products (see PRODUCTS.txt for a
  list) from your Zope's Products directory.

- Unpack the Silva-all distribution in your Zope's Products directory.

- If You have optional products installed which are either Silva
  extension or may interfere with Silva in some way, You may want to
  check if they have a compatible version and upgrade, if required.
  Again see PRODUCTS.txt for a list of dependencies and recommended
  version numbers.

- Restart Zope.

- In your Silva root, click on the ``services`` tab.

- Go to ``service_extensions``, the extensions service.

- Click on the 'upgrade content' button. This will automatically
  refresh all installed Silva extensions as well as upgrade the Silva
  content that needs upgrading. Note that this will take a while if
  your site is large.

- When testing Silva, it may be the WYSIWYG editor (Kupu) still
  retrieves files cached by the browser from a previous version of
  Silva. Clearing the browser cache should help.

Upgrading from Silva 2.1 to Silva 2.2
----------------------

The "table of contents" element in kupu and the forms-based editor
has been deprecated, in favor of a table of contents codesource.  
An upgrader for Silva 2.2 content upgrade converts any and all TOC
elements in silvaxml into this code source.  For large silva sites,
this upgrader may cause the Silva 2.2 content upgrade to take a long
time.  As always during upgrades, be sure to disable access to
silva sites!

Upgrading from Silva 2.0 to Silva 2.1
-------------------------------------

Zope 2.11.1 or later is required to run Silva 2.1

Upgrading from Silva 1.6 to Silva 2.0
-------------------------------------

Zope 2.10.2 or later is required to run Silva2.0, so you will have to
upgrade your Zope besides the regular upgrade step.

Upgrading from Silva 1.5 to Silva 1.6
-------------------------------------

Zope 2.8.6 is required for Silva 1.6, apart from that see notes for 1.5.

Upgrading from Silva 1.4 to Silva 1.5
-------------------------------------

Zope 2.8.5 or later is required to run Silva 1.5, so you will have to
upgrade your Zope besides the regular upgrade step.

PlacelessTranslationService is not in use by Silva anymore, so can be
safely removed.

Five 1.2 is a requirement of this version of Silva; see PRODUCTS.txt
for more information about requirements. In particular, Silva 1.5
also needs the latest version of Formulator.

Upgrading from Silva 1.3 to Silva 1.4
-------------------------------------

Apart from the regular 'upgrade' step, you'll have to upgrade to Zope
2.7.8, as this is now the recommended Zope version. This Silva version will
no longer work properly with Zope-2.7.7.

A field has been added to the silva-extra metadata-set. To ensure that
existing content keeps working, go to service_metdata in services, remove
the silva-extra metadataset, go to service extensions and click refresh
on Silva.

Upgrading from Silva 1.2 to silva 1.3
-------------------------------------

Apart from the regular 'upgrade' step, you'll have to upgrade to Zope
2.7.7, as this is now the recommended Zope version.

Upgrading from Silva 1.2 to Silva 1.2.1
---------------------------------------

Even though this is a minor upgrade you will have to update your Zope
version: Zopes <= 2.7.4 are not supported anymore. Zope 2.7.5 is now
the recommended version (this due to a change in the Zope core).

Upgrading from Silva 1.1 to Silva 1.2
-------------------------------------

With the the introduction of the subscriptions feature and a rewrite of the
Silva Indexers, upgrading Silva 1.1 to Silva 1.2 now requires a content
upgrade. The upgrade procedure is described in the previous section "Major
upgrades".

This upgrade will add and update an index in the service_catalog and it will
trigger an update on all existing Indexer objects in the Silva site.

If you want to enable the Silva UI in different languages, install
PlacelessTranslationService 1.0. This is included in the Silva-all
distribution.

If you want to enable the new (since 1.1) XSLT support, please see the
section "XSLT Support" in INSTALL.txt.

Upgrading from Silva 1.0 to Silva 1.1
-------------------------------------

Upgrading Silva 1.0 to Silva 1.1 does not require a content
upgrade. Although this is a major upgrade, the procedure for upgrading
is therefore the same as for minor upgrades. A ``Refresh all`` in
``service_extensions`` is however required in this upgrade.

If you want to enable the new XSLT support, please see the section
"XSLT Support" in INSTALL.txt.

Note that if you are upgrading from 1.1b1 to 1.1b2 or 1.1.x, you
should do the following:

* go to the services tab in the Silva root

* remove service_renderer_registry

* go to service_extensions and do a ``Refresh all``

Upgrading from Silva 0.9.3 to Silva 1.0
---------------------------------------

The instructions in the "Major upgrades" section should be
followed. In addition, read this section for special details.

If you are using ExtFile for image storage, upgrading to version 1.4.2
of ExtFile is required.

You need to update your layout templates. Note: this also affects the
Silva UI rendering; if your sidebar doesn't render properly, you need
to update ``frontend.css``. To see how, please read the section
``Layout templates``_ below.

Note: upgrading from Silva 1.0b1 to Silva 1.0 requires a 'refresh all'
in service extensions.

Upgrading from Silva 0.9.2 to Silva 0.9.3
-----------------------------------------

Please read the UPGRADE.txt included with the 0.9.3 release.

Upgrading from Silva 0.9.1 to Silva 0.9.2
-----------------------------------------

Please read the UPGRADE.txt included with the 0.9.2 release.

Upgrade issues
==============

Layout templates
----------------

The upgrade will likely carry new default versions of the page
templates and style sheets used for presentation of the public
website. You can install these examples in your Silva root by going to
``service_extensions`` in the Silva Root and pressing the `install
default layout` button.

Doing this won't overwrite your public layout code; the only thing
overwritten will be whatever in the current 'default_' objects, if any
exist. You can then look at this code for examples. If you're
satisfied with their contents you can also rename them to versions
without the ``default_`` prefix and start using them.

Because some API changes in Silva might break the layout templates and
scripts in the Silva root, you should take a good look at these new
versions if you have any problems with your current templates.

In particular, ``frontend.css`` changes regularly. If you haven't
changed this stylesheet just remove the old version and rename
``default_frontend.css`` to ``frontend.css``. If you see red text in
the SMI or preview this is a signal that your ``frontend.css`` should be
updated, since you're missing key selectors for content display.

If you are using the default layout (most likely not), or for some
other reason can safely throw away your old layout, you can have the
new layout installed directly. First, delete or rename the following
objects in the Silva root (from the Zope Management Interface):

frontend.css, get_metadata_element, index_html, layout_macro.html,
standard_error_message, standard_unauthorized_message

Then go to ``service_extensions`` and click ``install default
layout``. The new versions of the default layout should now be
installed.

For more info about layouts see:

http://www.infrae.com/products/silva/docs/SiteManager#templates

Reserved ids
------------

After an upgrade you may find that some links, image references,
etc. are broken which had been valid before the
upgrade.

In Silva 0.9.3, several reserved ids are added. When the upgrade
script encounters an object with a reserved id, the object is
renamed. The renaming is logged to Zope's event log on the file
system. You need to manually fix all links and references to those
object, since the upgrade script doesn't upgrade those! The reserved
ids are the following:

Members, REQUEST, acl_users, cached, cancel, code_source, content,
content.html, delete, edit, elements, form, fulltext, getBatch,
getDocmaFormatName, globals, index_html, insert, layout_macro.html,
logout, lookup, memberform, override.html, placeholder, preview_html,
promptWindow, quotify, redirect, render, save, search,
standard_error_message, standard_unauthorized_message, submit, up

It is also not allowed to have an id starting with 'aq', 'get',
'manage', 'service' and 'set'.

Brokenness after upgrading Silva to a newer version
---------------------------------------------------

Most of the problems after upgrading Silva are caused by missing
product refresh via the ``service_extensions`` service in the Silva
Root.

Major releases usually need a content upgrade, too. This is also
available via the ``service_extensions`` by the ``upgrade content``
button.

Please try at least a ``refresh all`` from the ``service_extensions``
before reporting any problems with upgrading.

Also please note in case of several Silva Roots within one Zope
instance you need to run the upgrade for all Silva Roots separately
after installation of an upgrades Silva version.

Symptoms of not removing a earlier versions of Silva
----------------------------------------------------

Another possible source of problems arises if one installs a newer
version of Silva in place over an existing one (i.e. by unpacking a
*.tgz into a directory where an older version of Silva is installed,
overwriting the older version.

This will not remove files present in the older version. As it often
happens that some files are move around (or removed at all) between
releases, one would have some old files still around after the
upgrade, which may lead to malfunction of the product.

Especially there have been reports of an "AttributeError" with an
error value of "__hash__" after upgrading which seemed to be caused by
this failure to remove previous versions.




