![[tokkee]](http://tokkee.org/images/avatar.png){kind=avatar}
diff --git a/doc/upgrading.txt b/doc/upgrading.txt
index f230c88888b7d246c5b33d116911898e5ca73273..2636b6297b31dfe6d67722531dd315220b94a812 100644 (file)
--- a/doc/upgrading.txt
+++ b/doc/upgrading.txt
accordingly. Note that there is information about upgrade procedures in the
`administration guide`_.
+If a specific version transition isn't mentioned here (eg. 0.6.7 to 0.6.8)
+then you don't need to do anything. If you're upgrading from 0.5.6 to
+0.6.8 though, you'll need to check the "0.5 to 0.6" and "0.6.x to 0.6.3"
+steps.
+
.. contents::
+Migrating from 1.4.2 to 1.4.3
+=============================
+
+If you are using the MySQL backend you will need to replace some indexes
+that may have been created by version 1.4.2.
+
+You should to access your MySQL database directly and remove any indexes
+with a name ending in "_key_retired_idx". You should then re-add them with
+the same spec except the key column name needs a size. So an index on
+"_user (__retired, _name)" should become "_user (__retired, _name(255))".
+
+
+Migrating from 1.4.x to 1.4.2
+=============================
+
+You should run the "roundup-admin migrate" command for your tracker once
+you've installed the latest codebase.
+
+Do this before you use the web, command-line or mail interface and before
+any users access the tracker.
+
+This command will respond with either "Tracker updated" (if you've not
+previously run it on an RDBMS backend) or "No migration action required"
+(if you have run it, or have used another interface to the tracker,
+or are using anydbm).
+
+It's safe to run this even if it's not required, so just get into the
+habit.
+
+
+Migrating from 1.3.3 to 1.4.0
+=============================
+
+Value of the "refwd_re" tracker configuration option (section "mailgw")
+is treated as UTF-8 string. In previous versions, it was ISO8859-1.
+
+If you have running trackers based on the classic template, please
+update the messagesummary detector as follows::
+
+ --- detectors/messagesummary.py 17 Apr 2003 03:26:38 -0000 1.1
+ +++ detectors/messagesummary.py 3 Apr 2007 06:47:21 -0000 1.2
+ @@ -8,7 +8,7 @@
+ if newvalues.has_key('summary') or not newvalues.has_key('content'):
+ return
+
+ - summary, content = parseContent(newvalues['content'], 1, 1)
+ + summary, content = parseContent(newvalues['content'], config=db.config)
+ newvalues['summary'] = summary
+
+In the latest version we have added some database indexes to the
+SQL-backends (mysql, postgresql, sqlite) for speeding up building the
+roundup-index for full-text search. We recommend that you create the
+following database indexes on the database by hand::
+
+ CREATE INDEX words_by_id ON __words (_textid)
+ CREATE UNIQUE INDEX __textids_by_props ON __textids (_class, _itemid, _prop)
+
+Migrating from 1.2.x to 1.3.0
+=============================
+
+1.3.0 Web interface changes
+---------------------------
+
+Some of the HTML files in the "classic" and "minimal" tracker templates
+were changed to fix some bugs and clean them up. You may wish to compare
+them to the HTML files in your tracker and apply any changes.
+
+
+Migrating from 1.1.2 to 1.2.0
+=============================
+
+1.2.0 Sorting and grouping by multiple properties
+-------------------------------------------------
+
+Starting with this version, sorting and grouping by multiple properties
+is possible. This means that request.sort and request.group are now
+lists. This is reflected in several places:
+
+ * ``renderWith`` now has list attributes for ``sort`` and ``group``,
+ where you previously wrote::
+
+ renderWith(... sort=('-', 'activity'), group=('+', 'priority')
+
+ you write now::
+
+ renderWith(... sort=[('-', 'activity')], group=[('+', 'priority')]
+
+ * In templates that permit to edit sorting/grouping, request.sort and
+ request.group are (possibly empty) lists. You can now sort and group
+ by multiple attributes. For an example, see the classic template. You
+ may want search for the variable ``n_sort`` which can be set to the
+ number of sort/group properties.
+
+ * Templates that diplay new headlines for each group of items with
+ equal group properties can now use the modified ``batch.propchanged``
+ method that can take several properties which are checked for
+ changes. See the example in the classic template which makes use of
+ ``batch.propchanged``.
+
+Migrating from 1.1.0 to 1.1.1
+=============================
+
+1.1.1 "Clear this message"
+--------------------------
+
+In 1.1.1, the standard ``page.html`` template includes a "clear this message"
+link in the green "ok" message bar that appears after a successful edit
+(or other) action.
+
+To include this in your tracker, change the following in your ``page.html``
+template::
+
+ <p tal:condition="options/ok_message | nothing" class="ok-message"
+ tal:repeat="m options/ok_message" tal:content="structure m">error</p>
+
+to be::
+
+ <p tal:condition="options/ok_message | nothing" class="ok-message">
+ <span tal:repeat="m options/ok_message"
+ tal:content="structure string:$m <br/ > " />
+ <a class="form-small" tal:attributes="href request/current_url"
+ i18n:translate="">clear this message</a>
+ </p>
+
+
+If you implemented the "clear this message" in your 1.1.0 tracker, then you
+should change it to the above and it will work much better!
+
+
+Migrating from 1.0.x to 1.1.0
+=============================
+
+1.1 Login "For Session Only"
+----------------------------
+
+In 1.1, web logins are alive for the length of a session only, *unless* you
+add the following to the login form in your tracker's ``page.html``::
+
+ <input type="checkbox" name="remember" id="remember">
+ <label for="remember" i18n:translate="">Remember me?</label><br>
+
+See the classic tracker ``page.html`` if you're unsure where this should
+go.
+
+
+1.1 Query Display Name
+----------------------
+
+The ``dispname`` web variable has been renamed ``@dispname`` to avoid
+clashing with other variables of the same name. If you are using the
+display name feature, you will need to edit your tracker's ``page.html``
+and ``issue.index.html`` pages to change ``dispname`` to ``@dispname``.
+
+A side-effect of this change is that the renderWith method used in the
+``home.html`` page may now take a dispname argument.
+
+
+1.1 "Clear this message"
+------------------------
+
+In 1.1, the standard ``page.html`` template includes a "clear this message"
+link in the green "ok" message bar that appears after a successful edit
+(or other) action.
+
+To include this in your tracker, change the following in your ``page.html``
+template::
+
+ <p tal:condition="options/ok_message | nothing" class="ok-message"
+ tal:repeat="m options/ok_message" tal:content="structure m">error</p>
+
+to be::
+
+ <p tal:condition="options/ok_message | nothing" class="ok-message">
+ <span tal:repeat="m options/ok_message"
+ tal:content="structure string:$m <br/ > " />
+ <a class="form-small" tal:attributes="href string:issue${context/id}"
+ i18n:translate="">clear this message</a>
+ </p>
+
+
+Migrating from 0.8.x to 1.0
+===========================
+
+1.0 New Query Permissions
+-------------------------
+
+New permissions are defined for query editing and viewing. To include these
+in your tracker, you need to add these lines to your tracker's
+``schema.py``::
+
+ # Users should be able to edit and view their own queries. They should also
+ # be able to view any marked as not private. They should not be able to
+ # edit others' queries, even if they're not private
+ def view_query(db, userid, itemid):
+ private_for = db.query.get(itemid, 'private_for')
+ if not private_for: return True
+ return userid == private_for
+ def edit_query(db, userid, itemid):
+ return userid == db.query.get(itemid, 'creator')
+ p = db.security.addPermission(name='View', klass='query', check=view_query,
+ description="User is allowed to view their own and public queries")
+ db.security.addPermissionToRole('User', p)
+ p = db.security.addPermission(name='Edit', klass='query', check=edit_query,
+ description="User is allowed to edit their queries")
+ db.security.addPermissionToRole('User', p)
+ p = db.security.addPermission(name='Create', klass='query',
+ description="User is allowed to create queries")
+ db.security.addPermissionToRole('User', p)
+
+and then remove 'query' from the line::
+
+ # Assign the access and edit Permissions for issue, file and message
+ # to regular users now
+ for cl in 'issue', 'file', 'msg', 'query', 'keyword':
+
+so it looks like::
+
+ for cl in 'issue', 'file', 'msg', 'keyword':
+
+
+Migrating from 0.8.0 to 0.8.3
+=============================
+
+0.8.3 Nosy Handling Changes
+---------------------------
+
+A change was made to fix a bug in the ``nosyreaction.py`` standard
+detector. To incorporate this fix in your trackers, you will need to copy
+the ``nosyreaction.py`` file from the ``templates/classic/detectors``
+directory of the source to your tracker's ``templates`` directory.
+
+If you have modified the ``nosyreaction.py`` file from the standard
+version, you will need to roll your changes into the new file.
+
+
+Migrating from 0.7.1 to 0.8.0
+=============================
+
+You *must* fully uninstall previous Roundup version before installing
+Roundup 0.8.0. If you don't do that, ``roundup-admin install``
+command may fail to function properly.
+
+0.8.0 Backend changes
+---------------------
+
+Backends 'bsddb' and 'bsddb3' are removed. If you are using one of these,
+you *must* migrate to another backend before upgrading.
+
+
+0.8.0 API changes
+-----------------
+
+Class.safeget() was removed from the API. Test your item ids before calling
+Class.get() instead.
+
+
+0.8.0 New tracker layout
+------------------------
+
+The ``config.py`` file has been replaced by ``config.ini``. You may use the
+roundup-admin command "genconfig" to generate a new config file::
+
+ roundup-admin genconfig <tracker home>/config.ini
+
+and modify the values therein based on the contents of your old config.py.
+In most cases, the names of the config variables are the same.
+
+The ``select_db.py`` file has been replaced by a file in the ``db``
+directory called ``backend_name``. As you might guess, this file contains
+just the name of the backend. To figure what the contents of yours should
+be, use the following table:
+
+ ================================ =========================
+ ``select_db.py`` contents ``backend_name`` contents
+ ================================ =========================
+ from back_anydbm import ... anydbm
+ from back_metakit import ... metakit
+ from back_sqlite import ... sqlite
+ from back_mysql import ... mysql
+ from back_postgresql import ... postgresql
+ ================================ =========================
+
+The ``dbinit.py`` file has been split into two new files,
+``initial_data.py`` and ``schema.py``. The contents of this file are:
+
+``initial_data.py``
+ You don't need one of these as your tracker is already initialised.
+
+``schema.py``
+ Copy the body of the ``def open(name=None)`` function from your old
+ tracker's ``dbinit.py`` file to this file. As the lines you're copying
+ aren't part of a function definition anymore, one level of indentation
+ needs to be removed (remove only the leading four spaces on each
+ line).
+
+ The first few lines -- those starting with ``from roundup.hyperdb
+ import ...`` and the ``db = Database(config, name)`` line -- don't
+ need to be copied. Neither do the last few lines -- those starting
+ with ``import detectors``, down to ``return db`` inclusive.
+
+You may remove the ``__init__.py`` module from the "detectors" directory as
+it is no longer used.
+
+There's a new way to write extension code for Roundup. If you have code in
+an ``interfaces.py`` file you should move it. See the `customisation
+documentation`_ for information about how extensions are now written.
+Note that some older trackers may use ``interfaces.py`` to customise the
+mail gateway behaviour. You will need to keep your ``interfaces.py`` file
+if this is the case.
+
+
+0.8.0 Permissions Changes
+-------------------------
+
+The creation of a new item in the user interfaces is now controlled by the
+"Create" Permission. You will need to add an assignment of this Permission
+to your users who are allowed to create items. The most common form of this
+is the following in your ``schema.py`` added just under the current
+assignation of the Edit Permission::
+
+ for cl in 'issue', 'file', 'msg', 'query', 'keyword':
+ p = db.security.getPermission('Create', cl)
+ db.security.addPermissionToRole('User', p)
+
+You will need to explicitly let anonymous users access the web interface so
+that regular users are able to see the login form. Note that almost all
+trackers will need this Permission. The only situation where it's not
+required is in a tracker that uses an HTTP Basic Authenticated front-end.
+It's enabled by adding to your ``schema.py``::
+
+ p = db.security.getPermission('Web Access')
+ db.security.addPermissionToRole('Anonymous', p)
+
+Finally, you will need to enable permission for your users to edit their
+own details by adding the following to ``schema.py``::
+
+ # Users should be able to edit their own details. Note that this
+ # permission is limited to only the situation where the Viewed or
+ # Edited item is their own.
+ def own_record(db, userid, itemid):
+ '''Determine whether the userid matches the item being accessed.'''
+ return userid == itemid
+ p = db.security.addPermission(name='View', klass='user', check=own_record,
+ description="User is allowed to view their own user details")
+ p = db.security.addPermission(name='Edit', klass='user', check=own_record,
+ description="User is allowed to edit their own user details")
+ db.security.addPermissionToRole('User', p)
+
+
+0.8.0 Use of TemplatingUtils
+----------------------------
+
+If you used custom python functions in TemplatingUtils, they must
+be moved from interfaces.py to a new file in the ``extensions`` directory.
+
+Each Function that should be available through TAL needs to be defined
+as a toplevel function in the newly created file. Furthermore you
+add an inititialization function, that registers the functions with the
+tracker.
+
+If you find this too tedious, donfu wrote an automatic init function that
+takes an existing TemplatingUtils class, and registers all class methods
+that do not start with an underscore. The following hack should be placed
+in the ``extensions`` directory alongside other extensions::
+
+ class TemplatingUtils:
+ # copy from interfaces.py
+
+ def init(tracker):
+ util = TemplatingUtils()
+
+ def setClient(tu):
+ util.client = tu.client
+ return util
+
+ def execUtil(name):
+ return lambda tu, *args, **kwargs: \
+ getattr(setClient(tu), name)(*args, **kwargs)
+
+ for name in dir(util):
+ if callable(getattr(util, name)) and not name.startswith('_'):
+ tracker.registerUtil(name, execUtil(name))
+
+
+0.8.0 Logging Configuration
+---------------------------
+
+See the `administration guide`_ for information about configuring the new
+logging implemented in 0.8.0.
+
+
+Migrating from 0.7.2 to 0.7.3
+=============================
+
+0.7.3 Configuration
+-------------------
+
+If you choose, you may specify the directory from which static files are
+served (those which use the URL component ``@@file``). Currently the
+directory defaults to the ``TEMPLATES`` configuration variable. You may
+define a new variable, ``STATIC_FILES`` which overrides this value for
+static files.
+
+
+Migrating from 0.7.0 to 0.7.2
+=============================
+
+0.7.2 DEFAULT_TIMEZONE is now required
+--------------------------------------
+
+The DEFAULT_TIMEZONE configuration variable is now required. Add the
+following to your tracker's ``config.py`` file::
+
+ # You may specify a different default timezone, for use when users do not
+ # choose their own in their settings.
+ DEFAULT_TIMEZONE = 0 # specify as numeric hour offest
+
+
+Migrating from 0.7.0 to 0.7.1
+=============================
+
+0.7.1 Permission assignments
+----------------------------
+
+If you allow anonymous access to your tracker, you might need to assign
+some additional View (or Edit if your tracker is that open) permissions
+to the "anonymous" user. To do so, find the code in your ``dbinit.py`` that
+says::
+
+ for cl in 'issue', 'file', 'msg', 'query', 'keyword':
+ p = db.security.getPermission('View', cl)
+ db.security.addPermissionToRole('User', p)
+ p = db.security.getPermission('Edit', cl)
+ db.security.addPermissionToRole('User', p)
+ for cl in 'priority', 'status':
+ p = db.security.getPermission('View', cl)
+ db.security.addPermissionToRole('User', p)
+
+Add add a line::
+
+ db.security.addPermissionToRole('Anonymous', p)
+
+next to the existing ``'User'`` lines for the Permissions you wish to
+assign to the anonymous user.
+
Migrating from 0.6 to 0.7
=========================
0.7.0 Getting the current user id
---------------------------------
-Removed Database.curuserid attribute. Any code referencing this attribute
-should be replaced with a call to Database.getuid().
+The Database.curuserid attribute has been removed.
+
+Any code referencing this attribute should be replaced with a
+call to Database.getuid().
0.7.0 ZRoundup changes
:action :required :template :remove:messages ...
-should become:
+should become::
@action @required @template @remove@messages ...
roundup-users mailing list for help if you're unsure.
+0.7.0 Edit collision detection
+------------------------------
+
+Roundup now detects collisions with editing in the web interface (that is,
+two people editing the same item at the same time).
+
+You must copy the ``_generic.collision.html`` file from Roundup source in
+the ``templates/classic/html`` directory. to your tracker's ``html``
+directory.
+
+
Migrating from 0.6.x to 0.6.3
=============================
.. _`customisation documentation`: customizing.html
.. _`security documentation`: security.html
-.. _`administration guide`: admin.html
+.. _`administration guide`: admin_guide.html