code-efd2b46ad31c/doc/.cvsignore 0000644 0000000 0000000 00000000452 10134704304 014626 0 ustar 0000000 0000000 announcement.html
customizing.html
developers.html
implementation.html
index.html
installation.html
user_guide.html
FAQ.html
security.html
features.html
upgrading.html
glossary.html
design.html
admin_guide.html
overview.html
mysql.html
postgresql.html
tracker_templates.html
whatsnew-0.7.html
*.ht
code-efd2b46ad31c/doc/FAQ.txt 0000644 0000000 0000000 00000011547 10134704304 014005 0 ustar 0000000 0000000 ===========
Roundup FAQ
===========
:Version: $Revision: 1.18 $
.. contents::
Installation
------------
Living without a mailserver
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Remove the nosy reactor, means delete the tracker file
``detectors/nosyreactor.py`` from your tracker home.
The cgi-bin is very slow!
~~~~~~~~~~~~~~~~~~~~~~~~~
Yep, it sure is. It has to start up Python and load all of the support
libraries for *every* request.
The solution is to use the built in server.
To make Roundup more seamless with your website, you may place the built
in server behind apache and link it into your web tree
How do I put Roundup behind Apache
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
We have a project (foo) running on ``tracker.example:8080``.
We want ``http://tracker.example/issues`` to use the roundup server, so we
set that up on port 8080 on ``tracker.example`` with the ``config.py`` line::
TRACKER_WEB = 'http://tracker.example/issues/'
We have a "foo_issues" tracker and we run the server with::
roundup-server -p 8080 issues=/home/roundup/trackers/issues
Then, on the Apache machine (eg. redhat 7.3 with apache 1.3), in
``/etc/httpd/conf/httpd.conf`` uncomment::
LoadModule proxy_module modules/libproxy.so
and::
AddModule mod_proxy.c
Then add::
# roundup stuff (added manually)
# proxy through one tracker
ProxyPass /issues/ http://tracker.example:8080/issues/
# proxy through all tracker(*)
#ProxyPass /roundup/ http://tracker.example:8080/
Then restart Apache. Now Apache will proxy the request on to the
roundup-server.
Note that if you're proxying multiple trackers, you'll need to use the
second ProxyPass rule described above. It will mean that your TRACKER_WEB
will change to::
TRACKER_WEB = 'http://tracker.example/roundup/issues/'
Once you're done, you can firewall off port 8080 from the rest of the world.
Note that in some situations (eg. virtual hosting) you might need to use a
more complex rewrite rule instead of the simpler ProxyPass above. The
following should be useful as a starting template::
# roundup stuff (added manually)
RewriteEngine on
# General Roundup
RewriteRule ^/roundup$ roundup/ [R]
RewriteRule ^/roundup/(.*)$ http://tracker.example:8080/$1 [P,L]
# Handle Foo Issues
RewriteRule ^/issues$ issues/ [R]
RewriteRule ^/issues/(.*)$ http://tracker.example:8080/issues/$1 [P,L]
Roundup runs very slowly on my XP machine when accessed from the Internet
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The issue is probably related to host name resolution for the client
performing the request. You can turn off the resolution of the names
when it's so slow like this. To do so, edit the module
roundup/scripts/roundup_server.py around line 77 to add the following
to the RoundupRequestHandler class:
def address_string(self):
return self.client_address[0]
Templates
---------
What is that stuff in the tracker html directory?
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This is the template code that Roundup uses to display the various pages.
This is based upon the template markup language in Zope called, oddly
enough "Zope Page Templates". There's documentation in the Roundup
customisation_ documentation. For more information have a look at:
http://www.zope.org/Documentation/Books/ZopeBook/current/contents
specifically chapter 5 "Using Zope Page Templates" and chapter 9 "Advanced
Page Templates".
But I just want a select/option list for ....
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Really easy... edit ``html/issue.item``. For 'nosy', change line 53 from::
to::
For 'assigned to', change line 61 from::
assignedto menu
to::
assignedto menu
Great! But now the select/option list is too big
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Thats a little harder (but only a little ;^)
Again, edit ``html/issue.item``. For nosy, change line 53 from:
to::
for more information, go and read about Zope Page Templates.
Using Roundup
-------------
I got an error and I cant reload it!
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you're using Netscape/Mozilla, try holding shift and pressing reload.
If you're using IE then install Mozilla and try again ;^)
I keep getting logged out
~~~~~~~~~~~~~~~~~~~~~~~~~
Make sure that the TRACKER_WEB setting in your tracker's config.py is set
to the URL of the tracker.
-----------------
Back to `Table of Contents`_
.. _`Table of Contents`: index.html
.. _`customisation`: customizing.html
code-efd2b46ad31c/doc/Makefile 0000644 0000000 0000000 00000001143 10134704304 014264 0 ustar 0000000 0000000 STXTOHTML = rst2html
STXTOHT = rst2ht.py
WEBDIR = ../../htdocs/htdocs/doc-0.7
SOURCE = announcement.txt customizing.txt developers.txt FAQ.txt features.txt \
glossary.txt implementation.txt index.txt design.txt mysql.txt \
installation.txt upgrading.txt user_guide.txt admin_guide.txt \
postgresql.txt tracker_templates.txt whatsnew-0.7.txt
COMPILED := $(SOURCE:.txt=.html)
WEBHT := $(SOURCE:.txt=.ht)
all: ${COMPILED} ${WEBHT}
website: ${WEBHT}
cp *.ht ${WEBDIR}
%.html: %.txt
${STXTOHTML} --report=warning -d $< $@
%.ht: %.txt
${STXTOHT} --report=warning -d $< $@
clean:
rm -f ${COMPILED}
code-efd2b46ad31c/doc/ZPL.txt 0000644 0000000 0000000 00000004476 10134704304 014046 0 ustar 0000000 0000000 Zope Public License (ZPL) Version 2.0
-----------------------------------------------
This software is Copyright (c) Zope Corporation (tm) and
Contributors. All rights reserved.
This license has been certified as open source. It has also
been designated as GPL compatible by the Free Software
Foundation (FSF).
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the
following conditions are met:
1. Redistributions in source code must retain the above
copyright notice, this list of conditions, and the following
disclaimer.
2. Redistributions in binary form must reproduce the above
copyright notice, this list of conditions, and the following
disclaimer in the documentation and/or other materials
provided with the distribution.
3. The name Zope Corporation (tm) must not be used to
endorse or promote products derived from this software
without prior written permission from Zope Corporation.
4. The right to distribute this software or to use it for
any purpose does not give you the right to use Servicemarks
(sm) or Trademarks (tm) of Zope Corporation. Use of them is
covered in a separate agreement (see
http://www.zope.com/Marks).
5. If any files are modified, you must cause the modified
files to carry prominent notices stating that you changed
the files and the date of any change.
Disclaimer
THIS SOFTWARE IS PROVIDED BY ZOPE CORPORATION ``AS IS''
AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT
NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
NO EVENT SHALL ZOPE CORPORATION OR ITS CONTRIBUTORS BE
LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
DAMAGE.
This software consists of contributions made by Zope
Corporation and many individuals on behalf of Zope
Corporation. Specific attributions are listed in the
accompanying credits file.
code-efd2b46ad31c/doc/admin_guide.txt 0000644 0000000 0000000 00000024663 10134704304 015646 0 ustar 0000000 0000000 ====================
Administration Guide
====================
:Version: $Revision: 1.13 $
.. contents::
What does Roundup install?
==========================
There's two "installations" that we talk about when using Roundup:
1. The installation of the software and its support files. This uses the
standard Python mechanism called "distutils" and thus Roundup's core code,
executable scripts and support data files are installed in Python's
directories. On Windows, this is typically:
Scripts
``\scripts\...``
Core code
``\lib\site-packages\roundup\...``
Support files
``\share\roundup\...``
and on Unix-like systems (eg. Linux):
Scripts
``/bin/...``
Core code
``/lib-/site-packages/roundup/...``
Support files
``/share/roundup/...``
2. The installation of a specific tracker. When invoking the roundup-admin
"inst" (and "init") commands, you're creating a new Roundup tracker. This
installs configuration files, HTML templates, detector code and a new
database. You have complete control over where this stuff goes through
both choosing your "tracker home" and the DATABASE variable in
config.py.
Configuring Roundup's Logging of Messages For Sysadmins
=======================================================
You may configure where Roundup logs messages in your tracker's config.py
file. Roundup will use the standard Python logging implementation when
available. If not, then a very basic logging implementation will be used
(see BasicLogging in the roundup.rlog module for details).
Configuration for "logging" module:
- tracker configuration file specifies the location of a logging
configration file as ``LOGGING_CONFIG``
- ``roundup-server`` specifies the location of a logging configuration
file on the command line
Configuration for "BasicLogging" implementation:
- tracker configuration file specifies the location of a log file
``LOGGING_FILENAME``
- tracker configuration file specifies the level to log to as
``LOGGING_LEVEL``
- ``roundup-server`` specifies the location of a log file on the command
line
- ``roundup-server`` specifies the level to log to on the command line
(``roundup-mailgw`` always logs to the tracker's log file)
In both cases, if no logfile is specified then logging will simply be sent
to sys.stderr with only logging of ERROR messages.
Configuring roundup-server
==========================
The basic configuration file layout is as follows (take from the
``roundup-server.ini.example`` file in the "doc" directory)::
[server]
port = 8080
;hostname =
;user =
;group =
;log_ip = yes
;pidfile =
;logfile =
; Add one of these per tracker being served
[tracker_url_component]
home = /path/to/tracker
Values ";commented out" are optional. The meaning of the various options
are as follows:
**port**
Defines the local TCP port to listen for clients on.
**hostname**
Defines the local hostname to listen for clients on. Only required if
"localhost" is not sufficient.
**user** and **group**
Defines the Unix user and group to run the server as. Only work if the
server is started as root.
**log_ip**
If ``yes`` then we log IP addresses against accesses. If ``no`` then we
log the hostname of the client. The latter can be much slower.
**pidfile**
If specified, the server will fork at startup and write its new PID to
the file.
**logfile**
Any unhandled exception messages or other output from Roundup will be
written to this file. It must be specified if **pidfile** is specified.
If per-tracker logging is specified, then very little will be written to
this file.
**example_tracker** sections
These are used to specify which Roundup trackers are to be served up by
roundup-server. Each tracker has its own ``[section]`` with a single
``home`` value defined pointing to the tracker's home. The section name is
used in the URL to select the appropriate reacker. Make sure the name part
doesn't include any url-unsafe characters like spaces. Stick to
alphanumeric characters and you'll be ok.
Users and Security
==================
Roundup holds its own user database which primarily contains a username,
password and email address for the user. Roundup *must* have its own user
listing, in order to maintain internal consistency of its data. It is a
relatively simple exercise to update this listing on a regular basis, or on
demand, so that it matches an external listing (eg. unix passwd file, LDAP,
etc.)
Roundup identifies users in a number of ways:
1. Through the web, users may be identified by either HTTP Basic
Authentication or cookie authentication. If you are running the web
server (roundup-server) through another HTTP server (eg. apache or IIS)
then that server may require HTTP Basic Authentication, and it will pass
the ``REMOTE_USER`` variable through to Roundup. If this variable is not
present, then Roundup defaults to using its own cookie-based login
mechanism.
2. In email messages handled by roundup-mailgw, users are identified by the
From address in the message.
In both cases, Roundup's behaviour when dealing with unknown users is
controlled by Permissions defined in the "SECURITY SETTINGS" section of the
tracker's ``dbinit.py`` module:
Web Registration
If granted to the Anonymous Role, then anonymous users will be able to
register through the web.
Email Registration
If granted to the Anonymous Role, then email messages from unknown users
will result in those users being registered with the tracker.
More information about how to customise your tracker's security settings
may be found in the `customisation documentation`_.
Tasks
=====
Maintenance of Roundup can involve one of the following:
1. `tracker backup`_
2. `software upgrade`_
3. `migrating backends`_
4. `moving a tracker`_
Tracker Backup
--------------
Stop the web and email frontends and to copy the contents of the tracker home
directory to some other place using standard backup tools.
Software Upgrade
----------------
Always make a backup of your tracker before upgrading software. Steps you may
take:
1. Ensure that the unit tests run on your system::
python run_tests.py
2. If you're using an RDBMS backend, make a backup of its contents now.
3. Make a backup of the tracker home itself.
4. Stop the tracker web and email frontends.
5. Follow the steps in the `upgrading documentation`_ for the new version of
the software in the copied.
6. You may test each of the admin tool, web interface and mail gateway using
the new version of the software. To do this, invoke the scripts directly
in the source directory with::
PYTHONPATH=. python roundup/scripts/roundup_server.py
PYTHONPATH=. python roundup/scripts/roundup_admin.py
PYTHONPATH=. python roundup/scripts/roundup_mailgw.py
Note that on Windows, this would read::
C:\sources\roundup-0.7.4> SET PYTHONPATH=.
C:\sources\roundup-0.7.4> python roundup/scripts/roundup_server.py
7. Once you're comfortable that the upgrade will work using that copy, you
should instal the new version of the software::
python setup.py install
8. Restart your tracker web and email frontends.
If something bad happens, you may reinstate your backup of the tracker and
reinstall the older version of the sofware using the same install command::
python setup.py install
Migrating Backends
------------------
1. stop the existing tracker web and email frontends (preventing changes)
2. use the roundup-admin tool "export" command to export the contents of
your tracker to disk
3. copy the tracker home to a new directory
4. change the backend used in the tracker home ``select_db.py`` file
5. delete the "db" directory from the new directory
6. use the roundup-admin "import" command to import the previous export with
the new tracker home
7. test each of the admin tool, web interface and mail gateway using the new
backend
8. move the old tracker home out of the way (rename to "tracker.old") and
move the new tracker home into its place
9. restart web and email frontends
Moving a Tracker
----------------
If you're moving the tracker to a similar machine, you should:
1. install Roundup on the new machine and test that it works there,
2. stop the existing tracker web and email frontends (preventing changes),
3. copy the tracker home directory over to the new machine, and
4. start the tracker web and email frontends on the new machine.
Most of the backends are actually portable across platforms (ie. from Unix to
Windows to Mac). If this isn't the case (ie. the tracker doesn't work when
moved using the above steps) then you'll need to:
1. install Roundup on the new machine and test that it works there,
2. stop the existing tracker web and email frontends (preventing changes),
3. use the roundup-admin tool "export" command to export the contents of
the existing tracker,
4. copy the export to the new machine,
5. use the roundup-admin "import" command to import the tracker on the new
machine, and
6. start the tracker web and email frontends on the new machine.
Running the Servers
===================
Unix
----
On Unix systems, use the scripts/server-ctl script to control the
roundup-server server. Copy it somewhere and edit the variables at the top
to reflect your specific installation.
Windows
-------
On Windows, the roundup-server program runs as a Windows Service, and
therefore may be controlled through the Services control panel. The
roundup-server program may also control the service directly:
**install the service**
``roundup-server -c install``
**start the service**
``roundup-server -c start``
**stop the service**
``roundup-server -c stop``
To bring up the services panel:
Windows 2000 and later
Start/Control Panel/Administrative Tools/Services
Windows NT4
Start/Control Panel/Services
Running the Mail Gateway Script
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The mail gateway script should be scheduled to run regularly on your
Windows server. Normally this will result in a window popping up. The
solution to this is to:
1. Create a new local account on the Roundup server
2. Set the scheduled task to run in the context of this user instead
of your normal login
-------------------
Back to `Table of Contents`_
.. _`Table of Contents`: index.html
.. _`customisation documentation`: customizing.html
.. _`upgrading documentation`: upgrading.html
code-efd2b46ad31c/doc/announcement.txt 0000644 0000000 0000000 00000004752 10134704304 016070 0 ustar 0000000 0000000 I'm proud to release this 7th major feature release of Roundup.
Version 0.7 introduces far too many features to list here so I've put
together a What's New page:
http://roundup.sourceforge.net/doc-0.7/whatsnew-0.7.html
Some highlights:
- added postgresql backend
- trackers using postgresql or mysql backends may have many users
- new "actor" automatic property (user who caused the last "activity")
- RDBMS backends have data typed columns and indexes on several columns
- registration may be concluded by replying to the confirmation email
- HTML templating permission checks are greatly simplified
- database exports now include full journals
- IMAP support in the mail gateway
Known issues:
- the metakit import feature currently has a bug and should not be used
If you're upgrading from an older version of Roundup you *must* follow
the "Software Upgrade" guidelines given in the maintenance documentation.
Roundup requires python 2.1.3 or later for correct operation.
To give Roundup a try, just download (see below), unpack and run::
python demo.py
Source and documentation is available at the website:
http://roundup.sourceforge.net/
Release Info (via download page):
http://sourceforge.net/projects/roundup
Mailing lists - the place to ask questions:
http://sourceforge.net/mail/?group_id=31577
About Roundup
=============
Roundup is a simple-to-use and -install issue-tracking system with
command-line, web and e-mail interfaces. It is based on the winning design
from Ka-Ping Yee in the Software Carpentry "Track" design competition.
Note: Ping is not responsible for this project. The contact for this
project is richard@users.sourceforge.net.
Roundup manages a number of issues (with flexible properties such as
"description", "priority", and so on) and provides the ability to:
(a) submit new issues,
(b) find and edit existing issues, and
(c) discuss issues with other participants.
The system will facilitate communication among the participants by managing
discussions and notifying interested parties when issues are edited. One of
the major design goals for Roundup that it be simple to get going. Roundup
is therefore usable "out of the box" with any python 2.1+ installation. It
doesn't even need to be "installed" to be operational, though a
disutils-based install script is provided.
It comes with two issue tracker templates (a classic bug/feature tracker and
a minimal skeleton) and seven database back-ends (anydbm, bsddb, bsddb3,
sqlite, metakit, mysql and postgresql).
code-efd2b46ad31c/doc/customizing.txt 0000644 0000000 0000000 00000456654 10134704304 015765 0 ustar 0000000 0000000 ===================
Customising Roundup
===================
:Version: $Revision: 1.147 $
.. This document borrows from the ZopeBook section on ZPT. The original is at:
http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx
.. contents::
:depth: 1
What You Can Do
===============
Before you get too far, it's probably worth having a quick read of the Roundup
`design documentation`_.
Customisation of Roundup can take one of six forms:
1. `tracker configuration`_ file changes
2. database, or `tracker schema`_ changes
3. "definition" class `database content`_ changes
4. behavioural changes, through detectors_
5. `security / access controls`_
6. change the `web interface`_
The third case is special because it takes two distinctly different forms
depending upon whether the tracker has been initialised or not. The other two
may be done at any time, before or after tracker initialisation. Yes, this
includes adding or removing properties from classes.
Trackers in a Nutshell
======================
Trackers have the following structure:
=================== ========================================================
Tracker File Description
=================== ========================================================
config.py Holds the basic `tracker configuration`_
dbinit.py Holds the `tracker schema`_
interfaces.py Defines the Web and E-Mail interfaces for the tracker
select_db.py Selects the database back-end for the tracker
db/ Holds the tracker's database
db/files/ Holds the tracker's upload files and messages
detectors/ Auditors and reactors for this tracker
html/ Web interface templates, images and style sheets
=================== ========================================================
Tracker Configuration
=====================
The ``config.py`` located in your tracker home contains the basic
configuration for the web and e-mail components of roundup's interfaces.
As the name suggests, this file is a Python module. This means that any
valid python expression may be used in the file. Mostly though, you'll
be setting the configuration variables to string values. Python string
values must be quoted with either single or double quotes::
'this is a string'
"this is also a string - use it when the value has 'single quotes'"
this is not a string - it's not quoted
Python strings may use formatting that's almost identical to C string
formatting. The ``%`` operator is used to perform the formatting, like
so::
'roundup-admin@%s'%MAIL_DOMAIN
this will create a string ``'roundup-admin@tracker.domain.example'`` if
MAIL_DOMAIN is set to ``'tracker.domain.example'``.
You'll also note some values are set to::
os.path.join(TRACKER_HOME, 'db')
or similar. This creates a new string which holds the path to the
``'db'`` directory in the TRACKER_HOME directory. This is just a
convenience so if the TRACKER_HOME changes you don't have to edit
multiple valoues.
The configuration variables available are:
**TRACKER_HOME** - ``os.path.split(__file__)[0]``
The tracker home directory. The above default code will automatically
determine the tracker home for you, so you can just leave it alone.
**MAILHOST** - ``'localhost'``
The SMTP mail host that roundup will use to send e-mail.
**MAILUSER** - ``()``
If your SMTP mail host requires a username and password for access, then
specify them here. eg. ``MAILUSER = ('username', 'password')``
**MAILHOST_TLS** - ``'no'``
If your SMTP mail host provides or requires TLS (Transport Layer
Security) then set ``MAILHOST_TLS = 'yes'``
**MAILHOST_TLS_KEYFILE** - ``''``
If you're using TLS, you may also set MAILHOST_TLS_KEYFILE to the name of
a PEM formatted file that contains your private key.
**MAILHOST_TLS_CERTFILE** - ``''``
If you're using TLS and have specified a MAILHOST_TLS_KEYFILE, you may
also set MAILHOST_TLS_CERTFILE to the name of a PEM formatted certificate
chain file.
**MAIL_DOMAIN** - ``'tracker.domain.example'``
The domain name used for email addresses.
**DATABASE** - ``os.path.join(TRACKER_HOME, 'db')``
This is the directory that the database is going to be stored in. By default
it is in the tracker home.
**TEMPLATES** - ``os.path.join(TRACKER_HOME, 'html')``
This is the directory that the HTML templates reside in. By default they are
in the tracker home.
**STATIC_FILES** - e.g. ``os.path.join(TRACKER_HOME, 'files')``
This *optional* variable defines the directory that static files are served
from (files with the URL ``/@@file/``). If this is not defined,
then static files are served from the TEMPLATES directory.
**TRACKER_NAME** - ``'Roundup issue tracker'``
A descriptive name for your roundup tracker. This is sent out in e-mails and
appears in the heading of CGI pages.
**TRACKER_EMAIL** - ``'issue_tracker@%s'%MAIL_DOMAIN``
The email address that e-mail sent to roundup should go to. Think of it as the
tracker's personal e-mail address.
**TRACKER_WEB** - ``'http://tracker.example/cgi-bin/roundup.cgi/bugs/'``
The web address that the tracker is viewable at. This will be included in
information sent to users of the tracker. The URL **must** include the
cgi-bin part or anything else that is required to get to the home page of
the tracker. You **must** include a trailing '/' in the URL.
**ADMIN_EMAIL** - ``'roundup-admin@%s'%MAIL_DOMAIN``
The email address that roundup will complain to if it runs into trouble.
**EMAIL_FROM_TAG** - ``''``
Additional text to include in the "name" part of the ``From:`` address used
in nosy messages. If the sending user is "Foo Bar", the ``From:`` line is
usually::
"Foo Bar"
The EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so::
"Foo Bar EMAIL_FROM_TAG"
**ERROR_MESSAGES_TO** - ``'user'``, ``'dispatcher'`` or ``'both'``
Sends error messages to the dispatcher, user, or both. It will use the
``DISPATCHER_EMAIL`` address if set, otherwise it'll use the
``ADMIN_EMAIL`` address.
**DISPATCHER_EMAIL** - ``''``
The email address that Roundup will issue all error messages to. This is
also useful if you want to switch your 'new message' notification to
a central user.
**LOGGGING_CONFIG** - ``os.path.join(TRACKER_HOME, 'logging.ini')``
This variable activates logging of Roundup's internal messages using the
standard python ``logging`` module. The module is configured using the
indicated configuration file. See the `admin guide`_ for more detail.
**LOGGING_FILENAME** - ``'/path/to/log file'``
This variable activates logging of Roundup's internal messages using a
built-in minimal logging service which appends messages to the indicated
file. See the `admin guide`_ for more detail.
**LOGGING_LEVEL** - ``'DEBUG'``, ``'INFO'``, ``'WARNING'`` or ``'ERROR'``
This variable determines the level of messages logged by the built-in
logging service - messages of the level named and higher will be sent to
the ``LOGGING_FILENAME`` file. Not used when the ``LOGGGING_CONFIG``
variable is set. See the `admin guide`_ for more detail.
**MESSAGES_TO_AUTHOR** - ``'new'``, ``'yes'`` or``'no'``
Send nosy messages to the author of the message?
If 'new' is used, then the author will only be sent the message when the
message creates a new issue. If 'yes' then the author will always be sent
a copy of the message they wrote.
**ADD_AUTHOR_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
Does the author of a message get placed on the nosy list automatically?
If ``'new'`` is used, then the author will only be added when a message
creates a new issue. If ``'yes'``, then the author will be added on followups
too. If ``'no'``, they're never added to the nosy.
**ADD_RECIPIENTS_TO_NOSY** - ``'new'``, ``'yes'`` or ``'no'``
Do the recipients (To:, Cc:) of a message get placed on the nosy list?
If ``'new'`` is used, then the recipients will only be added when a message
creates a new issue. If ``'yes'``, then the recipients will be added on
followups too. If ``'no'``, they're never added to the nosy.
**EMAIL_SIGNATURE_POSITION** - ``'top'``, ``'bottom'`` or ``'none'``
Where to place the email signature in messages that Roundup generates.
**EMAIL_KEEP_QUOTED_TEXT** - ``'yes'`` or ``'no'``
Keep email citations. Citations are the part of e-mail which the sender has
quoted in their reply to previous e-mail with ``>`` or ``|`` characters at
the start of the line.
**EMAIL_LEAVE_BODY_UNCHANGED** - ``'no'``
Preserve the email body as is. Enabiling this will cause the entire message
body to be stored, including all citations, signatures and Outlook-quoted
sections (ie. "Original Message" blocks). It should be either ``'yes'``
or ``'no'``.
**MAIL_DEFAULT_CLASS** - ``'issue'`` or ``''``
Default class to use in the mailgw if one isn't supplied in email
subjects. To disable, comment out the variable below or leave it blank.
**HTML_VERSION** - ``'html4'`` or ``'xhtml'``
HTML version to generate. The templates are html4 by default. If you
wish to make them xhtml, then you'll need to change this var to 'xhtml'
too so all auto-generated HTML is compliant.
**EMAIL_CHARSET** - ``utf-8`` (or ``iso-8859-1`` for Eudora users)
Character set to encode email headers with. We use utf-8 by default, as
it's the most flexible. Some mail readers (eg. Eudora) can't cope with
that, so you might need to specify a more limited character set (eg.
'iso-8859-1'.
**DEFAULT_TIMEZONE** - ``0``
Numeric hour timezone offest to be used when displaying local times.
The default timezone is used when users do not choose their own in
their settings.
The default config.py is given below - as you
can see, the MAIL_DOMAIN must be edited before any interaction with the
tracker is attempted.::
# roundup home is this package's directory
TRACKER_HOME=os.path.split(__file__)[0]
# The SMTP mail host that roundup will use to send mail
MAILHOST = 'localhost'
# The domain name used for email addresses.
MAIL_DOMAIN = 'your.tracker.email.domain.example'
# This is the directory that the database is going to be stored in
DATABASE = os.path.join(TRACKER_HOME, 'db')
# This is the directory that the HTML templates reside in
TEMPLATES = os.path.join(TRACKER_HOME, 'html')
# Optional: the directory that static files are served from (files with
# the URL /@@file/). If this is not defined, then static files
# are served from the TEMPLATES directory.
# STATIC_FILES = os.path.join(TRACKER_HOME, 'files')
# A descriptive name for your roundup tracker
TRACKER_NAME = 'Roundup issue tracker'
# The email address that mail to roundup should go to
TRACKER_EMAIL = 'issue_tracker@%s'%MAIL_DOMAIN
# The web address that the tracker is viewable at. This will be
# included in information sent to users of the tracker. The URL MUST
# include the cgi-bin part or anything else that is required to get
# to the home page of the tracker. You MUST include a trailing '/'
# in the URL.
TRACKER_WEB = 'http://tracker.example/cgi-bin/roundup.cgi/bugs/'
# The email address that roundup will complain to if it runs into
# trouble
ADMIN_EMAIL = 'roundup-admin@%s'%MAIL_DOMAIN
# These variables define where to log Roundup's internal messages to.
# You have two choices - either using the standard Python logging module
# or a minimal logging facility built into Roundup. The former is activated
# when you provide a LOGGING_CONFIG variable below which contains the
# configuration of the logging module. The latter is activated when you
# provide the LOGGING_FILENAME and optionally LOGGING_LEVEL variables. If
# none of these variables are defined then only errors will be logged, and
# they will go to stderr. See the Admin Guide for more detail.
# LOGGGING_CONFIG = os.path.join(TRACKER_HOME, 'logging.ini')
# or,
# LOGGING_FILENAME = '/path/to/log file'
# LOGGING_LEVEL = 'INFO' # one of 'DEBUG', 'INFO', 'WARNING', 'ERROR'
# Additional text to include in the "name" part of the From: address
# used in nosy messages. If the sending user is "Foo Bar", the From:
# line is usually: "Foo Bar"
# the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:
# "Foo Bar EMAIL_FROM_TAG"
EMAIL_FROM_TAG = ""
# Send nosy messages to the author of the message
MESSAGES_TO_AUTHOR = 'no' # either 'yes' or 'no'
# Does the author of a message get placed on the nosy list
# automatically? If 'new' is used, then the author will only be
# added when a message creates a new issue. If 'yes', then the
# author will be added on followups too. If 'no', they're never
# added to the nosy.
ADD_AUTHOR_TO_NOSY = 'new' # one of 'yes', 'no', 'new'
# Do the recipients (To:, Cc:) of a message get placed on the nosy
# list? If 'new' is used, then the recipients will only be added
# when a message creates a new issue. If 'yes', then the recipients
# will be added on followups too. If 'no', they're never added to
# the nosy.
ADD_RECIPIENTS_TO_NOSY = 'new' # either 'yes', 'no', 'new'
# Where to place the email signature
EMAIL_SIGNATURE_POSITION = 'bottom' # one of 'top', 'bottom', 'none'
# Keep email citations
EMAIL_KEEP_QUOTED_TEXT = 'no' # either 'yes' or 'no'
# Preserve the email body as is
EMAIL_LEAVE_BODY_UNCHANGED = 'no' # either 'yes' or 'no'
# Default class to use in the mailgw if one isn't supplied in email
# subjects. To disable, comment out the variable below or leave it
# blank. Examples:
MAIL_DEFAULT_CLASS = 'issue' # use "issue" class by default
#MAIL_DEFAULT_CLASS = '' # disable (or just comment the var out)
# HTML version to generate. The templates are html4 by default. If you
# wish to make them xhtml, then you'll need to change this var to 'xhtml'
# too so all auto-generated HTML is compliant.
HTML_VERSION = 'html4' # either 'html4' or 'xhtml'
# Character set to encode email headers with. We use utf-8 by default, as
# it's the most flexible. Some mail readers (eg. Eudora) can't cope with
# that, so you might need to specify a more limited character set (eg.
# 'iso-8859-1'.
EMAIL_CHARSET = 'utf-8'
#EMAIL_CHARSET = 'iso-8859-1' # use this instead for Eudora users
# 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
#
# SECURITY DEFINITIONS
#
# define the Roles that a user gets when they register with the
# tracker these are a comma-separated string of role names (e.g.
# 'Admin,User')
NEW_WEB_USER_ROLES = 'User'
NEW_EMAIL_USER_ROLES = 'User'
Tracker Schema
==============
Note: if you modify the schema, you'll most likely need to edit the
`web interface`_ HTML template files and `detectors`_ to reflect
your changes.
A tracker schema defines what data is stored in the tracker's database.
Schemas are defined using Python code in the ``dbinit.py`` module of your
tracker.
The ``dbinit.py`` module
------------------------
The ``dbinit.py`` module contains two functions:
**open**
This function defines what your tracker looks like on the inside, the
**schema** of the tracker. It defines the **Classes** and **properties**
on each class. It also defines the **security** for those Classes. The
next few sections describe how schemas work and what you can do with
them.
**init**
This function is responsible for setting up the initial state of your
tracker. It's called exactly once - but the ``roundup-admin initialise``
command. See the start of the section on `database content`_ for more
info about how this works.
The "classic" schema
--------------------
The "classic" schema looks like this (see below for the meaning
of ``'setkey'``)::
pri = Class(db, "priority", name=String(), order=String())
pri.setkey("name")
stat = Class(db, "status", name=String(), order=String())
stat.setkey("name")
keyword = Class(db, "keyword", name=String())
keyword.setkey("name")
user = Class(db, "user", username=String(), organisation=String(),
password=String(), address=String(), realname=String(),
phone=String())
user.setkey("username")
msg = FileClass(db, "msg", author=Link("user"), summary=String(),
date=Date(), recipients=Multilink("user"),
files=Multilink("file"))
file = FileClass(db, "file", name=String(), type=String())
issue = IssueClass(db, "issue", topic=Multilink("keyword"),
status=Link("status"), assignedto=Link("user"),
priority=Link("priority"))
issue.setkey('title')
What you can't do to the schema
-------------------------------
You must never:
**Remove the users class**
This class is the only *required* class in Roundup.
**Remove the "username", "address", "password" or "realname" user properties**
Various parts of Roundup require these properties. Don't remove them.
**Change the type of a property**
Property types must *never* be changed - the database simply doesn't take
this kind of action into account. Note that you can't just remove a
property and re-add it as a new type either. If you wanted to make the
assignedto property a Multilink, you'd need to create a new property
assignedto_list and remove the old assignedto property.
What you can do to the schema
-----------------------------
Your schema may be changed at any time before or after the tracker has been
initialised (or used). You may:
**Add new properties to classes, or add whole new classes**
This is painless and easy to do - there are generally no repurcussions
from adding new information to a tracker's schema.
**Remove properties**
Removing properties is a little more tricky - you need to make sure that
the property is no longer used in the `web interface`_ *or* by the
detectors_.
Classes and Properties - creating a new information store
---------------------------------------------------------
In the tracker above, we've defined 7 classes of information:
priority
Defines the possible levels of urgency for issues.
status
Defines the possible states of processing the issue may be in.
keyword
Initially empty, will hold keywords useful for searching issues.
user
Initially holding the "admin" user, will eventually have an entry
for all users using roundup.
msg
Initially empty, will hold all e-mail messages sent to or
generated by roundup.
file
Initially empty, will hold all files attached to issues.
issue
Initially empty, this is where the issue information is stored.
We define the "priority" and "status" classes to allow two things:
reduction in the amount of information stored on the issue and more
powerful, accurate searching of issues by priority and status. By only
requiring a link on the issue (which is stored as a single number) we
reduce the chance that someone mis-types a priority or status - or
simply makes a new one up.
Class and Items
~~~~~~~~~~~~~~~
A Class defines a particular class (or type) of data that will be stored
in the database. A class comprises one or more properties, which gives
the information about the class items.
The actual data entered into the database, using ``class.create()``, are
called items. They have a special immutable property called ``'id'``. We
sometimes refer to this as the *itemid*.
Properties
~~~~~~~~~~
A Class is comprised of one or more properties of the following types:
* String properties are for storing arbitrary-length strings.
* Password properties are for storing encoded arbitrary-length strings.
The default encoding is defined on the ``roundup.password.Password``
class.
* Date properties store date-and-time stamps. Their values are Timestamp
objects.
* Number properties store numeric values.
* Boolean properties store on/off, yes/no, true/false values.
* A Link property refers to a single other item selected from a
specified class. The class is part of the property; the value is an
integer, the id of the chosen item.
* A Multilink property refers to possibly many items in a specified
class. The value is a list of integers.
FileClass
~~~~~~~~~
FileClasses save their "content" attribute off in a separate file from
the rest of the database. This reduces the number of large entries in
the database, which generally makes databases more efficient, and also
allows us to use command-line tools to operate on the files. They are
stored in the files sub-directory of the ``'db'`` directory in your
tracker.
IssueClass
~~~~~~~~~~
IssueClasses automatically include the "messages", "files", "nosy", and
"superseder" properties.
The messages and files properties list the links to the messages and
files related to the issue. The nosy property is a list of links to
users who wish to be informed of changes to the issue - they get "CC'ed"
e-mails when messages are sent to or generated by the issue. The nosy
reactor (in the ``'detectors'`` directory) handles this action. The
superseder link indicates an issue which has superseded this one.
They also have the dynamically generated "creation", "activity" and
"creator" properties.
The value of the "creation" property is the date when an item was
created, and the value of the "activity" property is the date when any
property on the item was last edited (equivalently, these are the dates
on the first and last records in the item's journal). The "creator"
property holds a link to the user that created the issue.
setkey(property)
~~~~~~~~~~~~~~~~
Select a String property of the class to be the key property. The key
property must be unique, and allows references to the items in the class
by the content of the key property. That is, we can refer to users by
their username: for example, let's say that there's an issue in roundup,
issue 23. There's also a user, richard, who happens to be user 2. To
assign an issue to him, we could do either of::
roundup-admin set issue23 assignedto=2
or::
roundup-admin set issue23 assignedto=richard
Note, the same thing can be done in the web and e-mail interfaces.
If a class does not have an "order" property, the key is also used to
sort instances of the class when it is rendered in the user interface.
(If a class has no "order" property, sorting is by the labelproperty of
the class. This is computed, in order of precedence, as the key, the
"name", the "title", or the first property alphabetically.)
create(information)
~~~~~~~~~~~~~~~~~~~
Create an item in the database. This is generally used to create items
in the "definitional" classes like "priority" and "status".
Examples of adding to your schema
---------------------------------
TODO
Detectors - adding behaviour to your tracker
============================================
.. _detectors:
Detectors are initialised every time you open your tracker database, so
you're free to add and remove them any time, even after the database is
initialised via the "roundup-admin initialise" command.
The detectors in your tracker fire *before* (**auditors**) and *after*
(**reactors**) changes to the contents of your database. They are Python
modules that sit in your tracker's ``detectors`` directory. You will
have some installed by default - have a look. You can write new
detectors or modify the existing ones. The existing detectors installed
for you are:
**nosyreaction.py**
This provides the automatic nosy list maintenance and email sending.
The nosy reactor (``nosyreaction``) fires when new messages are added
to issues. The nosy auditor (``updatenosy``) fires when issues are
changed, and figures out what changes need to be made to the nosy list
(such as adding new authors, etc.)
**statusauditor.py**
This provides the ``chatty`` auditor which changes the issue status
from ``unread`` or ``closed`` to ``chatting`` if new messages appear.
It also provides the ``presetunread`` auditor which pre-sets the
status to ``unread`` on new items if the status isn't explicitly
defined.
**messagesummary.py**
Generates the ``summary`` property for new messages based on the message
content.
**userauditor.py**
Verifies the content of some of the user fields (email addresses and
roles lists).
If you don't want this default behaviour, you're completely free to change
or remove these detectors.
See the detectors section in the `design document`__ for details of the
interface for detectors.
__ design.html
Detector API
------------
Auditors are called with the arguments::
audit(db, cl, itemid, newdata)
where ``db`` is the database, ``cl`` is an instance of Class or
IssueClass within the database, and ``newdata`` is a dictionary mapping
property names to values.
For a ``create()`` operation, the ``itemid`` argument is None and
newdata contains all of the initial property values with which the item
is about to be created.
For a ``set()`` operation, newdata contains only the names and values of
properties that are about to be changed.
For a ``retire()`` or ``restore()`` operation, newdata is None.
Reactors are called with the arguments::
react(db, cl, itemid, olddata)
where ``db`` is the database, ``cl`` is an instance of Class or
IssueClass within the database, and ``olddata`` is a dictionary mapping
property names to values.
For a ``create()`` operation, the ``itemid`` argument is the id of the
newly-created item and ``olddata`` is None.
For a ``set()`` operation, ``olddata`` contains the names and previous
values of properties that were changed.
For a ``retire()`` or ``restore()`` operation, ``itemid`` is the id of
the retired or restored item and ``olddata`` is None.
Additional Detectors Ready For Use
----------------------------------
Sample additional detectors that have been found useful will appear in
the ``'detectors'`` directory of the Roundup distribution. If you want
to use one, copy it to the ``'detectors'`` of your tracker instance:
**newissuecopy.py**
This detector sends an email to a team address whenever a new issue is
created. The address is hard-coded into the detector, so edit it
before you use it (look for the text 'team@team.host') or you'll get
email errors!
**creator_resolution.py**
Catch attempts to set the status to "resolved" - if the assignedto
user isn't the creator, then set the status to "confirm-done". Note that
"classic" Roundup doesn't have that status, so you'll have to add it. If
you don't want to though, it'll just use "in-progress" instead.
**email_auditor.py**
If a file added to an issue is of type message/rfc822, we tack on the
extension .eml.
The reason for this is that Microsoft Internet Explorer will not open
things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
they'll just give you an incomprehensible error message. For more
information, see the detector code - it has a length explanation.
Auditor or Reactor?
-------------------
Generally speaking, the following rules should be observed:
**Auditors**
Are used for `vetoing creation of or changes to items`_. They might
also make automatic changes to item properties.
**Reactors**
Detect changes in the database and react accordingly. They should avoid
making changes to the database where possible, as this could create
detector loops.
Vetoing creation of or changes to items
---------------------------------------
Auditors may raise the ``Reject`` exception to prevent the creation of
or changes to items in the database. The mail gateway, for example, will
not attach files or messages to issues when the creation of those files or
messages are prevented through the ``Reject`` exception. It'll also not create
users if that creation is ``Reject``'ed too.
To use, simply add at the top of your auditor::
from roundup.exceptions import Reject
And then when your rejection criteria have been detected, simply::
raise Reject
Generating email from Roundup
-----------------------------
The module ``roundup.mailer`` contains most of the nuts-n-bolts required
to generate email messages from Roundup.
In addition, the ``IssueClass`` methods ``nosymessage()`` and
``send_message()`` are used to generate nosy messages, and may generate
messages which only consist of a change note (ie. the message id parameter
is not required).
Database Content
================
Note: if you modify the content of definitional classes, you'll most
likely need to edit the tracker `detectors`_ to reflect your
changes.
Customisation of the special "definitional" classes (eg. status,
priority, resolution, ...) may be done either before or after the
tracker is initialised. The actual method of doing so is completely
different in each case though, so be careful to use the right one.
**Changing content before tracker initialisation**
Edit the dbinit module in your tracker to alter the items created in
using the ``create()`` methods.
**Changing content after tracker initialisation**
As the "admin" user, click on the "class list" link in the web
interface to bring up a list of all database classes. Click on the
name of the class you wish to change the content of.
You may also use the ``roundup-admin`` interface's create, set and
retire methods to add, alter or remove items from the classes in
question.
See "`adding a new field to the classic schema`_" for an example that
requires database content changes.
Security / Access Controls
==========================
A set of Permissions is built into the security module by default:
- Edit (everything)
- View (everything)
Every Class you define in your tracker's schema also gets an Edit and View
Permission of its own.
The default interfaces define:
- Web Registration
- Web Access
- Web Roles
- Email Registration
- Email Access
These are hooked into the default Roles:
- Admin (Edit everything, View everything, Web Roles)
- User (Web Access, Email Access)
- Anonymous (Web Registration, Email Registration)
And finally, the "admin" user gets the "Admin" Role, and the "anonymous"
user gets "Anonymous" assigned when the database is initialised on
installation. The two default schemas then define:
- Edit issue, View issue (both)
- Edit file, View file (both)
- Edit msg, View msg (both)
- Edit support, View support (extended only)
and assign those Permissions to the "User" Role. Put together, these
settings appear in the ``open()`` function of the tracker ``dbinit.py``
(the following is taken from the "minimal" template's ``dbinit.py``)::
#
# SECURITY SETTINGS
#
# 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)
New User Roles
--------------
New users are assigned the Roles defined in the config file as:
- NEW_WEB_USER_ROLES
- NEW_EMAIL_USER_ROLES
Changing Access Controls
------------------------
You may alter the configuration variables to change the Role that new
web or email users get, for example to not give them access to the web
interface if they register through email.
You may use the ``roundup-admin`` "``security``" command to display the
current Role and Permission configuration in your tracker.
Adding a new Permission
~~~~~~~~~~~~~~~~~~~~~~~
When adding a new Permission, you will need to:
1. add it to your tracker's dbinit so it is created, using
``security.addPermission``, for example::
self.security.addPermission(name="View", klass='frozzle',
description="User is allowed to access frozzles")
will set up a new "View" permission on the Class "frozzle".
2. enable it for the Roles that should have it (verify with
"``roundup-admin security``")
3. add it to the relevant HTML interface templates
4. add it to the appropriate xxxPermission methods on in your tracker
interfaces module
Example Scenarios
~~~~~~~~~~~~~~~~~
**automatic registration of users in the e-mail gateway**
By giving the "anonymous" user the "Email Registration" Role, any
unidentified user will automatically be registered with the tracker
(with no password, so they won't be able to log in through the web
until an admin sets their password). Note: this is the default
behaviour in the tracker templates that ship with Roundup.
**anonymous access through the e-mail gateway**
Give the "anonymous" user the "Email Access" and ("Edit", "issue")
Roles but do not not give them the "Email Registration" Role. This
means that when an unknown user sends email into the tracker, they're
automatically logged in as "anonymous". Since they don't have the
"Email Registration" Role, they won't be automatically registered, but
since "anonymous" has permission to use the gateway, they'll still be
able to submit issues. Note that the Sender information - their email
address - will not be available - they're *anonymous*.
**only developers may be assigned issues**
Create a new Permission called "Fixer" for the "issue" class. Create a
new Role "Developer" which has that Permission, and assign that to the
appropriate users. Filter the list of users available in the assignedto
list to include only those users. Enforce the Permission with an
auditor. See the example
`restricting the list of users that are assignable to a task`_.
**only managers may sign off issues as complete**
Create a new Permission called "Closer" for the "issue" class. Create a
new Role "Manager" which has that Permission, and assign that to the
appropriate users. In your web interface, only display the "resolved"
issue state option when the user has the "Closer" Permissions. Enforce
the Permission with an auditor. This is very similar to the previous
example, except that the web interface check would look like::
**don't give web access to users who register through email**
Create a new Role called "Email User" which has all the Permissions of
the normal "User" Role minus the "Web Access" Permission. This will
allow users to send in emails to the tracker, but not access the web
interface.
**let some users edit the details of all users**
Create a new Role called "User Admin" which has the Permission for
editing users::
db.security.addRole(name='User Admin', description='Managing users')
p = db.security.getPermission('Edit', 'user')
db.security.addPermissionToRole('User Admin', p)
and assign the Role to the users who need the permission.
Web Interface
=============
.. contents::
:local:
The web interface is provided by the ``roundup.cgi.client`` module and
is used by ``roundup.cgi``, ``roundup-server`` and ``ZRoundup``
(``ZRoundup`` is broken, until further notice). In all cases, we
determine which tracker is being accessed (the first part of the URL
path inside the scope of the CGI handler) and pass control on to the
tracker ``interfaces.Client`` class - which uses the ``Client`` class
from ``roundup.cgi.client`` - which handles the rest of the access
through its ``main()`` method. This means that you can do pretty much
anything you want as a web interface to your tracker.
Repercussions of changing the tracker schema
---------------------------------------------
If you choose to change the `tracker schema`_ you will need to ensure
the web interface knows about it:
1. Index, item and search pages for the relevant classes may need to
have properties added or removed,
2. The "page" template may require links to be changed, as might the
"home" page's content arguments.
How requests are processed
--------------------------
The basic processing of a web request proceeds as follows:
1. figure out who we are, defaulting to the "anonymous" user
2. figure out what the request is for - we call this the "context"
3. handle any requested action (item edit, search, ...)
4. render the template requested by the context, resulting in HTML
output
In some situations, exceptions occur:
- HTTP Redirect (generally raised by an action)
- SendFile (generally raised by ``determine_context``)
here we serve up a FileClass "content" property
- SendStaticFile (generally raised by ``determine_context``)
here we serve up a file from the tracker "html" directory
- Unauthorised (generally raised by an action)
here the action is cancelled, the request is rendered and an error
message is displayed indicating that permission was not granted for
the action to take place
- NotFound (raised wherever it needs to be)
this exception percolates up to the CGI interface that called the
client
Determining web context
-----------------------
To determine the "context" of a request, we look at the URL and the
special request variable ``@template``. The URL path after the tracker
identifier is examined. Typical URL paths look like:
1. ``/tracker/issue``
2. ``/tracker/issue1``
3. ``/tracker/@@file/style.css``
4. ``/cgi-bin/roundup.cgi/tracker/file1``
5. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png``
where the "tracker identifier" is "tracker" in the above cases. That means
we're looking at "issue", "issue1", "@@file/style.css", "file1" and
"file1/kitten.png" in the cases above. The path is generally only one
entry long - longer paths are handled differently.
a. if there is no path, then we are in the "home" context. See `the "home"
context`_ below for more information about how it may be used.
b. if the path starts with "@@file" (as in example 3,
"/tracker/@@file/style.css"), then the additional path entry,
"style.css" specifies the filename of a static file we're to serve up
from the tracker TEMPLATES (or STATIC_FILES, if configured) directory.
This is usually the tracker's "html" directory. Raises a SendStaticFile
exception.
c. if there is something in the path (as in example 1, "issue"), it
identifies the tracker class we're to display.
d. if the path is an item designator (as in examples 2 and 4, "issue1"
and "file1"), then we're to display a specific item.
e. if the path starts with an item designator and is longer than one
entry (as in example 5, "file1/kitten.png"), then we're assumed to be
handling an item of a ``FileClass``, and the extra path information
gives the filename that the client is going to label the download
with (i.e. "file1/kitten.png" is nicer to download than "file1").
This raises a ``SendFile`` exception.
Both b. and e. stop before we bother to determine the template we're
going to use. That's because they don't actually use templates.
The template used is specified by the ``@template`` CGI variable, which
defaults to:
- only classname suplied: "index"
- full item designator supplied: "item"
The "home" Context
------------------
The "home" context is special because it allows you to add templated
pages to your tracker that don't rely on a class or item (ie. an issues
list or specific issue).
Let's say you wish to add frames to control the layout of your tracker's
interface. You'd probably have:
- A top-level frameset page. This page probably wouldn't be templated, so
it could be served as a static file (see `serving static content`_)
- A sidebar frame that is templated. Let's call this page
"home.navigation.html" in your tracker's "html" directory. To load that
page up, you use the URL:
/home?@template=navigation
Serving static content
----------------------
See the previous section `determining web context`_ where it describes
``@@file`` paths.
Performing actions in web requests
----------------------------------
When a user requests a web page, they may optionally also request for an
action to take place. As described in `how requests are processed`_, the
action is performed before the requested page is generated. Actions are
triggered by using a ``@action`` CGI variable, where the value is one
of:
**login**
Attempt to log a user in.
**logout**
Log the user out - make them "anonymous".
**register**
Attempt to create a new user based on the contents of the form and then
log them in.
**edit**
Perform an edit of an item in the database. There are some `special form
variables`_ you may use.
**new**
Add a new item to the database. You may use the same `special form
variables`_ as in the "edit" action.
**retire**
Retire the item in the database.
**editCSV**
Performs an edit of all of a class' items in one go. See also the
*class*.csv templating method which generates the CSV data to be
edited, and the ``'_generic.index'`` template which uses both of these
features.
**search**
Mangle some of the form variables:
- Set the form ":filter" variable based on the values of the filter
variables - if they're set to anything other than "dontcare" then add
them to :filter.
- Also handle the ":queryname" variable and save off the query to the
user's query list.
Each of the actions is implemented by a corresponding ``*XxxAction*`` (where
"Xxx" is the name of the action) class in the ``roundup.cgi.actions`` module.
These classes are registered with ``roundup.cgi.client.Client`` which also
happens to be available in your tracker instance as ``interfaces.Client``. So
if you need to define new actions, you may add them there (see `defining new
web actions`_).
Each action class also has a ``*permission*`` method which determines whether
the action is permissible given the current user. The base permission checks
are:
**login**
Determine whether the user has permission to log in. Base behaviour is
to check the user has "Web Access".
**logout**
No permission checks are made.
**register**
Determine whether the user has permission to register. Base behaviour
is to check the user has the "Web Registration" Permission.
**edit**
Determine whether the user has permission to edit this item. Base
behaviour is to check whether the user can edit this class. If we're
editing the "user" class, users are allowed to edit their own details -
unless they try to edit the "roles" property, which requires the
special Permission "Web Roles".
**new**
Determine whether the user has permission to create (or edit) this
item. Base behaviour is to check the user can edit this class. No
additional property checks are made. Additionally, new user items may
be created if the user has the "Web Registration" Permission.
**editCSV**
Determine whether the user has permission to edit this class. Base
behaviour is to check whether the user may edit this class.
**search**
Determine whether the user has permission to search this class. Base
behaviour is to check whether the user may view this class.
Special form variables
----------------------
Item properties and their values are edited with html FORM
variables and their values. You can:
- Change the value of some property of the current item.
- Create a new item of any class, and edit the new item's
properties,
- Attach newly created items to a multilink property of the
current item.
- Remove items from a multilink property of the current item.
- Specify that some properties are required for the edit
operation to be successful.
In the following, values are variable, "@" may be
either ":" or "@", and other text "required" is fixed.
Most properties are specified as form variables:
````
property on the current context item
``"@"``
property on the indicated item (for editing related information)
Designators name a specific item of a class.
````
Name an existing item of class .
``"-"``
Name the th new item of class . If the form
submission is successful, a new item of is
created. Within the submitted form, a particular
designator of this form always refers to the same new
item.
Once we have determined the "propname", we look at it to see
if it's special:
``@required``
The associated form value is a comma-separated list of
property names that must be specified when the form is
submitted for the edit operation to succeed.
When the is missing, the properties are
for the current context item. When is
present, they are for the item specified by
.
The "@required" specifier must come before any of the
properties it refers to are assigned in the form.
``@remove@=id(s)`` or ``@add@=id(s)``
The "@add@" and "@remove@" edit actions apply only to
Multilink properties. The form value must be a
comma-separate list of keys for the class specified by
the simple form variable. The listed items are added
to (respectively, removed from) the specified
property.
``@link@=``
If the edit action is "@link@", the simple form
variable must specify a Link or Multilink property.
The form value is a comma-separated list of
designators. The item corresponding to each
designator is linked to the property given by simple
form variable.
None of the above (ie. just a simple form value)
The value of the form variable is converted
appropriately, depending on the type of the property.
For a Link('klass') property, the form value is a
single key for 'klass', where the key field is
specified in dbinit.py.
For a Multilink('klass') property, the form value is a
comma-separated list of keys for 'klass', where the
key field is specified in dbinit.py.
Note that for simple-form-variables specifiying Link
and Multilink properties, the linked-to class must
have a key field.
For a String() property specifying a filename, the
file named by the form value is uploaded. This means we
try to set additional properties "filename" and "type" (if
they are valid for the class). Otherwise, the property
is set to the form value.
For Date(), Interval(), Boolean(), and Number()
properties, the form value is converted to the
appropriate
Any of the form variables may be prefixed with a classname or
designator.
Two special form values are supported for backwards compatibility:
@note
This is equivalent to::
@link@messages=msg-1
msg-1@content=value
except that in addition, the "author" and "date" properties of
"msg-1" are set to the userid of the submitter, and the current
time, respectively.
@file
This is equivalent to::
@link@files=file-1
file-1@content=value
The String content value is handled as described above for file
uploads.
If both the "@note" and "@file" form variables are
specified, the action::
@link@msg-1@files=file-1
is also performed.
We also check that FileClass items have a "content" property with
actual content, otherwise we remove them from all_props before
returning.
Default templates
-----------------
The default templates are html4 compliant. If you wish to change them to be
xhtml compliant, you'll need to change the ``HTML_VERSION`` configuration
variable in ``config.py`` to ``'xhtml'`` instead of ``'html4'``.
Most customisation of the web view can be done by modifying the
templates in the tracker ``'html'`` directory. There are several types
of files in there. The *minimal* template includes:
**page.html**
This template usually defines the overall look of your tracker. When
you view an issue, it appears inside this template. When you view an
index, it also appears inside this template. This template defines a
macro called "icing" which is used by almost all other templates as a
coating for their content, using its "content" slot. It also defines
the "head_title" and "body_title" slots to allow setting of the page
title.
**home.html**
the default page displayed when no other page is indicated by the user
**home.classlist.html**
a special version of the default page that lists the classes in the
tracker
**classname.item.html**
displays an item of the *classname* class
**classname.index.html**
displays a list of *classname* items
**classname.search.html**
displays a search page for *classname* items
**_generic.index.html**
used to display a list of items where there is no
``*classname*.index`` available
**_generic.help.html**
used to display a "class help" page where there is no
``*classname*.help``
**user.register.html**
a special page just for the user class, that renders the registration
page
**style.css.html**
a static file that is served up as-is
The *classic* template has a number of additional templates.
Note: Remember that you can create any template extension you want to,
so if you just want to play around with the templating for new issues,
you can copy the current "issue.item" template to "issue.test", and then
access the test template using the "@template" URL argument::
http://your.tracker.example/tracker/issue?@template=test
and it won't affect your users using the "issue.item" template.
How the templates work
----------------------
Basic Templating Actions
~~~~~~~~~~~~~~~~~~~~~~~~
Roundup's templates consist of special attributes on the HTML tags.
These attributes form the `Template Attribute Language`_, or TAL.
The basic TAL commands are:
**tal:define="variable expression; variable expression; ..."**
Define a new variable that is local to this tag and its contents. For
example::
In this example, the variable "title" is defined as the result of the
expression "request/description". The "tal:content" command inside the
tag may then use the "title" variable.
**tal:condition="expression"**
Only keep this tag and its contents if the expression is true. For
example::
Display some issue information.
In the example, the
tag and its contents are only displayed if
the user has the "View" permission for issues. We consider the number
zero, a blank string, an empty list, and the built-in variable
nothing to be false values. Nearly every other value is true,
including non-zero numbers, and strings with anything in them (even
spaces!).
**tal:repeat="variable expression"**
Repeat this tag and its contents for each element of the sequence
that the expression returns, defining a new local variable and a
special "repeat" variable for each element. For example::
The first two lines is the classblock definition, which sets up a
condition that only users who have "View" permission for the "category"
object will have this section included in their output. Next comes a
plain "Categories" header in bold. Everyone who can view categories will
get that.
Next comes the link to the editing area of categories. This link will
only appear if the condition - that the user has "Edit" permissions for
the "category" objects - is matched. If they do have permission then
they will get a link to another page which will let the user add new
categories.
Note that if you have permission to *view* but not to *edit* categories,
then all you will see is a "Categories" header with nothing underneath
it. This is obviously not very good interface design, but will do for
now. I just claim that it is so I can add more links in this section
later on. However to fix the problem you could change the condition in
the classblock statement, so that only users with "Edit" permission
would see the "Categories" stuff.
Setting up a page to edit categories
::::::::::::::::::::::::::::::::::::
We defined code in the previous section which let users with the
appropriate permissions see a link to a page which would let them edit
conditions. Now we have to write that page.
The link was for the *item* template of the *category* object. This
translates into Roundup looking for a file called ``category.item.html``
in the ``html`` tracker directory. This is the file that we are going to
write now.
First we add an info tag in a comment which doesn't affect the outcome
of the code at all, but is useful for debugging. If you load a page in a
browser and look at the page source, you can see which sections come
from which files by looking for these comments::
Next we need to add in the METAL macro stuff so we get the normal page
trappings::
Category editing
Category editing
Next we need to setup up a standard HTML form, which is the whole
purpose of this file. We link to some handy javascript which sends the
form through only once. This is to stop users hitting the send button
multiple times when they are impatient and thus having the form sent
multiple times::
`` tags::
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.
__ customizing.html#form-values
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 tag::
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 must 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::
Timezone
timezone
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.
0.6.0 Search page structure
---------------------------
In order to accomodate query editing the search page has been restructured. If
you want to provide your users with query editing, you should update your
search page using the macros detailed in the customisation doc section
`Searching on categories`__.
__ customizing.html#searching-on-categories
Also, the url field in the query class no longer starts with a '?'. You'll need
to remove this question mark from the url field to support queries. There's
a script in the "tools" directory called ``migrate-queries.py`` that should
automatically change any existing queries for you. As always, make a backup
of your database before running such a script.
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. 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 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/templates/classic/instance_config.py
and::
/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/templates/classic/detectors/
If you used the extended schema, the detectors are in::
/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::
View:
The stylesheets have been cleaned up too. You may want to use the newer
versions in::
/roundup/templates//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/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/templates/classic/dbinit.py
If you used the extended schema, the file is in::
/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::
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/templates/classic/dbinit.py
If you used the extended schema, the file is in::
/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/templates//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/templates/classic/interfaces.py
If you used the extended schema, the file is in::
/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/templates/classic/dbinit.py
If you used the extended schema, the file is in::
/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 set user1 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
.. _`administration guide`: admin_guide.html
code-efd2b46ad31c/doc/user_guide.txt 0000644 0000000 0000000 00000063372 10134704304 015534 0 ustar 0000000 0000000 ==========
User Guide
==========
:Version: $Revision: 1.29 $
.. contents::
.. hint::
This document will refer to *issues* as the primary store of
information in the tracker. This is the default of the classic template,
but may vary in any given installation.
Your Tracker in a Nutshell
==========================
Your tracker holds information about issues in bundles we call *items*.
An item may be an *issue* (a bug or feature request) or a *user*. The
issue-ness or user-ness is called the item's *class*. So, for bug
reports and features, the class is "issue", and for users the class is
"user".
Each item in the tracker has an id number that identifies it along with
its item class. To identify a particular issue or user, we combine the
class with the number to create a unique label, so that user 1 (who,
incidentally, is *always* the "admin" user) is referred to as "user1".
Issue number 315 is referred to as "issue315". We call that label the
item's *designator*.
Items in the database are never deleted, they're just "retired". You
can still refer to them by ID - hence removing an item won't break
references to the item. It's just that the item won't appear in any
listings.
Accessing the Tracker
---------------------
You may access your tracker through one of three ways:
1. through the `web interface`_,
2. through the `e-mail gateway`_, or
3. using the `command line tool`_.
The last is usually only used by administrators. Most users will use the
web and email interfaces. All three are explained below.
Issue life cycles in Roundup
----------------------------
New issues may be submitted via the web or email.
By default, the issue will have the status "unread". If another message
is received for the issue, its status will change to "chatting".
The "home" page for a tracker will generally display all issues which
are not "resolved.
If an issue is closed, and a new message is received then it'll be
reopened to the state of "chatting".
Entering values in your Tracker
-------------------------------
All interfaces to your tracker use the same format for entering values.
This means the web interface for entering a new issue, the web interface
for searching issues, the email interface and even the command-line
administration tool.
String and Numeric properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
These fields just take a simple text value, like ``It's broken``.
Boolean properties
~~~~~~~~~~~~~~~~~~
These fields take a value which indicates "yes"/"no", "true"/"false",
"1"/"0" or "on"/"off".
Constrained (link and multilink) properties
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Fields like "Assigned To" and "Topics" hold references to items in other
classes ("user" and "keyword" in those two cases.)
Sometimes, the selection is done through a menu, like in the "Assigned
To" field.
Where the input is not a simple menu selection, we use a comma-separated
list of values to indicated which values of "user" or "keyword" are
interesting. The values may be either numeric ids or the names of items.
The special value "-1" may be used to match items where the property is
not set. For example, the following searches on the issues:
``assignedto=richard,george``
match issues which are assigned to richard or george.
``assignedto=-1``
match issues that are not assigned to a user.
``assignedto=2,3,40``
match issues that are assigned to users 2, 3 or 40.
``topic=user interface``
match issues with the keyword "user interface" in their topic list
``topic=web interface,email interface``
match issues with the keyword "web interface" or "email interface" in
their topic list
``topic=-1``
match issues with no topics set
Date properties
~~~~~~~~~~~~~~~
Date-and-time stamps are specified with the date in
international standard format (``yyyy-mm-dd``) joined to the time
(``hh:mm:ss``) by a period ``.``. Dates in this form can be easily
compared and are fairly readable when printed. An example of a valid
stamp is ``2000-06-24.13:03:59``. We'll call this the "full date
format". When Timestamp objects are printed as strings, they appear in
the full date format.
For user input, some partial forms are also permitted: the whole time or
just the seconds may be omitted; and the whole date may be omitted or
just the year may be omitted. If the time is given, the time is
interpreted in the user's local time zone. The Date constructor takes
care of these conversions. In the following examples, suppose that
``yyyy`` is the current year, ``mm`` is the current month, and ``dd`` is
the current day of the month.
- "2000-04-17" means
- "01-25" means
- "2000-04-17.03:45" means
- "08-13.22:13" means
- "11-07.09:32:43" means
- "14:25" means
-
- "8:47:11" means
-
- the special date "." means "right now"
When searching, a plain date entered as a search field will match that date
exactly in the database. We may also accept ranges of dates. You can
specify range of dates in one of two formats:
1. English syntax::
[From ][To ]
Keywords "From" and "To" are case insensitive. Keyword "From" is
optional.
2. "Geek" syntax::
[];[]
Either first or second ```` can be omitted in both syntaxes.
For example, if you enter string "from 9:00" to "Creation date" field,
roundup will find all issues, that were created today since 9 AM.
The ```` may also be an interval, as described in the next section.
Searching of "-2m; -1m" on activity field gives you issues which were
active between period of time since 2 months up-till month ago.
Other possible examples (consider local time is 2003-03-08.22:07:48)::
- "from 2-12 to 4-2" means
- "FROM 18:00 TO +2m" means
- "12:00;" means
- "tO +3d" means
- "2002-11-10; 2002-12-12" means
- "; 20:00 +1d" means
- "2003" means
- "2003-04" means
Interval properties
~~~~~~~~~~~~~~~~~~~
Date intervals are specified using the suffixes "y", "m", and "d". The
suffix "w" (for "week") means 7 days. Time intervals are specified in
hh:mm:ss format (the seconds may be omitted, but the hours and minutes
may not).
- "3y" means three years
- "2y 1m" means two years and one month
- "1m 25d" means one month and 25 days
- "2w 3d" means two weeks and three days
- "1d 2:50" means one day, two hours, and 50 minutes
- "14:00" means 14 hours
- "0:04:33" means four minutes and 33 seconds
Simple support for collision detection
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Item edit pages remember when the item was last edited. When a form is
submitted, the user will be informed if someone else has edited the item
at the same time they tried to.
Web Interface
=============
.. note::
This document contains screenshots of the default look and feel.
Your site may have a slightly (or very) different look, but the
functionality will be very similar, and the concepts still hold.
The web interface is broken up into the following parts:
1. `lists of items`_,
2. `display, edit or entry of an item`_, and
3. `searching page`_.
Lists of Items
--------------
The first thing you'll see when you log into Roundup will be a list of
open (ie. not resolved) issues. This list has been generated by a bunch
of controls `under the covers`_ but for now, you can see something like:
.. img: images/index_logged_out.png
The screen is divided up into three sections:
.. img: images/page_layout.png
you may either register or log in. Registration takes you to:
.. img: images/registration.png
Once you're logged in, the screen changes slightly to:
.. img: images/index_logged_in.png
Note that the sidebar menu has changed slightly, so you can now get to
your "My Details" page:
.. img: images/my_details.png
Note the new information on this page - the history.
Display, edit or entry of an item
---------------------------------
Create a new issue with "create new" under the issue subheading. This
will take you to:
.. img: images/new_issue.png
The `nosy list`_ is explained below. Enter some information and click
"submit new entry" and you'll be rewarded with:
.. img: images/new_issue_created.png
or, if you don't enter all the required information (or some other error
occurs) you'll get something like:
.. img: images/new_issue_error.png
Searching Page
--------------
See `entering values in your tracker`_ for an explanation of what you
may type into the search form.
Saving queries
~~~~~~~~~~~~~~
You may save queries in the tracker by giving the query a name. Each user
may only have one query with a given name - if a subsequent search is
performed with the same query name supplied, then it will edit the
existing query of the same name.
Queries may be marked as "private". These queries are only visible to the
user that created them. If they're not marked "private" then all other
users may include the query in their list of "Your Queries". Marking it as
private at a later date does not affect users already using the query, nor
does deleting the query.
If a user subsequently creates or edits a public query, a new personal
version of that query is made, with the same editing rules as described
above.
Under the covers
~~~~~~~~~~~~~~~~
The searching page converts your selections into the following
arguments:
========== =============================================================
Argument Description
========== =============================================================
:sort sort by prop name, optionally preceeded with '-' to give
descending or nothing for ascending sorting.
:group group by prop name, optionally preceeded with '-' or to sort
in descending or nothing for ascending order.
:filter selects which props should be displayed in the filter
section. Default is all.
:columns selects the columns that should be displayed. Default is
all.
propname selects the values the item properties given by propname must
have (very basic search/filter).
========== =============================================================
You may manually write URLS that contain these arguments, like so
(whitespace has been added for clarity)::
/issue?status=unread,in-progress,resolved&
topic=security,ui&
:group=priority&
:sort=-activity&
:filters=status,topic&
:columns=title,status,fixer
Access Controls
---------------
User access is controlled through Permissions. These are are grouped
into Roles, and users have a comma-separated list of Roles assigned to
them.
Permissions divide access controls up into answering questions like:
- may the user edit issues ("Edit", "issue")
- is the user allowed to use the web interface ("Web Access")
- may the user edit other user's Roles through the web ("Web Roles")
Any number of new Permissions and Roles may be created as described in
the customisation documentation. Examples of new access controls are:
- only managers may sign off issues as complete
- don't give users who register through email web access
- let some users edit the details of all users
E-Mail Gateway
==============
E-mail sent to Roundup is examined for several pieces of information:
1. `subject-line information`_ identifying the purpose of the e-mail
2. `sender identification`_ using the sender of the message
3. `e-mail message content`_ which is to be extracted
4. e-mail attachments which should be associated with the message
Subject-line information
------------------------
The subject line of the incoming message is examined to find one of:
1. the item that the message is responding to,
2. the type of item the message should create, or
3. we default the item class and try some trickiness
If the subject line contains a prefix in ``[square brackets]`` then
we're looking at case 1 or 2 above. Any "re:" or "fwd:" prefixes are
stripped off the subject line before we start looking for real
information.
If an item designator (class name and id number, for example
``issue123``) is found there, a new "msg" item is added to the
"messages" property for that item, and any new "file" items are added to
the "files" property for the item.
If just an item class name is found there, we attempt to create a new
item of that class with its "messages" property initialized to contain
the new "msg" item and its "files" property initialized to contain any
new "file" items.
The third case above - where no ``[information]`` is provided, the
tracker's ``MAIL_DEFAULT_CLASS`` configuration variable defines what
class of item the message relates to. We try to match the subject line
to an existing item of the default class, and if there's a match, the
message is related to that matched item. If not, then a new item of the
default class is created.
Setting Properties
~~~~~~~~~~~~~~~~~~
The e-mail interface also provides a simple way to set properties on
items. At the end of the subject line, propname=value pairs can be
specified in square brackets, using the same conventions as for the
roundup set shell command.
For example,
- setting the priority of an issue::
Subject: Re: [issue1] the coffee machine is broken! [priority=urgent]
- adding yourself to a nosy list::
Subject: Re: [issue2] we're out of widgets [nosy=+richard]
- setting the nosy list to just you and cliff::
Subject: Re: [issue2] we're out of widgets [nosy=richard,cliff]
- removing yourself from a nosy list and setting the priority::
Subject: Re: [issue2] we're out of widgets [nosy=-richard;priority=bug]
In all cases, the message relates to issue 2. The ``Re:`` prefix is
stripped off.
Automatic Properties
~~~~~~~~~~~~~~~~~~~~
**status of new issues**
When a new message is received that is not identified as being related
to an existing issue, it creates a new issue. The status of the new
issue is defaulted to "unread".
**reopening of resolved issues**
When a message is is received for a resolved issue, the issue status is
automatically reset to "chatting" to indicate new information has been
received.
Sender identification
---------------------
If the sender of an email is unknown to Roundup (looking up both user
primary email addresses and their alternate addresses) then a new user
will be created. The new user will have their username set to the "user"
part of "user@domain" in their email address. Their password will be
completely randomised, and they'll have to visit the web interface to
have it changed. Some sites don't allow web access by users who register
via email like this.
E-Mail Message Content
----------------------
Roundup only associates plain text (MIME type ``text/plain``) as
messages for items. Any other parts of a message are associated as
downloadable files. If no plain text part is found, the message is
rejected.
To do this, incoming messages are examined for multiple parts:
* In a multipart/mixed message or part, each subpart is extracted and
examined. The text/plain subparts are assembled to form the textual
body of the message, to be stored in the file associated with a "msg"
class item. Any parts of other types are each stored in separate files
and given "file" class items that are linked to the "msg" item.
* In a multipart/alternative message or part, we look for a text/plain
subpart and ignore the other parts.
If the message is a response to a previous message, and contains quoted
sections, then these will be stripped out of the message if the
``EMAIL_KEEP_QUOTED_TEXT`` configuration variable is set to ``'no'``.
Message summary
~~~~~~~~~~~~~~~
The "summary" property on message items is taken from the first
non-quoting section in the message body. The message body is divided
into sections by blank lines. Sections where the second and all
subsequent lines begin with a ">" or "|" character are considered
"quoting sections". The first line of the first non-quoting section
becomes the summary of the message.
Address handling
----------------
All of the addresses in the ``To:`` and ``Cc:`` headers of the incoming
message are looked up among the tracker users, and the corresponding
users are placed in the "recipients" property on the new "msg" item. The
address in the ``From:`` header similarly determines the "author"
property of the new "msg" item. The default handling for addresses that
don't have corresponding users is to create new users with no passwords
and a username equal to the address.
The addresses mentioned in the ``To:``, ``From:`` and ``Cc:`` headers of
the message may be added to the `nosy list`_ depending on:
``ADD_AUTHOR_TO_NOSY``
Does the author of a message get placed on the nosy list automatically?
If 'new' is used, then the author will only be added when a message
creates a new issue. If 'yes', then the author will be added on
followups too. If 'no', they're never added to the nosy.
``ADD_RECIPIENTS_TO_NOSY``
Do the recipients (To:, Cc:) of a message get placed on the nosy list?
If 'new' is used, then the recipients will only be added when a message
creates a new issue. If 'yes', then the recipients will be added on
followups too. If 'no', they're never added to the nosy.
Nosy List
~~~~~~~~~
Roundup watches for additions to the "messages" property of items.
When a new message is added, it is sent to all the users on the "nosy"
list for the item that are not already on the "recipients" list of the
message. Those users are then appended to the "recipients" property on
the message, so multiple copies of a message are never sent to the same
user. The journal recorded by the hyperdatabase on the "recipients"
property then provides a log of when the message was sent to whom.
If the author of the message is also in the nosy list for the item that
the message is attached to, then the config var ``MESSAGES_TO_AUTHOR``
is queried to determine if they get a nosy list copy of the message too.
Mail gateway script command line
--------------------------------
Usage::
roundup-mailgw [[-C class] -S field=value]* [method]
The roundup mail gateway may be called in one of three ways:
- with an instance home as the only argument,
- with both an instance home and a mail spool file, or
- with both an instance home and a pop server account.
It also supports optional -C and -S arguments that allows you to set a
fields for a class created by the roundup-mailgw. The default class if
not specified is msg, but the other classes: issue, file, user can also
be used. The -S or --set options uses the same
property=value[;property=value] notation accepted by the command line
roundup command or the commands that can be given on the Subject line of
an email message.
It can let you set the type of the message on a per email address basis.
PIPE:
In the first case, the mail gateway reads a single message from the
standard input and submits the message to the roundup.mailgw module.
UNIX mailbox:
In the second case, the gateway reads all messages from the mail spool
file and submits each in turn to the roundup.mailgw module. The file is
emptied once all messages have been successfully handled. The file is
specified as::
mailbox /path/to/mailbox
POP:
In the third case, the gateway reads all messages from the POP server
specified and submits each in turn to the roundup.mailgw module. The
server is specified as::
pop username:password@server
The username and password may be omitted::
pop username@server
pop server
are both valid. The username and/or password will be prompted for if
not supplied on the command-line.
APOP:
Same as POP, but using Authenticated POP::
apop username:password@server
Command Line Tool
=================
The basic usage is::
Usage: roundup-admin [options] []
Options:
-i instance home -- specify the issue tracker "home directory" to administer
-u -- the user[:password] to use for commands
-d -- print full designators not just class id numbers
-c -- when outputting lists of data, comma-separate them.
Same as '-S ","'.
-S -- when outputting lists of data, string-separate them
-s -- when outputting lists of data, space-separate them.
Same as '-S " "'.
Only one of -s, -c or -S can be specified.
Help:
roundup-admin -h
roundup-admin help -- this help
roundup-admin help -- command-specific help
roundup-admin help all -- all available help
Commands:
commit
create classname property=value ...
display designator[,designator]*
export [class[,class]] export_dir
find classname propname=value ...
get property designator[,designator]*
help topic
history designator
import import_dir
initialise [adminpw]
install [template [backend [admin password]]]
list classname [property]
pack period | date
reindex
retire designator[,designator]*
rollback
security [Role name]
set items property=value property=value ...
specification classname
table classname [property[,property]*]
Commands may be abbreviated as long as the abbreviation matches only one
command, e.g. l == li == lis == list.
All commands (except help) require a tracker specifier. This is just the
path to the roundup tracker you're working with. A roundup tracker is
where roundup keeps the database and configuration file that defines an
issue tracker. It may be thought of as the issue tracker's "home
directory". It may be specified in the environment variable
``TRACKER_HOME`` or on the command line as "``-i tracker``".
A designator is a classname and an itemid concatenated, eg. bug1,
user10, ... Property values are represented as strings in command
arguments and in the printed results:
- Strings are, well, strings.
- Password values will display as their encoded value.
- Date values are printed in the full date format in the local time
zone, and accepted in the full format or any of the partial formats
explained below.::
Input of... Means...
"2000-04-17.03:45" 2000-04-17.03:45:00
"2000-04-17" 2000-04-17.00:00:00
"01-25" yyyy-01-25.00:00:00
"08-13.22:13" yyyy-08-13.22:13:00
"11-07.09:32:43" yyyy-11-07.09:32:43
"14:25" yyyy-mm-dd.14:25:00
"8:47:11" yyyy-mm-dd.08:47:11
"2003" 2003-01-01.00:00:00
"2003-04" 2003-04-01.00:00:00
"." "right now"
- Link values are printed as item designators. When given as an
argument, item designators and key strings are both accepted.
- Multilink values are printed as lists of item designators joined by
commas. When given as an argument, item designators and key strings
are both accepted; an empty string, a single item, or a list of items
joined by commas is accepted.
When multiple items are specified to the roundup get or roundup set
commands, the specified properties are retrieved or set on all the
listed items. When multiple results are returned by the roundup get or
roundup find commands, they are printed one per line (default) or joined
by commas (with the "``-c``" option).
Where the command changes data, a login name/password is required. The
login may be specified as either "``name``" or "``name:password``".
- ``ROUNDUP_LOGIN`` environment variable
- the "``-u``" command-line option
If either the name or password is not supplied, they are obtained from
the command-line.
Using with the shell
--------------------
With version 0.6.0 or newer of roundup which supports: multiple
designators to display and the -d, -S and -s flags.
To find all messages regarding chatting issues that contain the word
"spam", for example, you could execute the following command from the
directory where the database dumps its files::
shell% for issue in `roundup-admin -ds find issue status=chatting`; do
> grep -l spam `roundup-admin -ds ' ' get messages $issue`
> done
msg23
msg49
msg50
msg61
shell%
Or, using the -dc option, this can be written as a single command::
shell% grep -l spam `roundup get messages \
\`roundup -dc find issue status=chatting\``
msg23
msg49
msg50
msg61
shell%
You can also display issue contents::
shell% roundup-admin display `roundup-admin -dc get messages \
issue3,issue1`
files: []
inreplyto: None
recipients: []
author: 1
date: 2003-02-16.21:23:03
messageid: None
summary: jkdskldjf
files: []
inreplyto: None
recipients: []
author: 1
date: 2003-02-15.01:59:11
messageid: None
summary: jlkfjadsf
or status::
shell% roundup-admin get name `/tools/roundup/bin/roundup-admin \
-dc -i /var/roundup/sysadmin get status issue3,issue1`
unread
deferred
or status on a single line::
shell% echo `roundup-admin get name \`/tools/roundup/bin/roundup-admin \
-dc -i /var/roundup/sysadmin get status issue3,issue1\``
unread deferred
which is the same as::
shell% roundup-admin -s get name `/tools/roundup/bin/roundup-admin \
-dc -i /var/roundup/sysadmin get status issue3,issue1`
unread deferred
Also the tautological::
shell% roundup-admin get name \
`roundup-admin -dc get status \`roundup-admin -dc find issue \
status=chatting\``
chatting
chatting
Remember the roundup commands that accept multiple designators accept
them ',' separated so using '-dc' is almost always required.
-----------------
Back to `Table of Contents`_
.. _`Table of Contents`: index.html
.. _`customisation documentation`: customizing.html
code-efd2b46ad31c/doc/whatsnew-0.7.txt 0000644 0000000 0000000 00000037351 10134704304 015541 0 ustar 0000000 0000000 =========================
What's New in Roundup 0.7
=========================
For those completely new to Roundup, you might want to look over the very
terse features__ page.
__ features.html
.. contents::
Instant-Gratification script even more gratifying
=================================================
The immensely popular ``python demo.py`` instant-gratification script has
been extended to allow you to choose the backend to use with the demo. To
select the "sqlite" backend (assuming it is available) you use::
python demo.py sqlite nuke
This will nuke any existing demo and reinitialise it with the sqlite
backend. Remember folks, if you want to restart the demo at a later point,
you just need to type::
python demo.py
without the "sqlite nuke" part, or you'll clear out the demo again. The
backend names are:
anydbm bsddb bsddb3 sqlite metakit mysql postgresql
You will need support modules installed for all except the first two. If
you're not sure whether you have support, run::
python run_tests.py
and if you see a line saying "Including XXXX tests" where XXXX is the
backend you wish to try, then you're on your way. The mysql and postgresql
require their test environments to be set up. Read their respective
documents in the "doc" directory to do that.
Web Interface
=============
Saving and sharing of user queries
----------------------------------
Due to popular demand, the user query saving mechanisms have been
overhauled.
As before, you may save queries in the tracker by giving the query a
name. Each user may only have one query with a given name - if a
subsequent search is performed with the same query name supplied, then
it will edit the existing query of the same name.
Queries may be marked as "private". These queries are only visible to the
user that created them. If they're not marked "private" then all other
users may include the query in their list of "Your Queries". Marking it as
private at a later date does not affect users already using the query, nor
does deleting the query.
If a user subsequently creates or edits a public query, a new personal
version of that query is made, with the same editing rules as described
above.
You *are not required* to make these changes in your tracker. You only
need to make them if you wish to use the new query editing features. It's
highly recommended, as the effort is minimal.
1. You will need to edit your tracker's ``dbinit.py`` to change the way
queries are stored. Change the lines::
query = Class(db, "query",
klass=String(), name=String(),
url=String())
query.setkey("name")
to::
query = Class(db, "query",
klass=String(), name=String(),
url=String(), private_for=Link('user'))
That is, add the "private_for" property, and remove the line that says
``query.setkey("name")``.
2. You will also need to copy the ``query.edit.html`` template page from the
``templates/classic/html/`` directory of the source to your tracker's
``html`` directory.
3. Once you've done that, edit the tracker's ``page.html`` template to
change::
Your Queries
to::
Your Queries (edit)
That is, you're removing the ``tal:condition`` and adding a link to the
new edit page.
4. You might also wish to remove the redundant query editing section from the
``user.item.html`` page.
ZRoundup reinstated
-------------------
The Zope interface, ZRoundup, lives again!
See the `upgrading documentation`__ if you wish to use it.
__ upgrading.html#zroundup-changes
Simple support for collision detection
--------------------------------------
Item edit pages that use the ``context/submit`` function to generate their
submit buttons now automatically include a datestamp in the form. This
datestamp is compared to the "activity" property of the item when the form
is submitted. If the "actvity" property is younger than the datestamp in
the form submission, then someone else has edited the item, and a page
indicating this is displayed to the user.
Extending the cgi interface
---------------------------
Before 0.7.0 adding or extending web actions was done by overriding or adding
methods on the Client class. Though this approach still works to provide
backwards compatibility, it is recommended you upgrade to the new approach, as
described in the `Defining new web actions`__ section of the customization
documentation. You might also want to take a look at the `Using an external
password validation source`__ example.
__ customizing.html#defining-new-web-actions
__ customizing.html#using-an-external-password-validation-source
Actions may also return the content that should return to the user, which
causes the web interface to skip the normal template formatting step.
This could be used to return an image to the user instead of HTML. Be sure
to set the correct content-type header though! The default is still
text/html. This is done with::
self.client.setHeader('Content-Type', 'image/png')
if you were returning a PNG image.
Roundup server
--------------
The roundup-server web interface now supports setgid and running on port
< 1024.
It also forks to handle new connections, which means that trackers using
the postgresql or mysql backends will be able to have multiple users
accessing the tracker simultaneously.
HTML templating made easier
---------------------------
All HTML templating functions perform checks for permissions required to
display or edit the data they are manipulating. The simplest case is
editing an issue title. Including the expression::
context/title/field
will present the user with an edit field if they have Edit Permission. If
not, then they will be presented with a static display if they have View
Permission. If they don't even have View Permission, then an error message
is raised, preventing the display of the page, indicating that they don't
have permission to view the information.
This removes the need for the template to perform those checks, which was
just plain messy.
Some new permissions will need to be created in your trackers to cope with
this change, as outlined in the `upgrading documentation`__.
__ upgrading.html#permission-assignments
Standards changes
-----------------
The HTTP Content-Length header when we serve up files, either
static ones from the "html" folder or file content from the database.
We also handle If-Modified-Since and supply Last-Modified for both types
of file too.
The HTML generated in the classic tracker is now HTML4 (or optionally
XHTML) compliant. The ``config.py`` variable "HTML_VERSION" is used to
control this behaviour.
The stylesheet includes printer settings now too, so printed pages
don't include the sidebar.
Quoting of URLs and HTML
------------------------
Templates that wish to offer file downloads may now use a new
``download_url`` method::
...
The ``download_url`` method looks up the file's "id" and "name" and
generates a correctly-quoted URL.
Additionally, users wishing to URL- or HTML- quote text in their templates
may use the new ``utils.url_quote(url)`` and ``utils.html_quote(html)``
methods.
CSV download of search results
------------------------------
A new CGI action, ``export_csv`` has been added which exports a given
index page query as a comma-separated-value file.
To use this new action, just add a link to your ``issue.index.html``
page::
Download as CSV
You may use this for other classes by adding it to their index page and
changing the ``'issue'`` part of the expression to the new class' name.
Other changes
-------------
- we serve up a favicon now
- the page titles have the tracker name at the end of the text instead
of the start
- added url_quote and html_quote methods to the utils object
- added isset method to HTMLProperty
- added search_checkboxes as an option for the search form
Email Interface
===============
Better handling of some email headers
-------------------------------------
We ignore messages with the header "Precedence: bulk".
If a Resent-From: header is present, it is used in preference to the From:
header when determining the author of the message. Useful for redirecting
error messages from automated systems.
Email character set
-------------------
The default character set for sending email is UTF-8 (ie. Unicode). If you
have users whose email clients can't handle UTF-8 (eg. Eudora) then you
will need to edit the new config.py variable ``EMAIL_CHARSET``.
Dispatcher configuration
------------------------
A new config option has been added that specifies the email address of
a "dispatcher" role. This email address acts as a central sentinel for
issues coming into the system. You can configure it so that all e-mail
error messages get bounced to them, them and the user in question, or
just the user (default).
To toggle these switches, add the "DISPATCHER_EMAIL" and
"ERROR_MESSAGES_TO" configuration values to your tracker's ``config.py``.
See the `customisation documentation`_ for how to use them.
More flexible message generation
--------------------------------
The code for generating email messages in Roundup has been refactored. A
new module, ``roundup.mailer`` contains most of the nuts-n-bolts required
to generate email messages from Roundup.
In addition, the ``IssueClass`` methods ``nosymessage()`` and
``send_message()`` have both been altered so that they don't require the
message id parameter. This means that change notes with no associated
change message may now be generated much more easily.
The roundupdb nosymessage() method also accepts a ``bcc`` argument which
specifies additional userids to send the message to that will not be
included in the To: header of the message.
Registration confirmation by email
----------------------------------
Users may now reply to their registration confirmation email, and the
roundup mail gateway will complete their registration.
``roundup-mailgw`` now supports IMAP
------------------------------------
To retrieve from an IMAP mailbox, use a *cron* entry similar to the
POP one::
0,10,20,30,40,50 * * * * /usr/local/bin/roundup-mailgw /opt/roundup/trackers/support imap
where imap_spec is "``username:password@server``" that specifies the roundup
submission user's IMAP account name, password and server. You may
optionally include a mailbox to use other than the default ``INBOX`` with
"``imap username:password@server mailbox``".
If you have a secure (ie. HTTPS) IMAP server then you may use ``imaps``
in place of ``imap`` in the command to use a secure connection.
Database configuration
======================
Postgresql added as a backend option
------------------------------------
Trackers may now use the postgresql RDBMS as a database store.
Postgresql is a good choice if you expect your tracker to grow very large,
and are expecting many users.
API change
----------
The Database.curuserid attribute was removed. Any code referencing this
attribute should be replaced with a call to Database.getuid().
New configuration options
-------------------------
- Added DEFAULT_TIMEZONE which allows the tracker to have a different
default to UTC when users don't specify their own preference.
- Added EMAIL_CHARSET (in 0.6.6, but worth mentioning here) which hard-codes
the character set to be used when sending email from Roundup. This works
around some email clients' inability to cope well with UTF-8 (the
default).
- ERROR_MESSAGES_TO and DISPATCHER_EMAIL as described above in `Dispatcher
configuration`_.
Typed columns in RDBMS backends
-------------------------------
The SQLite, MySQL and Postgresql backends now create tables with
appropriate column datatypes (not just varchar).
Your database will be automatically migrated to use the new schemas, but
it will take time. It's probably a good idea to make sure you do this as
part of the upgrade when users are not expected to be using the system.
Permission setup
----------------
0.7 automatically sets up the Edit and View Permissions for all classes,
thus you don't need to do so. Feel free to remove the code::
# Add new Permissions for this schema
for cl in 'issue', 'file', 'msg', 'user', 'query', 'keyword':
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)
from your ``dbinit.py``.
New "actor" property
--------------------
Roundup's database has a new per-item property "actor" which reflects the
user performing the last "actvitiy". See the classic template for ways to
integrate this new property into your interface.
The property will be automatically added to your existing database.
New Reject exception for Auditors
---------------------------------
An auditor may raise this exception when the current create or set
operation should be stopped.
It is up to the specific interface invoking the create or set to
handle this exception sanely. For example:
- mailgw will trap and ignore Reject for file attachments and messages
- cgi will trap and present the exception in a nice format
New auditor fixes Outlook bug
-----------------------------
The new optional auditor ``detectors/emailauditor.py`` fires whenever a
new file entity is created.
If the file is of type message/rfc822, we tack on the extension .mht.
The reason for this is that Microsoft Internet Explorer will not open
things with a .eml attachment, as they deem it 'unsafe'. Worse yet,
they'll just give you an incomprehensible error message. For more
information, please see:
http://support.microsoft.com/default.aspx?scid=kb;EN-US;825803
Their suggested work around is (excerpt):
WORKAROUND
To work around this behavior, rename the .EML file that the URL
links to so that it has a .MHT file name extension, and then update
the URL to reflect the change to the file name. To do this:
1. In Windows Explorer, locate and then select the .EML file that
the URL links.
2. Right-click the .EML file, and then click Rename.
3. Change the file name so that the .EML file uses a .MHT file name
extension, and then press ENTER.
4. Updated the URL that links to the file to reflect the new file
name extension.
New script for copying users
----------------------------
A new script, ``scripts/copy-user.py``, will copy users from one tracker
to another. Example usage::
copy-user.py /roundup/tracker1 /roundup/tracker2 `seq 3 10` 14 16
which copies users 3, 4, 5, 6, 7, 8, 9, 10, 14 and 16.
Other improvements
------------------
- All RDBMS backends now have indexes automatically created on critical
table columns.
- Additionally, the RDBMS backends also implement their own session,
one-time-key and full-text indexing stores. These were previously external
dbm stores. This change allows control of locking the database to be
completely handed over to the RDBMS.
- Date values capture fractions of seconds now. Note that the MySQL backend
is not capable of storing this precision though, so it will be lost for
users of that backend.
- The roundup-admin "export" and "import" commands now handle the database
journals too. This means that exports from previous versions of Roundup
will not work under 0.7!
.. _`customisation documentation`: customizing.html
code-efd2b46ad31c/doc/whatsnew-0.8.txt 0000644 0000000 0000000 00000000510 10134704304 015525 0 ustar 0000000 0000000 =========================
What's New in Roundup 0.8
=========================
For those completely new to Roundup, you might want to look over the very
terse features__ page.
__ features.html
.. contents::
Logging of internal messages
============================
TODO
.. _`customisation documentation`: customizing.html