![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/upgrading.txt b/doc/upgrading.txt
index c14a40ce02bfd497da16a7e5d7b4b9524c9847d4..f01150cd554b46f8bab157e86b86f7fa403283f9 100644 (file)
--- a/doc/upgrading.txt
+++ b/doc/upgrading.txt
Upgrading to newer versions of Roundup
======================================
-Please read each section carefully and edit your instance home files
+Please read each section carefully and edit your tracker home files
accordingly.
.. contents::
+Migrating from 0.5 to 0.6
+=========================
+
+0.6.0 Configuration
+-------------------
+
+Introduced EMAIL_FROM_TAG config variable. This value is inserted into
+the From: line of nosy email. If the sending user is "Foo Bar", the
+From: line is usually::
+
+ "Foo Bar" <issue_tracker@tracker.example>
+
+the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so::
+
+ "Foo Bar EMAIL_FROM_TAG" <issue_tracker@tracker.example>
+
+I've altered the mechanism in the detectors __init__.py module so that it
+doesn't cross-import detectors from other trackers (if you run more than one
+in a single roundup-server). This change means that you'll need to copy the
+__init__.py from roundup/templates/classic/detectors/__init__.py to your
+<tracker home>/detectors/__init__.py. Don't worry, the "classic" __init__ is a
+one-size-fits-all, so it'll work even if you've added/removed detectors.
+
+
+0.6.0 Form handling changes
+---------------------------
+
+Roundup's form handling capabilities have been significantly expanded. This
+should not affect users of 0.5 installations - but if you find you're
+getting errors from form submissions, please ask for help on the Roundup
+users mailing list:
+
+ http://lists.sourceforge.net/lists/listinfo/roundup-users
+
+See the customisation doc section on "Form Values" for documentation of the
+new form variables possible.
+
+
+0.6.0 Multilingual character set support
+----------------------------------------
+
+Added internationalization support. This is done via encoding all data
+stored in roundup database to utf-8 (unicode encoding). To support utf-8 in
+web interface you should add the folowing line to your tracker's html/page
+and html/_generic.help files inside <head> tag::
+
+ <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+
+Since latin characters in utf-8 have the same codes as in ASCII table, this
+modification is optional for users who use only plain latin characters.
+
+After this modification, you will be able to see and enter any world
+character via web interface. Data received via mail interface also converted
+to utf-8, however only new messages will be converted. If your roundup
+database contains some of non-ASCII characters in one of 8-bit encoding,
+they will not be visible in new unicode environment. Some of such data (e.g.
+user names, keywords, etc) can be edited by administrator, the others
+(e.g. messages' contents) is not editable via web interface. Currently there
+is no tool for converting such data, the only solution is to close
+appropriate old issues and create new ones with the same content.
+
+0.6.0 User timezone support
+---------------------------
+
+From version 0.6.0 roundup supports displaying of Date data in user' local
+timezone if he/she has provided timezone information. To make it possible
+some modification to tracker's schema and HTML templates are required.
+First you should add string property 'timezone' to user class in dbinit.py
+like this::
+
+ user = Class(db, "user",
+ username=String(), password=Password(),
+ address=String(), realname=String(),
+ phone=String(), organisation=String(),
+ alternate_addresses=String(),
+ queries=Multilink('query'), roles=String(),
+ timezone=String())
+
+And second - html interface. Add following lines to
+$TRACKER_HOME/html/user.item template::
+
+ <tr>
+ <th>Timezone</th>
+ <td tal:content="structure context/timezone/field">timezone</td>
+ </tr>
+
+After that all users should be able to provide their timezone information.
+Timezone should be a positive or negative integer - offset from GMT.
+
+After providing timezone, roundup will show all dates values, found in web
+and mail interfaces in local time. It will also accept any Date info in
+local time, convert and store it in GMT.
+
+However you are not forced to make these modifications. By default roundup
+will assume timezone=0 and will work as previous versions did.
+
+
+0.6.0 Notes for metakit backend users
+-------------------------------------
+
+Roundup 0.6.0 introduced searching on ranges of dates and intervals. To
+support it, some modifications to interval storing routine were made. So if
+your tracker uses metakit backend and your db schema contains intervals
+property, searches on that property will not be accurate for db items that
+was stored before roundup' upgrade. However all new records should be
+searchable on intervals.
+
+It is possible to convert your database to new format: you can export and
+import back all your data (consult "Migrating backends" in "Maintenance"
+documentation). After this operation all your interval properties should
+become searchable.
+
+Users of backends others than metakit should not worry about this issue.
+
+
Migrating from 0.4.x to 0.5.0
=============================
This has been a fairly major revision of Roundup:
1. Brand new, much more powerful, flexible, tasty and nutritious templating.
- Unfortunately, this means all your current templates are useless. Please
- don't hesitate to ask on roundup-users for help (or complete conversions
- if you're completely stuck)!
+ Unfortunately, this means all your current templates are useless. Hopefully
+ the new documentation and examples will be enough to help you make the
+ transition. Please don't hesitate to ask on roundup-users for help (or
+ complete conversions if you're completely stuck)!
2. The database backed got a lot more flexible, allowing Metakit and SQL
- databases! The only SQL database implemented at present is gadfly, but
- others shouldn't be a whole lot more work.
+ databases! The only decent SQL database implemented at present is sqlite,
+ but others shouldn't be a whole lot more work.
3. A brand new, highly flexible and much more robust security system including
a system of Permissions, Roles and Role assignments to users. You may now
define your own Permissions that may be checked in CGI transactions.
4. Journalling has been made less storage-hungry, so has been turned on
by default *except* for author, recipient and nosy link/unlink events. You
- are advised to turn it off in your instances too.
-5. Because of the above changes, the instance configuration has seen some
+ are advised to turn it off in your trackers too.
+5. We've changed the terminology from "instance" to "tracker", to ease the
+ learning curve/impact for new users.
+6. Because of the above changes, the tracker configuration has seen some
major changes. See below for the details.
-Please, *back up your database* before you start the migration process. This
+Please, **back up your database** before you start the migration process. This
is as simple as copying the "db" directory and all its contents from your
-instance to somewhere safe.
+tracker to somewhere safe.
0.5.0 Configuration
-------------------
+First up, rename your ``instance_config.py`` file to just ``config.py``.
+
+Then edit your tracker's ``__init__.py`` module. It'll currently look
+like this::
+
+ from instance_config import *
+ try:
+ from dbinit import *
+ except ImportError:
+ pass # in installdir (probably :)
+ from interfaces import *
+
+and it needs to be::
+
+ import config
+ from dbinit import open, init
+ from interfaces import Client, MailGW
+
Due to the new templating having a top-level ``page`` that defines links for
searching, indexes, adding items etc, the following variables are no longer
used:
- ISSUE_FILTER
The new security implementation will require additions to the dbinit module,
-but also removes the need for the following instance config variables:
+but also removes the need for the following tracker config variables:
- ANONYMOUS_ACCESS
- ANONYMOUS_REGISTER
Role. See the section on customising security in the `customisation
documentation`_ for more information.
+Finally, the following config variables have been renamed to make more sense:
+
+- INSTANCE_HOME -> TRACKER_HOME
+- INSTANCE_NAME -> TRACKER_NAME
+- ISSUE_TRACKER_WEB -> TRACKER_WEB
+- ISSUE_TRACKER_EMAIL -> TRACKER_EMAIL
+
0.5.0 Schema Specification
--------------------------
0.5.0 Database backend changes
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Your select_db module in your instance has changed a fair bit. Where it used
+Your select_db module in your tracker has changed a fair bit. Where it used
to contain::
# WARNING: DO NOT EDIT THIS FILE!!!
# WARNING: DO NOT EDIT THIS FILE!!!
from roundup.backends.back_anydbm import Database, Class, FileClass, IssueClass
+Yes, I realise the irony of the "DO NOT EDIT THIS FILE" statement :)
Note the addition of the Class, FileClass, IssueClass imports. These are very
important, as they're going to make the next change work too. You now need to
-modify the top of the dbinit module in your instance from::
+modify the top of the dbinit module in your tracker from::
import instance_config
from roundup import roundupdb
'''
pass
+to::
-
-to just::
-
- import instance_config
+ import config
from select_db import Database, Class, FileClass, IssueClass
Yes, remove the Database and IssueClass definitions and those other imports.
They're not needed any more!
+Look for places in dbinit.py where ``instance_config`` is used too, and
+rename them ``config``.
+
0.5.0 Journalling changes
~~~~~~~~~~~~~~~~~~~~~~~~~
messageid=String(), inreplyto=String())
Nosy list link event journalling is actually turned off by default now. If you
-want to turn it onn, change to your issue class' nosy list, change its
+want to turn it on, change to your issue class' nosy list, change its
definition from::
issue = IssueClass(db, "issue",
4. Roundup checks that users have appropriate Permissions at appropriate times
(like editing issues).
-Your instance dbinit module's *open* function now has to define any
-Permissions that are specific to your instance, and also the assignment
+Your tracker dbinit module's *open* function now has to define any
+Permissions that are specific to your tracker, and also the assignment
of Permissions to Roles. At the moment, your open function
ends with::
and all other users "User". The ``fixroles.py`` script in the tools directory
will do this. Run it like so (where python is your python 2+ binary)::
- python tools/fixroles.py -i <instance home>
+ python tools/fixroles.py -i <tracker home> fixroles
---------------------------
The CGI interface code was completely reorganised and largely rewritten. The
-end result is that this section of your instance interfaces module will need
+end result is that this section of your tracker interfaces module will need
changing from::
- from roundup import mailgw
- from roundup.cgi import client
+ from roundup import cgi_client, mailgw
+ from roundup.i18n import _
- class Client(client.Client):
+ class Client(cgi_client.Client):
''' derives basic CGI implementation from the standard module,
with any specific extensions
'''
to::
- from roundup import cgi_client, mailgw
- from roundup.i18n import _
+ from roundup import mailgw
+ from roundup.cgi import client
- class Client(cgi_client.Client):
+ class Client(client.Client):
''' derives basic CGI implementation from the standard module,
with any specific extensions
'''
pass
+You will also need to install the new version of roundup.cgi from the source
+cgi-bin directory if you're using it.
+
+
0.5.0 HTML templating
---------------------
-You'll want to make a backup of your current instance html directory. You
-should then copy the html directory from the Roundup source template that you
-used to create your instance, and modify it according to your local schema
-changes.
+You'll want to make a backup of your current tracker html directory. You
+should then copy the html directory from the Roundup source "classic" template
+and modify it according to your local schema changes.
If you need help with the new templating system, please ask questions on the
roundup-users mailing list (available through the roundup project page on
0.5.0 Detectors
---------------
-The nosy reactor has been updated to handle the instance not having an
-"assignedto" property on issues. You may want to copy it into your instance's
+The nosy reactor has been updated to handle the tracker not having an
+"assignedto" property on issues. You may want to copy it into your tracker's
detectors directory. Chances are you've already fixed it though :)
0.4.2 HTML templating changes
-----------------------------
The link() htmltemplate function now has a "showid" option for links and
-multilinks. When true, it only displays the linked node id as the anchor
+multilinks. When true, it only displays the linked item id as the anchor
text. The link value is displayed as a tooltip using the title anchor
attribute. To use in eg. the superseder field, have something like this::
0.4.0 Configuration
--------------------
-``INSTANCE_NAME`` and ``EMAIL_SIGNATURE_POSITION`` have been added to the
+``TRACKER_NAME`` and ``EMAIL_SIGNATURE_POSITION`` have been added to the
instance_config.py. The simplest solution is to copy the default values
from template in the core source.