Log in
Forgot your password?
UPGRADE.txt
===============
Upgrading Silva
===============
Meta
----
Copyright (c) 2002, 2003, 2004 Infrae. All rights reserved. See also
LICENSE.txt
Valid for: Silva 1.0.x
Author: Martijn Faassen, Jan-Wijbrand Kolman
Email: [email protected], [email protected]
CVS: $Revision: 1.36.8.12.8.14 $
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! If you still run into
trouble, please consult TROUBLESHOOTING.txt.
Upgrades
========
Minor upgrades
--------------
If you are upgrading Silva minor versions (1.0.1 to 1.0.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 making 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.
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.
Please remove (or move away) any old installation of Silva (and its
companion products, see PRODUCTS.txt for a list) before unpacking the
new version in your Products directory to avoid any problems.
Upgrading Silva
===============
Meta
----
Copyright (c) 2002, 2003, 2004 Infrae. All rights reserved. See also
LICENSE.txt
Valid for: Silva 1.0.x
Author: Martijn Faassen, Jan-Wijbrand Kolman
Email: [email protected], [email protected]
CVS: $Revision: 1.36.8.12.8.14 $
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! If you still run into
trouble, please consult TROUBLESHOOTING.txt.
Upgrades
========
Minor upgrades
--------------
If you are upgrading Silva minor versions (1.0.1 to 1.0.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 making 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.
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.
Please remove (or move away) any old installation of Silva (and its
companion products, see PRODUCTS.txt for a list) before unpacking the
new version in your Products directory to avoid any problems.