Mercurial Repository: p/roundup/code: doc/upgrading.txt comparison

comparison doc/upgrading.txt @ 1356:83f33642d220 maint-0.5

[[Metadata associated with this commit was garbled during conversion from CVS to Subversion.]]

author	Richard Jones <richard@users.sourceforge.net>
date	Thu, 09 Jan 2003 22:59:22 +0000
parents
children

comparison

equal deleted inserted replaced

-:3d0158c8c32b
+:83f33642d220
+======================================
+Upgrading to newer versions of Roundup
+======================================
+Please read each section carefully and edit your tracker home files
+accordingly.
+.. contents::
+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. 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 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 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
+is as simple as copying the "db" directory and all its contents from your
+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:
+- HEADER_INDEX_LINKS
+- HEADER_ADD_LINKS
+- HEADER_SEARCH_LINKS
+- SEARCH_FILTERS
+- DEFAULT_INDEX
+- UNASSIGNED_INDEX
+- USER_INDEX
+- ISSUE_FILTER
+The new security implementation will require additions to the dbinit module,
+but also removes the need for the following tracker config variables:
+- ANONYMOUS_ACCESS
+- ANONYMOUS_REGISTER
+but requires two new variables which define the Roles assigned to users who
+register through the web and e-mail interfaces:
+- NEW_WEB_USER_ROLES
+- NEW_EMAIL_USER_ROLES
+in both cases, 'User' is a good initial setting. To emulate
+``ANONYMOUS_ACCESS='deny'``, remove all "View" Permissions from the
+"Anonymous" Role. To emulate ``ANONYMOUS_REGISTER='deny'``, remove the "Web
+Registration" and/or the "Email Registration" Permission from the "Anonymous"
+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 tracker has changed a fair bit. Where it used
+to contain::
+# WARNING: DO NOT EDIT THIS FILE!!!
+from roundup.backends.back_anydbm import Database
+it must now contain::
+# 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 tracker from::
+import instance_config
+from roundup import roundupdb
+from select_db import Database
+from roundup.roundupdb import Class, FileClass
+class Database(roundupdb.Database, select_db.Database):
+''' Creates a hybrid database from:
+. the selected database back-end from select_db
+. the roundup extensions from roundupdb
+'''
+pass
+class IssueClass(roundupdb.IssueClass):
+''' issues need the email information
+'''
+pass
+to::
+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
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Journalling has been optimised for storage. Journalling of links has been
+turned back on by default. If your tracker has a large user base, you may wish
+to turn off journalling of nosy list, message author and message recipient
+link and unlink events. You do this by adding ``do_journal='no'`` to the Class
+initialisation in your dbinit. For example, your *msg* class initialisation
+probably looks like this::
+msg = FileClass(db, "msg",
+author=Link("user"), recipients=Multilink("user"),
+date=Date(),         summary=String(),
+files=Multilink("file"),
+messageid=String(),  inreplyto=String())
+to turn off journalling of author and recipient link events, add
+``do_journal='no'`` to the ``author=Link("user")`` part of the statement,
+like so::
+msg = FileClass(db, "msg",
+author=Link("user", do_journal='no'),
+recipients=Multilink("user", do_journal='no'),
+date=Date(),         summary=String(),
+files=Multilink("file"),
+messageid=String(),  inreplyto=String())
+Nosy list link event journalling is actually turned off by default now. If you
+want to turn it on, change to your issue class' nosy list, change its
+definition from::
+issue = IssueClass(db, "issue",
+assignedto=Link("user"), topic=Multilink("keyword"),
+priority=Link("priority"), status=Link("status"))
+to::
+issue = IssueClass(db, "issue", nosy=Multilink("user", do_journal='yes'),
+assignedto=Link("user"), topic=Multilink("keyword"),
+priority=Link("priority"), status=Link("status"))
+noting that your definition of the nosy Multilink will override the normal one.
+0.5.0 User schema changes
+~~~~~~~~~~~~~~~~~~~~~~~~~
+Users have two more properties, "queries" and "roles". You'll have something
+like this in your dbinit module now::
+user = Class(db, "user",
+username=String(),   password=Password(),
+address=String(),    realname=String(),
+phone=String(),      organisation=String(),
+alternate_addresses=String())
+user.setkey("username")
+and you'll need to add the new properties and the new "query" class to it
+like so::
+query = Class(db, "query",
+klass=String(),     name=String(),
+url=String())
+query.setkey("name")
+# Note: roles is a comma-separated string of Role names
+user = Class(db, "user",
+username=String(),   password=Password(),
+address=String(),    realname=String(),
+phone=String(),      organisation=String(),
+alternate_addresses=String(),
+queries=Multilink('query'), roles=String())
+user.setkey("username")
+The "queries" property is used to store off the user's favourite database
+queries. The "roles" property is explained below in `0.5.0 Security
+Settings`_.
+0.5.0 Security Settings
+~~~~~~~~~~~~~~~~~~~~~~~
+See the `security documentation`_ for an explanation of how the new security
+system works. In a nutshell though, the security is handled as a four step
+process:
+1. Permissions are defined as having a name and optionally a hyperdb class
+they're specific to,
+2. Roles are defined that have one or more Permissions,
+3. Users are assigned Roles in their "roles" property, and finally
+4. Roundup checks that users have appropriate Permissions at appropriate times
+(like editing issues).
+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::
+import detectors
+detectors.init(db)
+return db
+and what we need to do is insert some commands that will set up the security
+parameters. Right above the ``import detectors`` line, you'll want to insert
+these lines::
+#
+# SECURITY SETTINGS
+#
+# new permissions for this schema
+for cl in 'issue', 'file', 'msg', 'user':
+db.security.addPermission(name="Edit", klass=cl,
+description="User is allowed to edit "+cl)
+db.security.addPermission(name="View", klass=cl,
+description="User is allowed to access "+cl)
+# Assign the access and edit permissions for issue, file and message
+# to regular users now
+for cl in 'issue', 'file', 'msg':
+p = db.security.getPermission('View', cl)
+db.security.addPermissionToRole('User', p)
+p = db.security.getPermission('Edit', cl)
+db.security.addPermissionToRole('User', p)
+# and give the regular users access to the web and email interface
+p = db.security.getPermission('Web Access')
+db.security.addPermissionToRole('User', p)
+p = db.security.getPermission('Email Access')
+db.security.addPermissionToRole('User', p)
+# May users view other user information? Comment these lines out
+# if you don't want them to
+p = db.security.getPermission('View', 'user')
+db.security.addPermissionToRole('User', p)
+# Assign the appropriate permissions to the anonymous user's Anonymous
+# Role. Choices here are:
+# - Allow anonymous users to register through the web
+p = db.security.getPermission('Web Registration')
+db.security.addPermissionToRole('Anonymous', p)
+# - Allow anonymous (new) users to register through the email gateway
+p = db.security.getPermission('Email Registration')
+db.security.addPermissionToRole('Anonymous', p)
+# - Allow anonymous users access to the "issue" class of data
+#   Note: this also grants access to related information like files,
+#         messages, statuses etc that are linked to issues
+#p = db.security.getPermission('View', 'issue')
+#db.security.addPermissionToRole('Anonymous', p)
+# - Allow anonymous users access to edit the "issue" class of data
+#   Note: this also grants access to create related information like
+#         files and messages etc that are linked to issues
+#p = db.security.getPermission('Edit', 'issue')
+#db.security.addPermissionToRole('Anonymous', p)
+# oh, g'wan, let anonymous access the web interface too
+p = db.security.getPermission('Web Access')
+db.security.addPermissionToRole('Anonymous', p)
+Note in the comments there the places where you might change the permissions
+to restrict users or grant users more access. If you've created additional
+classes that users should be able to edit and view, then you should add them
+to the "new permissions for this schema" section at the start of the security
+block. Then add them to the "Assign the access and edit permissions" section
+too, so people actually have the new Permission you've created.
+One final change is needed that finishes off the security system's
+initialisation. We need to add a call to ``db.post_init()`` at the end of the
+dbinit open() function. Add it like this::
+import detectors
+detectors.init(db)
+# schema is set up - run any post-initialisation
+db.post_init()
+return db
+You may verify the setup of Permissions and Roles using the new
+"``roundup-admin security``" command.
+0.5.0 User changes
+~~~~~~~~~~~~~~~~~~
+To support all those schema changes, you'll need to massage your user database
+a little too, to:
+1. make sure there's an "anonymous" user - this user is mandatory now and is
+the one that unknown users are logged in as.
+2. make sure all users have at least one Role.
+If you don't have the "anonymous" user, create it now with the command::
+roundup-admin create user username=anonymous roles=Anonymous
+making sure the capitalisation is the same as above. Once you've done that,
+you'll need to set the roles property on all users to a reasonable default.
+The admin user should get "Admin", the anonymous user "Anonymous"
+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 <tracker home> fixroles
+0.5.0 CGI interface changes
+---------------------------
+The CGI interface code was completely reorganised and largely rewritten. The
+end result is that this section of your tracker interfaces module will need
+changing from::
+from roundup import cgi_client, mailgw
+from roundup.i18n import _
+class Client(cgi_client.Client):
+''' derives basic CGI implementation from the standard module,
+with any specific extensions
+'''
+pass
+to::
+from roundup import mailgw
+from roundup.cgi import 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 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
+sourceforge, http://roundup.sf.net/)
+0.5.0 Detectors
+---------------
+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 :)
+Migrating from 0.4.1 to 0.4.2
+=============================
+0.4.2 Configuration
+-------------------
+The USER_INDEX definition introduced in 0.4.1 was too restrictive in its
+allowing replacement of 'assignedto' with the user's userid. Users must change
+the None value of 'assignedto' to 'CURRENT USER' (the string, in quotes) for
+the replacement behaviour to occur now.
+The new configuration variables are:
+- EMAIL_KEEP_QUOTED_TEXT
+- EMAIL_LEAVE_BODY_UNCHANGED
+- ADD_RECIPIENTS_TO_NOSY
+See the sample configuration files in::
+<roundup source>/roundup/templates/classic/instance_config.py
+and::
+<roundup source>/roundup/templates/extended/instance_config.py
+and the `customisation documentation`_ for information on how they're used.
+0.4.2 Changes to detectors
+--------------------------
+You will need to copy the detectors from the distribution into your instance
+home "detectors" directory. If you used the classic schema, the detectors
+are in::
+<roundup source>/roundup/templates/classic/detectors/
+If you used the extended schema, the detectors are in::
+<roundup source>/roundup/templates/extended/detectors/
+The change means that schema-specific code has been removed from the
+mail gateway and cgi interface and made into auditors:
+- nosyreactor.py has now got an updatenosy auditor which updates the nosy
+list with author, recipient and assignedto information.
+- statusauditor.py makes the unread or resolved -> chatting changes and
+presets the status of an issue to unread.
+There's also a bug or two fixed in the nosyreactor code.
+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 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::
+<td>
+<display call="field('superseder', showid=1)">
+<display call="classhelp('issue', 'id,title', label='list', width=500)">
+<property name="superseder">
+<br>View: <display call="link('superseder', showid=1)">
+</property>
+</td>
+The stylesheets have been cleaned up too. You may want to use the newer
+versions in::
+<roundup source>/roundup/templates/<template>/html/default.css
+Migrating from 0.4.0 to 0.4.1
+=============================
+0.4.1 Files storage
+-------------------
+Messages and files from newly created issues will be put into subdierectories
+in thousands e.g. msg123 will be put into files/msg/0/msg123, file2003
+will go into files/file/2/file2003. Previous messages are still found, but
+could be put into this structure.
+0.4.1 Configuration
+-------------------
+To allow more fine-grained access control, the variable used to check
+permission to auto-register users in the mail gateway is now called
+ANONYMOUS_REGISTER_MAIL rather than overloading ANONYMOUS_REGISTER. If the
+variable doesn't exist, then ANONYMOUS_REGISTER is tested as before.
+Configuring the links in the web header is now easier too. The following
+variables have been added to the classic instance_config.py::
+HEADER_INDEX_LINKS   - defines the "index" links to be made available
+HEADER_ADD_LINKS     - defines the "add" links
+DEFAULT_INDEX        - specifies the index view for DEFAULT
+UNASSIGNED_INDEX     - specifies the index view for UNASSIGNED
+USER_INDEX           - specifies the index view for USER
+See the <roundup source>/roundup/templates/classic/instance_config.py for more
+information - including how the variables are to be set up. Most users will
+just be able to copy the variables from the source to their instance home. If
+you've modified the header by changing the source of the interfaces.py file in
+the instance home, you'll need to remove that customisation and move it into
+the appropriate variables in instance_config.py.
+The extended schema has similar variables added too - see the source for more
+info.
+0.4.1 Alternate E-Mail Addresses
+--------------------------------
+If you add the property "alternate_addresses" to your user class, your users
+will be able to register alternate email addresses that they may use to
+communicate with roundup as. All email from roundup will continue to be sent
+to their primary address.
+If you have not edited the dbinit.py file in your instance home directory,
+you may simply copy the new dbinit.py file from the core code. If you used
+the classic schema, the interfaces file is in::
+<roundup source>/roundup/templates/classic/dbinit.py
+If you used the extended schema, the file is in::
+<roundup source>/roundup/templates/extended/dbinit.py
+If you have modified your dbinit.py file, you need to edit the dbinit.py
+file in your instance home directory. Find the lines which define the user
+class::
+user = Class(db, "msg",
+username=String(),   password=Password(),
+address=String(),    realname=String(),
+phone=String(),      organisation=String(),
+alternate_addresses=String())
+You will also want to add the property to the user's details page. The
+template for this is the "user.item" file in your instance home "html"
+directory. Similar to above, you may copy the file from the roundup source if
+you haven't modified it. Otherwise, add the following to the template::
+<display call="multiline('alternate_addresses')">
+with appropriate labelling etc. See the standard template for an idea.
+Migrating from 0.3.x to 0.4.0
+=============================
+0.4.0 Message-ID and In-Reply-To addition
+-----------------------------------------
+0.4.0 adds the tracking of messages by message-id and allows threading
+using in-reply-to. Most e-mail clients support threading using this
+feature, and we hope to add support for it to the web gateway. If you
+have not edited the dbinit.py file in your instance home directory, you may
+simply copy the new dbinit.py file from the core code. If you used the
+classic schema, the interfaces file is in::
+<roundup source>/roundup/templates/classic/dbinit.py
+If you used the extended schema, the file is in::
+<roundup source>/roundup/templates/extended/dbinit.py
+If you have modified your dbinit.py file, you need to edit the dbinit.py
+file in your instance home directory. Find the lines which define the msg
+class::
+msg = FileClass(db, "msg",
+author=Link("user"), recipients=Multilink("user"),
+date=Date(),         summary=String(),
+files=Multilink("file"))
+and add the messageid and inreplyto properties like so::
+msg = FileClass(db, "msg",
+author=Link("user"), recipients=Multilink("user"),
+date=Date(),         summary=String(),
+files=Multilink("file"),
+messageid=String(),  inreplyto=String())
+Also, configuration is being cleaned up. This means that your dbinit.py will
+also need to be changed in the open function. If you haven't changed your
+dbinit.py, the above copy will be enough. If you have, you'll need to change
+the line (round line 50)::
+db = Database(instance_config.DATABASE, name)
+to::
+db = Database(instance_config, name)
+0.4.0 Configuration
+--------------------
+``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.
+The mail gateway now checks ``ANONYMOUS_REGISTER`` to see if unknown users
+are to be automatically registered with the tracker. If it is set to "deny"
+then unknown users will not have access. If it is set to "allow" they will be
+automatically registered with the tracker.
+0.4.0 CGI script roundup.cgi
+----------------------------
+The CGI script has been updated with some features and a bugfix, so you should
+copy it from the roundup cgi-bin source directory again. Make sure you update
+the ROUNDUP_INSTANCE_HOMES after the copy.
+0.4.0 Nosy reactor
+------------------
+The nosy reactor has also changed - copy the nosyreactor.py file from the core
+source::
+<roundup source>/roundup/templates/<template>/detectors/nosyreactor.py
+to your instance home "detectors" directory.
+0.4.0 HTML templating
+---------------------
+The field() function was incorrectly implemented - links and multilinks now
+display as text fields when rendered using field(). To display a menu (drop-
+down or select box) you need to use the menu() function.
+Migrating from 0.2.x to 0.3.x
+=============================
+0.3.x Cookie Authentication changes
+-----------------------------------
+0.3.0 introduces cookie authentication - you will need to copy the
+interfaces.py file from the roundup source to your instance home to enable
+authentication. If you used the classic schema, the interfaces file is in::
+<roundup source>/roundup/templates/classic/interfaces.py
+If you used the extended schema, the file is in::
+<roundup source>/roundup/templates/extended/interfaces.py
+If you have modified your interfaces.Client class, you will need to take
+note of the login/logout functionality provided in roundup.cgi_client.Client
+(classic schema) or roundup.cgi_client.ExtendedClient (extended schema) and
+modify your instance code apropriately.
+0.3.x Password encoding
+-----------------------
+This release also introduces encoding of passwords in the database. If you
+have not edited the dbinit.py file in your instance home directory, you may
+simply copy the new dbinit.py file from the core code. If you used the
+classic schema, the interfaces file is in::
+<roundup source>/roundup/templates/classic/dbinit.py
+If you used the extended schema, the file is in::
+<roundup source>/roundup/templates/extended/dbinit.py
+If you have modified your dbinit.py file, you may use encoded passwords:
+1. Edit the dbinit.py file in your instance home directory
+a. At the first code line of the open() function::
+from roundup.hyperdb import String, Date, Link, Multilink
+alter to include Password, as so::
+from roundup.hyperdb import String, Password, Date, Link, Multilink
+b. Where the password property is defined (around line 66)::
+user = Class(db, "user",
+username=String(),   password=String(),
+address=String(),    realname=String(),
+phone=String(),      organisation=String())
+user.setkey("username")
+alter the "password=String()" to "password=Password()"::
+user = Class(db, "user",
+username=String(),   password=Password(),
+address=String(),    realname=String(),
+phone=String(),      organisation=String())
+user.setkey("username")
+2. Any existing passwords in the database will remain cleartext until they
+are edited. It is recommended that at a minimum the admin password be
+changed immediately::
+roundup-admin -i <instance home> set user1 password=<new password>
+0.3.x Configuration
+-------------------
+FILTER_POSITION, ANONYMOUS_ACCESS, ANONYMOUS_REGISTER have been added to
+the instance_config.py. Simplest solution is to copy the default values from
+template in the core source.
+MESSAGES_TO_AUTHOR has been added to the IssueClass in dbinit.py. Set to 'yes'
+to send nosy messages to the author. Default behaviour is to not send nosy
+messages to the author. You will need to add MESSAGES_TO_AUTHOR to your
+dbinit.py in your instance home.
+0.3.x CGI script roundup.cgi
+----------------------------
+There have been some structural changes to the roundup.cgi script - you will
+need to install it again from the cgi-bin directory of the source
+distribution. Make sure you update the ROUNDUP_INSTANCE_HOMES after the
+copy.
+.. _`customisation documentation`: customizing.html
+.. _`security documentation`: security.html

Mercurial > p > roundup > code

comparison doc/upgrading.txt @ 1356:83f33642d220 maint-0.5