code-001c16ac87ec/doc/CVE.txt0000644000000000000000000000705515046233326013657 0ustar 00000000000000.. comments: This file is a temporary way to post CVE notifications before a release. Document the CVE fix info in upgrading.txt. We extract the sections from upgrading.txt that deal with the CVE into a separate CVE.html. An updated docs/security.html and docs/CVE.html provide the details on a between release CVE announcment. Publishing upgrading.txt would include info on the to be released roundup software and wouldn't match the rest of the release docs. To extract the info from upgrading.txt to use in CVE.html, add a commented out a reference anchor in upgrading.txt. Then in CVE.txt we use an include directive with start-after and end-before options to exract the sections from upgrading.txt into CVE.html. The extracted section in CVE.txt gets the same anchor that is in upgrading.txt, but is is not commented out. This allows us to swap out CVE.txt and uncomment the reference in upgrading.txt. Then rerunning sphinx-build will make security.html point to the sections in upgrading.html. For example, in upgrading.txt add a .. comment: _CVE-2024-39124: before the section for the CVE (use the real CVE number). At the end of the CVE section add an end comment: .. comment: end of CVE include marker Update security.txt with a :ref: to the CVE section. E.G. a security.txt references look like: * `CVE-2024-39124`_ - :ref:`classhelpers (_generic.help.html) are vulnerable to an XSS attack. ` Requires fixing tracker homes. where is the reference. The same reference anchor is present (commented out) in upgrading.txt. In CVE.txt you replicate the existing anchor and include to extract the content section from upgrading.txt. E.G. .. _CVE-2024-39124: .. include:: upgrading.txt :start-after: .. comment: _CVE-2024-39124: :end-before: .. comment: end of CVE After building the docs, install docs/security.html and docs/CVE.html on the web site. Reference: https://www.roundup-tracker.org/docs/security.html in the CVE announcement from Mitre. When the release is ready, replace 'comment: _CVE' with '_CVE' in upgrading.txt. This makes the anchors in upgrading.txt live. Then disable CVE.txt by removing CVE.txt from contents.txt in the toctree hidden section. Also add docs/CVE.txt to exclude_patterns in conf.py. No change needs to happen to security.txt as it's using a :ref: and we just changed the location for the ref so sphinx will get the links correct. Now build the docs and publish to the web site. =========== Roundup CVE =========== This is a list of remediation for CVE's that are not fixed in the latest release. When the latest release fixes the CVE, see `the upgrading doc `_ for these details. .. contents:: :local: :depth: 2 .. _CVE-2024-39124: .. note:: Prior to the release of Roundup 2.4.0, you can access updated tracker templates that address CVE-2024-39124 from `CVE-2024-39124-templates.zip <../CVE-2024-39124-templates.zip>`_. Download and extract the zip file to generate a templates subdirectory containing the classic, minimal and other tracker templates. .. include:: upgrading.txt :start-after: .. comment: _CVE-2024-39124: :end-before: .. comment: .. _CVE-2024-39125: .. include:: upgrading.txt :start-after: .. comment: _CVE-2024-39125: :end-before: .. comment: .. _CVE-2024-39126: .. include:: upgrading.txt :start-after: .. comment: _CVE-2024-39126: :end-before: .. comment: end of CVE include marker code-001c16ac87ec/doc/FAQ.txt0000644000000000000000000002014015046233326013637 0ustar 00000000000000=========== Roundup FAQ =========== .. contents:: :local: Installation ------------ Living without a mailserver ~~~~~~~~~~~~~~~~~~~~~~~~~~~ Remove the nosy reactor - delete the tracker file ``detectors/nosyreactor.py`` from your tracker home. You do need to configure the ``[mail]`` section of config.ini. Specifically the ``domain`` and ``host`` settings have to have a value. The values don't matter, but the config parser will complain if they are not set. 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 (or possibly mod_wsgi or other WSGI support). To make Roundup more seamless with your website, you may place the built in server behind apache and link it into your web tree (see below). 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.ini`` 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] How do I run Roundup through SSL (HTTPS)? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The preferred way of using SSL is to proxy through apache and use its SSL service. See the previous question on how to proxy through apache. The standalone roundup-server now also has SSL support which is still considered experimental. For details refer to the documentation of roundup server, in particular to the generated configuration file generated with :: roundup-server --save-config that describes the needed option in detail. With the standalone server now XMLRPC over SSL works, too. 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 reference_ documentation. For more information have a look at: https://zope.readthedocs.io/en/latest/zopebook/ZPT.html specifically the chapter (10) on "Using Zope Page Templates" and the chapter (13) on "Advanced Page Templates". (Note the link above is for a newer version of Zope, so some of the info may not apply to version 2 of Zope which is used in roundup. The version 2 docs appear to not be available anymore.) But I just want a select/option list for .... ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Really easy... edit ``html/issue.item.html``. For ``nosy``, change the line (around line 69) from:: to:: For ``assigned to``, this is already done around line 77:: assignedto menu Great! But now the select/option list is too big ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ That is a little harder (but only a little ;^) Again, edit ``html/issue.item``. For nosy, change line (around line 69) from:: to:: for more information, go and read about Zope Page Templates. I want to link version identifiers from my messages to svn/mercurial/git ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ See: the LinkFormatingExample at: https://wiki.roundup-tracker.org/LinkFormattingExample?highlight=%28local%5C_replace%29 There are examples in the devel and responsive templates. Search for LocalReplace to find the extension file and the change that has to be made to the item template. I can see values in a multilink but not display the items ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Make sure that you have allowed the user to view the labelprop for the multilink class. Look for the setlabelprop explanation in the Roundup reference_ documentation. Using Roundup ------------- I got an error and I cannot 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.ini is set to the URL of the tracker. I'm getting infinite redirects in the browser ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A wrong value for the ``tracker`` -> ``web`` setting may also result in infinite redirects, see https://issues.roundup-tracker.org/issue2537286 How is sorting performed, and why does it seem to fail sometimes? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When we sort items in the hyperdb, we use one of a number of methods, depending on the properties being sorted on: 1. If it's a String, Integer, Number, Date or Interval property, we just sort the scalar value of the property. Strings are sorted case-sensitively. 2. If it's a Link property, we sort by either the linked item's "order" property (if it has one) or the linked item's "id". 3. Mulitlinks sort similar to #2, but we start with the first Multilink list item, and if they're the same, we sort by the second item, and so on. Note that if an "order" property is defined on a Class that is used for sorting, all items of that Class *must* have a value against the "order" property, or sorting will result in random ordering. How do I filter roundup emails? ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ When roundup emails users, it provides an email header:: X-Roundup-(class)-(property): values for every property that is a link or multilink (usually things set by a dropdown or selection in the web interface). For example, assume you have a category field for issues in your tracker. You respond to issues that fall into the catagories: Network and Security. You will see headers like: X-Roundup-issue-category: Network or X-Roundup-issue-category: Network, Security, Linux Then you can set up a filter looking for X-Roundup-issue-category followed by Network or Security in your mail program. Also for newer (post version 1.6.X) releases there is also a header: X-Roundup-issue-Id: 22 for messages from issue22. Directions on using your mail program are beyond the scope of this FAQ entry. (If you don't see a header for a multilink or link property, look for msg_header_property in the roundup docs. In some cases you have to explicitly enable the header.) .. _`reference`: reference.html code-001c16ac87ec/doc/Makefile0000644000000000000000000000363015046233326014134 0ustar 00000000000000##@ Default target all: man_html tracker_config.txt admin_help.html ## make all docs under share cd ..; ./setup.py build_doc ##@ build doc parts tracker_config.txt: ../roundup/configuration.py format_config.awk ## generate a current config file python3 ../roundup/scripts/roundup_admin.py \ genconfig _temp_config.txt awk -f format_config.awk _temp_config.txt | \ cat -s > tracker_config.txt rm -f _temp_config.txt ## generate html versions of man pages for inclusion in documentation # find all man pages and generate output file paths. MAN_ROFF=$(wildcard ../share/man/man1/*.1) MAN_HTML=$(patsubst ../share/man/man1/%.1,html_extra/man_pages/%.1.html,$(MAN_ROFF)) man_html: $(MAN_HTML) ## generate html versions of man pages for docs html_extra/man_pages/%.1.html: ../share/man/man1/%.1 man --html=cat $< > $@ # set max width for paragraphs sed -i '/ ROUNDUP-ADMIN

ROUNDUP-ADMIN

NAME
SYNOPSIS
OPTIONS
COMMANDS
READLINE SUPPORT
SECURITY NOTES
ENVIRONMENT VARIABLES
FURTHER HELP
SEE ALSO
AUTHOR

NAME

roundup-admin - administrate roundup trackers

SYNOPSIS

roundup-admin [options] <command> <arguments>

OPTIONS

-i instance home

Specify the issue tracker "home directory" to administer

-u user[:password]

The user and password to use for commands (partial implemention, see Security Notes below).

-h

Print help text.

-d

Print full designators (e.g. issue1) not just id numbers (1).

-c

When outputting lists of data, comma-separate them. Same as -S ",".

-S string

When outputting lists of data, separate items with given string.

-s

When outputting lists of data, space-separate them. Same as -S " ".

-P pragma=value

Set a pragma on the command line. Multiple -P options can be specified to set multiple pragmas.

-V

Be verbose when importing data.

-v

Report Roundup and Python versions and quit.

Only one of -s, -c or -S can be specified.

COMMANDS

If no command is provided on the command line, roundup-admin will enter an interactive mode. More details about these commands are available using the help command.

A designator is a classname and a nodeid concatenated, eg. bug1, user10, ....

Roundup-admin takes a number of commands:

help

prints help (same as -h)

help <subcommand>

Print command-specific help

help all

Print available help for all commands.

commit

Commit changes made to the database during an interactive session.

The changes made during an interactive session are not automatically written to the database - they must be committed using this command.

One-off commands on the command-line are automatically committed if they are successful. See also rollback.

create classname property=value ...

This creates a new entry of the given class using the property name=value arguments provided on the command line after the "create" command.

display designator[,designator]*

This lists the properties and their associated values for the given node. The pragma display_header can be used to add a header between designators that includes the active/retired status of the item.

export [[-]class[,class]] export_dir

Export the database to colon-separated-value files. To exclude the files (e.g. for the msg or file class), use the exporttables command.

Optionally limit the export to just the named classes or exclude the named classes, if the 1st argument starts with ’-’.

This action exports the current data from the database into colon-separated-value files that are placed in the nominated destination directory.

exporttables [[-]class[,class]] export_dir

Export the database to colon-separated-value files, excluding the files below $TRACKER_HOME/db/files/ (which can be archived separately). To include the files, use the export command.

filter classname propname=value ...

Find the nodes of the given class with a given property value. Multiple values can be specified by separating them with commas. If property is a string, all values must match. I.E. it’s an matches. I.E. an ’or’ operation.

find classname propname=value ...

Find the nodes of the given class with a given link property value.

genconfig <filename>

Generate a new tracker config file (ini style) with default values in <filename>. Note that this does not preserve any settings from the current tracker. Use updateconfig for that.

get property designator[,designator]*

Get the given property of one or more designator(s).

Retrieves the property value of the nodes specified by the designators.

history designator [skipquiet] [raw]

Lists the journal entries viewable by the user for the node identified by the designator. If skipquiet is added, journal entries for quiet properties are not shown. Without the raw option a more human readable output format is used.

import import_dir

Import a database from the directory containing CSV files, two per class to import.

The imported nodes will have the same nodeid as defined in the import file, thus replacing any existing content.

The new nodes are added to the existing database - if you want to create a new database using the imported data, then create a new database (or, tediously, retire all the old data). See also export.

importtables import_dir

Import a database from the directory containing CSV files, two per class to import.

The imported nodes will have the same nodeid as defined in the import file, thus replacing any existing content.

This only imports database tables. It does not import files/message content. It is used to import data exported by exporttables. See also exporttables.

initialise [adminpw]

Initialise a new Roundup tracker.

The administrator details will be set at this step.

install [template [backend [key=val[,key=val]]]]

Install a new roundup tracker.

The command will prompt for the tracker home directory (if not supplied through TRACKER_HOME or the -i option). The template and backend may be specified on the command-line as arguments, in that order.

Command line arguments following the backend allows you to pass initial values for config options. For example, passing "web_http_auth=no,rdbms_user=dinsdale" will override defaults for options http_auth in section [web] and user in section [rdbms]. Please be careful to not use spaces in this argument! (Enclose whole argument in quotes if you need spaces in option value).

The initialise command must be called after this command in order to initialise the tracker’s database. You may edit the tracker’s initial database contents before running that command by editing the tracker’s dbinit.py module init() function.

See also initopts help.

list classname [property]

Lists all instances of the given class. If the property is not specified, the "label" property is used. The label property is tried in order: the key, "name", "title" and then the first property, alphabetically.

With -c, -S or -s print a list of item id’s if no property specified. If property specified, print list of that property for every class instance.

The pragma show_retired can be used to print only retired items or to print retired and active items. The default is to print only active items.

migrate

Update a tracker’s database to be compatible with the Roundup codebase.

You should run the "migrate" command for your tracker once you’ve installed the latest codebase.

Do this before you use the web, command-line or mail interface and before any users access the tracker.

This command will respond with either "Tracker updated" (if you’ve not previously run it on an RDBMS backend) or "No migration action required" (if you have run it, or have used another interface to the tracker, or possibly because you are using anydbm).

It’s safe to run this even if it’s not required, so just get into the habit.

pack period | date

Remove journal entries older than a period of time specified or before a certain date.

perftest [mode] [arguments]*

Run performance test. For example test the effect of changing password hashing parameters.

pragma setting=value|list

Set internal settings to a value. E.G.

pragma verbose=True
pragma verbose=yes
pragma verbose=on
pragma verbose=1

will turn on verbose mode for roundup-admin.

pragma list

will show all settings and their current values. If verbose is enabled hidden settings and descriptions will be shown.

reindex [classname|classname:#-#|designator]* This will

re-generate the search indexes for a tracker. You can specify a specific item (or items) (e.g. issue23), range(s) of items (e.g. issue:1-1000), class(es) (e.g. issue) or reindex all items in the database if no arguments are supplied.

restore designator[,designator]*

Restore the retired node specified by designator.

The given nodes will become available for users again.

retire designator[,designator]*

This action indicates that a particular node is not to be retrieved by the list or find commands, and its key value may be re-used. See also restore.

rollback

Undo all changes that are pending commit to the database.

The changes made during an interactive session are not automatically written to the database - they must be committed manually. This command undoes all those changes, so a commit immediately after would make no changes to the database.

security [Role name]

Display the Permissions available to one or all Roles.

set items property=value property=value ...

Set the given properties of one or more items(s).

The items are specified as a class or as a comma-separated list of item designators (ie "designator[,designator,...]").

This command sets the properties to the values for all designators given. If the value is missing (ie. "property=") then the property is un-set. If the property is a multilink, you specify the linked ids for the multilink as comma-separated numbers (ie "1,2,3").

specification classname

Show the properties for a classname.

templates [trace_search]]

Lists the names, location and description of all known templates.

table classname [property[,property]*]

Lists all instances of the given class. If the properties are not specified, all properties are displayed. By default, the column widths are the width of the largest value.

The pragma show_retired can be used to print only retired items or to print retired and active items. The default is to print only active items.

updateconfig <filename>

This is used when updating software. It merges the config.ini from the tracker with new settings from the new software. The merged/updated config file is written to <filename>.

Commands may be abbreviated as long as the abbreviation matches only one command, e.g. l == li == lis == list.

READLINE SUPPORT

You can edit the command line and interact with history in roundup-admin’s interactive mode. On Linux like systems, GNU Readline is required. On Mac’s libedit can be used as well. On Windows pyreadline3 is required. See: https://docs.python.org/3/library/readline.html for details on readline.

Roundup-admin will save the history between roundup-admin sessions. The commands are saved to the .roundup_admin_history file in the user’s home directory. You can set the pragma history_length on the roundup-admin command line to change the amount of available and stored history for the session.

If you are using GNU readline, you can persistently change the history size by adding: set history-size 100 to the init file .roundup_admin_rlrc located in the user’s home directory.

Mac users using libedit should be able to persistently save history and set the history size by adding history size 100.

Users of pyreadline3 can use: history_length(100).

SECURITY NOTES

The -u user setting does not currently operate like a user logging in via the web. The user running roundup-admin must have read access to the tracker home directory. As a result the user has access to the files and the database info contained in config.ini.

Using -u user sets the actor/user parameter in the journal. Changes that are made are attributed to that user. The password is ignored if provided. Any existing username has full access to the data just like the admin user. This is an area for further development so that roundup-admin could be used with sudo to provide secure command line access to a tracker.

ENVIRONMENT VARIABLES

ROUNDUP_LOGIN

Provides an alternate way to set the user.

FURTHER HELP

roundup-admin -h
roundup-admin help -- this help
roundup-admin help <command> -- command-specific help
roundup-admin help all -- all available help

SEE ALSO

roundup-demo(1), roundup-mailgw(1), roundup-server(1)

AUTHOR

This manpage was written by Bastian Kleineidam <calvin@debian.org> for the Debian distribution of roundup.

The main author of roundup is Richard Jones <richard@users.sourceforge.net>.

code-001c16ac87ec/doc/html_extra/man_pages/roundup-demo.1.html0000644000000000000000000001436015046233326022242 0ustar 00000000000000 ROUNDUP-DEMO

ROUNDUP-DEMO

NAME
SYNOPSIS
OPTIONS
DESCRIPTION
SEE ALSO
AUTHOR

NAME

roundup-demo - create a roundup "demo" tracker and launch its web interface

SYNOPSIS

roundup_demo [-h] [-b BIND_ADDRESS] [-b {anydbm,mysql,sqlite,postgresql}] [-t {minimal,jinja2,classic,responsive,devel}] [-p PORT] [-P URLPORT] [-V] [directory] [backend] [nuke]

OPTIONS

directory

The home directory for the new demo tracker. (*)

backend

Choose backend database. Depricated, use -b.

nuke

Create a fresh demo tracker (deleting the existing one if any). E.G.

roundup-demo -b sqlite -t classic ./mytracker nuke
will remove an existing tracker (if present) from the directory ./mytracker. Then it will create and serve a new empty classic tracker using the sqlite backend.

-h, --help

Show the help message and exit

-B BIND_ADDRESS, --bind_address BIND_ADDRESS

Choose address for server to listen at. Use 0.0.0.0 to bind to all addreses. Default: 127.0.0.1.

-b {anydbm,mysql,sqlite,postgresql}, --backend_db
{anydbm,mysql,sqlite,postgresql}

Choose backend database. Default: sqlite. Available backends are subject to availability on your system.

-t {minimal,jinja2,classic,responsive,devel}, --template
{minimal,jinja2,classic,responsive,devel}

Use specified template when building tracker. (*)

-h HOSTNAME, --hostname HOSTNAME

Set the hostname used in the URL. This does not make the server listen at the hostname. Use the hostname with -B to listen on that IP address.

-p PORT, --port PORT

Listen at this port. Default: search for open port starting at 8917.

-P URLPORT, --urlport URLPORT

When using docker this option passes the docker external port to the demo instance. If using docker ... -p 9090:8917 ... this should be set to -P 9090. Default: as selected by --port.

-V, --version

Show program’s version number and exit

If items marked with (*) are missing, they will be asked for interactively when setting up the tracker.

DESCRIPTION

This command creates a fresh demo tracker for you to experiment with. The email features of Roundup will be turned off (so the nosy feature won’t send email). It does this by removing the nosyreaction.py module from the demo tracker’s detectors directory. If you wish to send email to promote the tracker to production, you will need to copy nosyreaction.py from the default tracker templates directory. The templates command from roundup-admin(1) can help you locate a replacement.

If you wish, you may modify the demo tracker by editing its configuration files and HTML templates. See the customisation manual for information about how to do that.

Once you’ve fiddled with the demo tracker, you may use it as a template for creating your real, live tracker. Simply run the roundup-admin command to install the tracker from inside the demo tracker home directory, and it will be listed as an available template for installation. No data will be copied over.

SEE ALSO

roundup-admin(1), roundup-mailgw(1), roundup-server(1)

AUTHOR

This manpage was written by Richard Jones and extensively modified by John Rouillard <rouilj@users.sourceforge.net>.

code-001c16ac87ec/doc/html_extra/man_pages/roundup-mailgw.1.html0000644000000000000000000002512715046233326022601 0ustar 00000000000000 ROUNDUP-MAILGW

ROUNDUP-MAILGW

NAME
SYNOPSIS
OPTIONS
DESCRIPTION
ENVIRONMENT VARIABLES
EXAMPLE
SEE ALSO
AUTHOR

NAME

roundup-mailgw - mail gateway for roundup

SYNOPSIS

roundup-mailgw [-h|--help] [-v] [--version] [-c|--default-class default_class] [-S|--set-value [class.]field=value] [-O|--oauth-directory directory] [-T|--oauth-token-endpoint endpoint-url] [instance_home] [mail source [specification]]

OPTIONS

-v --version

Print version and exit.

-c --default-class hyperdb class

specify the default tracker class - one of issue (the default), msg, file, user etc. Overrides the tracker’s mailgw default_class setting.

-S --set-value [class.]property=value[;property=value]

specify the values to set on the class specified as prefix using the same format as the Subject line property manipulations. If the class prefix is left out it defaults to msg. Can also be specified with --set-value (and abbreviated to --set).

-O --oauth-directory directory

Only with OAuth authentication specify the directory containing additional OAuth credentials.

-T --oauth-token-endpoint url

Token endpoint URL of your cloud provider, only used with OAuth.

DESCRIPTION

The roundup mail gateway may be called in one of four ways:

•

without arguments which will use the env var ROUNDUP_INSTANCE,

•

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 mail source type and its specification.

PIPE
If there is no mail source specified, the mail gateway reads a single message from the standard input and submits the message to the roundup.mailgw module.

UNIX mailbox
In this case, the gateway reads all messages from the UNIX 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

In all of the following mail source types, the username and password can be stored in a ~/.netrc file. If done so, only the server name needs to be specified on the command-line.

The username and/or password will be prompted for if not supplied on the command-line or in ~/.netrc.

POP
For the mail source "pop", 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.

POPS
Connect to the POP server over ssl/tls. This supports the same notation as POP.

APOP
Same as POP, but using Authenticated POP:
apop username:password@server

IMAP
Connect to an IMAP server. This supports the same notation as that of POP mail.
imap username:password@server
It also allows you to specify a specific mailbox other than INBOX using this format:
imap username:password@server mailbox

IMAPS
Connect to an IMAP server over ssl/tls. This supports the same notation as IMAP.
imaps username:password@server [mailbox]

IMAPS_CRAM
Connect to an IMAP server over ssl/tls using CRAM-MD5 authentication. This supports the same notation as IMAP.
imaps_cram username:password@server [mailbox]

IMAPS_OAUTH
Connect to an IMAP server over ssl/tls using OAUTH authentication. Note that this does not support a password in imaps URLs. Instead it uses only the user and server and a command-line option for the directory with the files access_token, refresh_token, client_secret, and client_id. By default this directory is oauth in your tracker home directory. The access token is tried first and, if expired, the refresh token together with the client secret is used to retrieve a new access token. Note that both token files need to be writeable, the access token is continuously replaced and some cloud providers may also renew the refresh token from time to time:
imaps_oauth username@server [mailbox]
The refresh and access tokens (the latter can be left empty), the client id and the client secret need to be retrieved via cloud provider specific protocols or websites.

ENVIRONMENT VARIABLES

ROUNDUP_INSTANCE
This can be used to set the instance directory. If it is set, the instance_home argument is optional.

EXAMPLE

If your msg class has a messsagetype property you can set up aliases to receive the different types of messages. Setting up an alias in your MTA Using:

tracker: |/tools/roundup/bin/roundup-mailgw
-S "msg.messagetype=reply - to all" /var/roundup/sysadmin

(the lines are split for readability. In the alias file they will be on the same line). Replace /tools/roundup/bin/roundup-mailgw by your path to the roundup-mailgw. This creates the email alias "tracker". All messages sent to it have their messagetype property set to "reply - to all". The roundup tracker instance is located at /var/roundup/sysadmin.

A comment alias would receive emails at tracker_comment with:

tracker_comment: |/tools/roundup/bin/roundup-mailgw
-S "msg.messagetype=to tech" /var/roundup/sysadmin

which would be a technical message. These messages can trigger different workflows based on the messagetype.

Both examples use the default class specified in the tracker’s config.ini (usually the issue class).

You can also set properties directly on the issue class. If your tracker’s issue has a "private" property that limits who can view an issue and its messages:

security: |/tools/roundup/bin/roundup-mailgw
-S "issue.private=true" -S "issue.keyword+=security"
/var/roundup/sysadmin

would set the private property on a issue to restrict visiblity and mark the issue as a security topic using a keyword.

Both examples use the default class specified in the tracker’s config.ini (usually the issue class).

SEE ALSO

roundup-admin(1), roundup-demo(1), roundup-server(1)

AUTHOR

This manpage was written by Bastian Kleineidam <calvin@debian.org> for the Debian distribution of roundup.

The main author of roundup is Richard Jones <richard@users.sourceforge.net>.

Updates by John Rouillard <rouilj@users.sourceforge.net> and Ralf Schlatterbeck <rsc@runtux.com>.

code-001c16ac87ec/doc/html_extra/man_pages/roundup-server.1.html0000644000000000000000000002412515046233326022624 0ustar 00000000000000 ROUNDUP-SERVER

ROUNDUP-SERVER

NAME
SYNOPSIS
OPTIONS
EXAMPLES
CONFIGURATION FILE
SEE ALSO
AUTHOR

NAME

roundup-server - start roundup web server

SYNOPSIS

roundup-server [options] [name=tracker home]*

OPTIONS

-C file or --config file

Use options read from the configuration file (see below).

-n hostname

Sets the host name or IP address to listen on. Default is localhost (127.0.0.1). Use 0.0.0.0 to listen on all interfaces on the system.

-p port

Sets the port to listen on (default: 8080).

-d PIDfile

Run the server in the background and write the server’s PID to the file indicated by PIDfile. The -l (or -L) option must be specified if -d is used.

-D

Run the server in the foreground even if -d is used.

-t fork|thread|debug|none

Control multi-process mode. debug and none are always available. If an invalid mode is specified the server starts in none (also called single) mode. Default fork.

-m max_children

Set the maximum number of child processes (servers). This value may need to be increased on a heavily loaded site. Default 40.

-l file

Sets a filename to log to (instead of stdout). This is required if the -d option is used.

-P

If a reverse proxy is used in front of the roundup-server, the server will log the ip address of the proxy, not the client browser. Using -P logs the left most entry in the X-Forwarded-For http header as the IP address of the client. This address will be logged or resolved to a hostname (with -N) and a ’+’ character will be appended. -P should only be used when the roundup server is accessible only from trusted proxy hosts. See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For for details and warnings about using the X-Forwarded-For header.

-L

Have the server log using the Python logger with key roundup.http.

-i file

Sets a filename to use as a template for generating the tracker index page. The variable "trackers" is available to the template and is a dict of all configured trackers. If you connect to the root of the server (without a tracker name), the default index page is shown. Using -i allows you to customize the index page.

-I header1[,header2,...]

Pass the header(s) and their values to the backend. This allow-list of header variables can be used by custom code in the tracker or with a tracker’s http_auth_header configuration option to allows a front end server to authenticate a user and pass the user identity to roundup.

-s

Enables use of SSL. In most cases, you will want to run a real web server (Apache, Nginx) as a proxy to roundup-server running without SSL. The real web server can filter/rate limit/firewall requests to roundup-server.

-e file

Sets a filename containing the PEM file to use for SSL. The PEM file must include both the private key and certificate with appropriate header/trailer markers:

-----BEGIN PRIVATE KEY-----
-----END PRIVATE KEY-----

and

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

If no file is specified, a temporary self-signed certificate will be used.

-N

Log client machine names instead of IP addresses (much slower).

-V HTTPVER

By default roundup-server uses HTTP/1.1 to enable keepalives for faster response. HTTPVER can be set to HTTP/1.0 to disable keepalives.

-u UID

Runs the Roundup web server as this UID.

-g GID

Runs the Roundup web server as this GID.

-v or --version

Print version and exit.

-h or --help

Print help and exit.

--save-config

Create configuration file and exit. The old config.ini will be saved to config.bak. Note that this command doesn’t attempt to load or verify an existing config.ini. Running this in a tracker home directory will move the existing config.ini to config.bak and replace it with the roundup-server’s config.ini. This will make the tracker in the directory fail to start until the original config.ini is restored.

name=tracker home

Sets the tracker home(s) to use. The name variable is how the tracker is identified in the URL (it’s the first part of the URL path). The tracker home variable is the directory that was identified when you did "roundup-admin init". You may specify any number of these name=home pairs on the command-line. For convenience, you may edit the TRACKER_HOMES variable in the roundup-server file instead. Make sure the name part doesn’t include any url-unsafe characters like spaces, as these confuse the cookie handling in browsers like IE.

If you connect to the root directory (I.E. you do not include the name component in the URL, the server will display an index page of trackers served by roundup-server if more than one tracker is defined. If only one tracker is defined it will redirect to the tracker.

EXAMPLES

roundup-server -p 9000 bugs=/var/tracker reqs=/home/roundup/group1

Start the server on port 9000 serving two trackers; one under /bugs and one under /reqs.

If you connect to the server at the root level (http://host:9000/) it will display a list of the available trackers.

CONFIGURATION FILE

See the "admin_guide" in the Roundup "doc" directory.

SEE ALSO

roundup-admin(1), roundup-demo(1), roundup-mailgw(1)

AUTHOR

This manpage was written by Bastian Kleineidam <calvin@debian.org> for the Debian distribution of roundup.

The main author of roundup is Richard Jones <richard@users.sourceforge.net>.

code-001c16ac87ec/doc/html_extra/original_overview.html0000644000000000000000000011540215046233326021264 0ustar 00000000000000 Roundup: an Issue-Tracking System for Knowledge Workers
[Software Carpentry logo]
[ACL Logo]
[CodeSourcery Logo]
Copyright (c) 2000 Ka-Ping Yee. This material may be distributed only subject to the terms and conditions set forth in the Software Carpentry Open Publication License, which is available at:
http://www.software-carpentry.com/openpub-license.html

Roundup

An Issue-Tracking System for Knowledge Workers

Ka-Ping Yee

lfw discorporated
ping@lfw.org

Contents

Overview

We propose an issue-tracking system called Roundup, which will manage a number of issues (with properties such as "description", "priority", and so on) and provide 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.

This design draws on experience from an existing implementation which we will refer to as "the Roundup prototype". The graphical interface we have in mind will resemble the main display of the prototype.

Web page with a green banner at the top titled Index of Bugs. Checkboxes to filter issue selection and a table of displayed issues, grouped by severity.

Background

A typical software project requires the management of many tasks, usually distributed among several collaborators. In fact, any project team could use a tool for sorting out and discussing all the relevant issues. A common approach is to set up some kind of "to-do" list that people can share.

However, to address the overall problem we need much more than just a shared to-do list; we need to manage a growing body of knowledge and experience to help a team collaborate effectively on a project. The issue-tracking tool becomes a nexus for communication: the Grand Central Station of the group intelligence.

The primary focus of this design is to help developers work together well, not to provide a customer service interface to the developers. This is not to say that the design is to be made unsuitable for customers to use. Rather, it is assumed that many of the same qualities that are good for supporting development (see below) are also good for non-developers using the system. Additional niceties for providing a safe or simplified interface to clients are intentionally deferred for later consideration.

A good issue-tracking system should have at least the following properties:

With a nod to the time-honoured computer science tradition of "filling in the fourth quadrant", we note that there are really four kinds of information flow going on here. The three mentioned qualities really address the first three quadrants of this 2-by-2 matrix, respectively:

  1. User push: a user submits information to the system.
  2. User pull: a user queries for information from the system.
  3. System push: the system sends information out to users.
  4. System pull: the system solicits information from users.
An example of the fourth kind of flow is voting. Voting isn't described in this design, but it should be noted as a potential enhancement.

  1. Low barrier to participation. The usefulness of the tool depends entirely on the information people contribute to it. It must be made as easy as possible to submit new issues and contribute information about existing issues.

  2. Straightforward navigation. It should be easy for users to extract information they need from the system to direct their decisions and tasks. They should be able to get a decent overview of things as well as finding specific information when they know what they're after.

  3. Controlled information flow. The users must have control over how much information and what information they get. A common flaw of some issue-tracking systems is that they inundate users with so much useless e-mail that people avoid the system altogether.


Guiding Principles

Simplicity. It is a strong requirement that the tool be accessible and understandable. It should be fairly obvious what different parts of the interface do, and the inner mechanisms should operate in ways that most users can easily predict.

Efficiency. We aim to optimize for minimum effort to do the most common operations, and best use of resources like screen real estate to maximize the amount of information that we summarize and present.

Generality. We try to avoid making unnecessary assumptions that would restrict the applicability of the tool. For example, there is no reason why one might not also want to use this tool to manage a design process, non-software projects, or organizational decisions.

Persistence. We prefer hiding or reclassifying information to deleting it. This helps support the collection of statistics later. If records are never destroyed, there is little danger in providing access to a larger community, and logging yields accountability, which may encourage better behaviour.

Okay, enough ranting. Let's get down to business.

Data Model

Roundup stores a number of items, each of which can have several properties and an associated discussion. The properties can be used to classify or search for items. The discussion is a sequence of e-mail messages. Each item is identified by a unique number, and has an activity log which records the time and content of edits made on its properties. The log stays fairly small since the design intentionally provides only small data types as item properties, and encourages anything large to be attached to e-mail where it becomes part of the discussion. The next section explains how items are organized.

The Hyperdatabase

In my opinion, forcing items into fixed categories is one of the most serious problems with the Roundup prototype. The hyperdatabase is an experimental attempt to address the problem of information organization, whose scope goes beyond just Roundup.
Often when classifying information we are asked to select exactly one of a number of categories or to fit it into a rigid hierarchy. Yet things only sometimes fall into one category; often, a piece of information may be related to several concepts. For example, forcing each item into a single topic category is not just suboptimal but counterproductive: seekers of that item may expect to find it in a different category and conclude that the item is not present in the database -- which has them worse off than if the items were not categorized at all.

Some systems try to alleviate this problem by allowing nodes to appear at multiple locations in a tree, as with "aliases" or "symbolic links" in a filesystem, for example. This does help somewhat, but we want to be even more flexible by allowing the organization of nodes into sets that may freely intersect. Rather than putting each node at exactly one place in an overall "grand scheme", a node can belong to as many sets as are appropriate. If we choose to represent the sets themselves as nodes and set membership as a link between nodes, we're now ready to present the definition of a hyperdatabase.

Perhaps it's too pretentious a name? You could say this is just like an object database. The hyperdatabase is hardly much of an invention; the intent is merely to emphasize querying on links rather than properties. (I haven't heard of this being done with object databases before, but plead ignorance if there's already a good name for this idea.)
A hyperdatabase is a collection of nodes that may be hyperlinked to each other (hence the name "hyperdatabase"). Each node carries a collection of key-value pairs, where some of the values may be links to other nodes. Any node may have an arbitrary number of outgoing and incoming links. Hyperdatabases are able to efficiently answer queries such as "what nodes link to this node?" and "what nodes does this node link to?"

Rationale

There are several reasons for building our own kind of database for Roundup rather than using an existing one. Requiring the installation of a full-blown third-party SQL database system would probably deter many potential users from attempting to set up Roundup; yet a real relational database would be too complicated to implement on our own. On the other hand, a hyperdatabase can be implemented fairly easily using one of the Python DBM modules, so we can take the "batteries-included" approach and provide it as part of the system. It's easier to build and understand than a true relational database (in accordance with our guiding principle of simplicity), but provides most of the query functionality we want.

A hyperdatabase is well suited for finding the intersection of a number of sets in which items belong. We expect that most of the queries people want to do will be of this form, rather than complicated SQL queries. For example, a typical request might be "show me all critical items related to security". The ability to store arbitrary key-value pairs and links on nodes gives it more flexibility than an RDBMS. Users are not going to be making thousands of queries per second, so it makes sense to optimize for simplicity and flexibility rather than performance.

Roundup's Hyperdatabase

For our application, we store each item as a node in a hyperdatabase. The item's properties are stored as key-value pairs on its node. Four types of properties are allowed: string, date, choice, and reference.

The string type is for short, free-form strings. String properties are not intended to contain large amounts of text, and it is recommended that they be presented as one-line fields to encourage brevity.

The date type is for calendar dates and times.

The choice type denotes a single selection from a number of options. A choice property entails a link from the node possessing the property to the node representing the chosen option.

The reference type is for a list of links to any number of other nodes in the in the database. A reference property, for example, can be used to refer to related items or topic categories relevant to an item.

For Roundup, all items have five properties that are not customizable:

  • a string property named description
  • a reference property named superseder
  • a reference property named nosy
  • a date property named creation
  • a date property named activity

The description property is a short one-line description of the item. The detailed description can go in the first e-mail message of the item's discussion spool.

The superseder property is used to support the splitting, joining, or replacing of items. When several items need to be joined into a single item, all the old items link to the new item in their superseder property. When an item needs to be split apart, the item references all the new items in its superseder propety. We can easily list all active items just by checking for an empty superseder property, and trace the path of an item's origins by querying the hyperdatabase for links.

The nosy property contains a list of the people who are interested in an item. This mechanism is explained in the section on Nosy Lists.

The creation property records the item's creation time. The activity property records the last time that the item was edited or a mail message was added to its discussion spool. These two properties are managed by Roundup and are not available to be edited like other properties.

Users of the system are also represented by nodes in the hyperdatabase, containing properties like the user's e-mail address, login name, and password.

The Default Schema

Roundup could be distributed with a few suggested schemas for different purposes. One possible enhancement to the software-development schema is a reference property named implements for connecting development items to design requirements which they satisfy, which should be enough to provide basic support for traceability. Clearly there is also potential for adding properties for related source files, check-ins, test results, regression tests for resolved items, and so on, though these have not yet been sufficiently well thought out to specify here.

It is hoped that the hyperdatabase together with the specializations mentioned above for Roundup will be applicable in a variety of situations (in accordance with our guiding principle of generality).

To address the problem at hand, we need a specific schema for items applied particularly to software development. Again, we are trying to keep the schema simple: too many options make it tougher for someone to make a good choice. The schema is written here in the same form that it would appear in a configuration file. 

    fixer = Reference()             # people who will fix the problem

    topic = Reference()             # relevant topic keywords

    priority = Choice("critical",   # panic: work is stopped!
                      "urgent",     # important, but not deadly
                      "bug",        # lost work or incorrect results
                      "feature",    # want missing functionality
                      "wish")       # avoidable bugs, missing conveniences

    status = Choice("unread",       # submitted but no action yet
                    "deferred",     # intentionally set aside
                    "chatting",     # under review or seeking clarification
                    "need-eg",      # need a reproducible example of a bug
                    "in-progress",  # understood; development in progress
                    "testing",      # we think it's done; others, please test
                    "done-cbb",     # okay for now, but could be better
                    "resolved")     # fix has been released

The fixer property assigns responsibility for an item to a person or a list of people. The topic property places the item in an arbitrary number of relevant topic sets (see the section on Browsing and Searching).

As previously mentioned, each item gets an activity log. Whenever a property on an item is changed, the log records the time of the change, the user making the change, and the old and new values of the property. This permits the later gathering of statistics (for example, the average time from submission to resolution).

We do not specify or enforce a state transition graph, since making the system rigid in that fashion is probably more trouble than it's worth. Experience has shown that there are probably two convenient automatic state transitions:

  • from unread to chatting when e-mail is written about an item
  • from testing to resolved when a new release of the software is made
Beyond these, in accordance with our principle of generality, we allow access to the hyperdatabase API so that scripts can automate transitions themselves or be triggered by changes in the database.

User Interface

Roundup provides its services through two main interfaces: e-mail and the Web. This division is chosen to optimize the most common tasks.

E-mail is best suited for the submission of new items since most people are most comfortable with composing long messages in their own favourite e-mail client. E-mail also permits them to mention URLs or attach files relevant to their submission. Indeed, in many cases people are already used to making requests by sending e-mail to a mailing list of people; they can do exactly the same thing to use Roundup without even thinking about it. Similarly, people are already familiar with holding discussions in e-mail, and plenty of valuable usage conventions and software tools already exist for that medium.

The Web, on the other hand, is best suited for summarizing and seeking information, because it can present an interactive overview of items. Since the Web has forms, it's also the best place to edit items.

Submission and Discussion

Nosy lists have actually been tried in practice, and their emergent properties have turned out to be very effective. They are one of the key strengths of the Roundup prototype, and often cause me to wonder if all mailing lists ought to work this way. Roundup could even replace Hypermail.

The system needs an address for receiving mail and an address that forwards mail to all participants. Each item has its own list of interested parties, known as its nosy list. Here's how nosy lists work:

  1. New items are always submitted by sending an e-mail message to Roundup. The "Subject:" field becomes the description of the new item. The message is saved in the mail spool of the new item, and copied to the list of all participants so everyone knows that a new item has been added. The new item's nosy list initially contains the submitter.
  2. All e-mail messages sent by Roundup have their "Reply-To:" field set to Roundup's address, and have the item's number in the "Subject:" field. Thus, any replies to the initial announcement and subsequent threads are all received by Roundup. Roundup notes the item number in the "Subject:" field of each incoming message and appends the message to the appropriate spool.
  3. Any incoming e-mail tagged with an item number is copied to all the people on the item's nosy list, and any users found in the "From:", "To:", or "Cc:" fields are automatically added to the nosy list. Whenever a user edits an item's properties in the Web interface, they are also added to the nosy list.

The effect is like each item having its own little mailing list, except that no one ever has to worry about subscribing to anything. Indicating interest in an issue is sufficient, and if you want to bring someone new into the conversation, all you need to do is Cc: a message to them. It turns out that no one ever has to worry about unsubscribing, either: the nosy lists are so specific in scope that the conversation tends to die down by itself when the issue is resolved or people no longer find it sufficiently important.

Each nosy list is like an asynchronous chat room, lasting only a short time (typically five or ten messages) and involving a small group of people. However, that group is the right group of people: only those who express interest in an item in some way ever end up on the list, so no one gets spammed with mail they don't care about, and no one who wants to see mail about a particular item needs to be left out, for they can easily join in, and just as easily look at the mail spool on an item to catch up on any messages they might have missed.

We can take this a step further and permit users to monitor particular topics or classifications of items by allowing other kinds of nodes to also have their own nosy lists. For example, a manager could be on the nosy list of the priority value node for "critical", or a developer could be on the nosy list of the topic value node for "security". The recipients are then determined by the union of the nosy lists on the item and all the nodes it links to.

Using many small, specific mailing lists results in much more effective communication than one big list. Taking away the effort of subscribing and unsubscribing gives these lists the "feel" of being cheap and disposable. The transparent capture of the mail spool attached to each issue also yields a nice knowledge repository over time.

Editing

Since Roundup is intended to support arbitrary user-defined schema for item properties, the editing interface must be automatically generated from the schema. The configuration for Roundup will include a template describing how to lay out the properties to present a UI for inspecting and editing items. For example: 

    <table width="100%">
    <tr><td align=right>Description:</td>
        <td><?property description size=70></td></tr>
    <tr><td align=right>Status:</td>
        <td><?property status></td></tr>
    </table>

To display the editing form for an item, Roundup substitutes an HTML form widget for each <?property ...> tag, and transfers attributes (such as size=70 in the above example) from the processing tag to the form widget's tag. Each type has its own appropriate editing widget:

  • string properties appear as text fields
  • date properties appear as text fields
  • choice properties appear as selection lists
  • reference properties appear as multiple-selection lists with a text field for adding a new option

We foresee the use of custom date fields for things like deadlines, so input fields for date properties should support some simple way of specifying relative dates (such as "three weeks from now").

The superseder property is a special case: although it is more efficient to store a superseder property in the superseded item, it makes more sense to provide a "supersedes" edit field on the superseding item. So we need a special widget on items for this purpose (perhaps something as simple as a text field containing a comma-separated list of item numbers will do). Links in the superseder property should appear on both the superseding and superseded items to facilitate navigating an item's pedigree.

After the editing widgets, the item inspection page shows a "note" text box and then a display of the messages in the discussion spool, like the Roundup prototype. This field lets you enter a note explaining your change when you edit the item, and the note is included in the notification message that goes out to tell the interested parties on the nosy list of your edits.

Browsing and Searching

The ideal we would like to achieve is to make searching as much like browsing as possible: the user simply clicks about on things that seem interesting, and the information narrows down comfortably until the goal is in sight. This is preferable to trying to digest a screen filled with widgets and buttons or entering a search expression in some arcane algebraic syntax.

Though the generation of each page amounts to a database query, so that the underlying mechanism is still a series of queries and responses, the user interface never separates the query from the response, so the experience is one of stepwise refinement.
While a one-shot search may be appropriate when you're looking for a single item and you know exactly what you want, it's not very helpful when you want an overview of things ("Gee, there are a lot more high-priority items than there were last week!") or trying to do comparisons ("I have some time today, so who is busiest and could most use some help?")

The browsing interface presents filtering functionality for each of the properties in the schema. As with editing, the interface is generated from a template describing how to lay out the properties. Each type of property has its own appropriate filtering widget:

  • string properties appear as text fields supporting case-insensitive substring match
  • date properties appear as a text field with an option to choose dates after or before the specified date
  • choice properties appear as a group of selectable options (the filter selects the union of the sets of items associated with the active options)
  • reference properties appear as a group of selectable options (the filter selects the intersection of the sets of items associated with the active options)

For a reference property like topic, one possibility is to show, as hyperlinks, the keywords whose sets have non-empty intersections with the currently displayed set of items. Sorting the keywords by popularity seems reasonable. Clicking on a keyword then narrows both the list of items and the list of keywords. This gives some of the feel of walking around a directory tree -- but without the restriction of having to select keywords in a particular hierarchical order, and without the need to travel all the way to the leaves of the tree before any items are visible.

Below the filtering form is a listing of items, with their properties displayed in a table. Rows in the table can also be generated from a template, as with the editing interface. This listing is the central overview of the system, and it should aim to maximize the density of useful information in accordance with our guiding principle of efficiency. For example, Bugzilla initially displays seven or eight items of the index, but only after the user has waded through three bewildering screens of form widgets. Jitterbug can't even fit any items at all in the first screenful, as it's taken up by artwork and adminstrative debris. In contrast, in the Roundup prototype, 25 high-priority issues are immediately visible, with most of the screen space devoted to their descriptions. Colour indicates the status of each item to help the eye sift through the index quickly.

In both Jitterbug and Bugzilla, items are sorted by default by ID, a meaningless field. Sorting by ID puts the issues in order by ascending submission date, which banishes recent issues far away at the bottom of the list. The Roundup prototype sorts items in sections by priority, and then within sections by the date of last activity. This reveals at a glance where discussion is most active, and provides an easy way for anyone to move an issue up in the list.

The page produced by a given set of browsing options constitutes a view. The options should all be part of the query parameters in the URL so that views may be bookmarked. A view specifies:

  • search strings for string properties
  • date ranges for date properties
  • acceptable values for choice properties
  • required values for reference properties
  • one or more sort keys
  • a list of properties for which to display filtering widgets

On each sort key there is the option to use sections -- that is, instead of making the property's value a column of the table, each possible value for the property is displayed at the top of a section and all the items having that value for that property are grouped underneath. This avoids wasting screen space with redundant information.

We propose that our default view should be:

  • all options on for priority and fixer
  • all options on except "resolved" for status
  • no options on for topic
  • primary sort by priority in sections
  • secondary sort by decreasing activity date

The starting URL for Roundup should immediately present the listing of items generated by this default view, with no preceding query screen.

Development Plan

The hyperdatabase is clearly a separable component which can be developed and tested independently to an API specification.

As soon as the API to the hyperdatabase is nailed down, the implementation of the Roundup database layer on top of the hyperdatabase can begin. (This refers to the data types and five fixed properties specific to Roundup.) This layer can also be tested separately.

When the interface to the Roundup hyperdatabase is ready, development can begin on the user interface. The mail handler and the Web interface can be developed in parallel and mostly independently of each other.

The mail handler can be set up for testing fairly easily: mail messages on its standard input can be synthesized; its output is outgoing mail, which can be captured by replacing the implementation of the "send mail" function; and its side effects appear in the hyperdatabase, which has a Python API.

The Web interface is not easily testable in its entirety, though the most important components of it can be unit tested, such as the component that translates a view specification into a list of items for display, and the component that performs replacements on templates to produce an editing or filtering interface.

Open Issues

The description of the hyperdatabase above avoids some issues regarding node typing that need to be better specified. It is conceivable that eventually Roundup could support multiple kinds of items with their own schemas.

To permit integration with external tools, it is probably a good idea to provide a command-line tool that exposes the hyperdatabase API. This tool will be left for a later phase of development and so isn't specified in detail here.

Generating the user interface from a template is like applying an XSL stylesheet to XML, and if there's a standard Python module for performing these transformations, we could use XML instead.

More thinking is needed to determine the best filtering interface for reference properties. The proposed interface works well for topic keywords, but it isn't clear what to do when there are too many keywords to display them all.

There has been a variety of reactions to the hyperdatabase from reviewers: some like it, some are neutral, and some would prefer a "standard" RDBMS solution. For those in the latter camp, note that it's still possible to build the Roundup database layer around an RDBMS if we really need to. The rest of the design, in particular the "nosy list" mechanism, remains intact.

The possibility of malice by registered users has been disregarded. The system is intended to be used by a co-operative group.

This design tries to address as many as possible of the suggested requirements mentioned on the contest page:

  • configuring states: Edit the schema.
  • setting state transition rules: We don't enforce any rules.
  • assigning responsibility: Set the fixer property.
  • splitting and joining: Use the superseder property.
  • hiding information: Add a property and a pre-defined view that filters on it.
  • secure protocols: Naturally HTTPS would be nice, though it's largely a webserver configuration issue; secure e-mail is not addressed.
  • archiving old issues: Tag them with a property.
  • identifying repeated issues: Use the superseder property.
  • connecting state changes to external operations: We provide an API to the database and the notification mechanism so it can be scripted.
  • non-Latin alphabets: Unicode in Python 1.6 will handle this for string properties, and we can leverage existing standards for internationalizing e-mail messages.
  • images and other binaries: Attach them to e-mail messages.
  • inspecting item state: Use the editing interface.
  • translation between system-dependent formats: This is not addressed.
  • performing searches: Use the browsing and filtering interface.
  • collecting statistics: Information is gathered in the activity log, though tools to summarize it are not described here.

Summary

Roundup is an issue-tracking system that also functions as a communications center and a knowledge repository. It combines the strengths of e-mail and the Web to try to provide the best possible user interaction.

  • The submission and discussion of items by e-mail, permitting participants to use an easy and familiar tool, achieves our goal of low barrier to participation.
  • The generic link-based structuring of data and use of incremental filtering rather than one-shot querying makes for straightforward navigation.
  • The use of nosy lists (a powerful replacement for e-mail discussion lists) to manage communication on a fine-grained level provides controlled information flow.

The use of a "hyperdatabase" as the core model for the knowledge repository gives us the flexibility to extend Roundup and apply it to a variety of domains by providing new item schemas and user-interface templates.

Roundup is self-contained and easy to set up, requiring only a webserver and a mailbox. No one needs to be root to configure the webserver or to install database software.

This design is based on an existing deployed prototype which has proven its strengths and revealed its weaknesses in heavy day-to-day use by a real development team.

Acknowledgements

My thanks are due to Christina Heyl, Jesse Vincent, Mark Miller, Christopher Simons, Jeff Dunmall, Wayne Gramlich, and Dean Tribble for reviewing this paper and contributing their suggestions.

   [Home]       [FAQ]       [License]       [Rules]       [Resources]       [Archives]   

Last modified 2001/04/06 11:50:59.9063 US/Mountain
code-001c16ac87ec/doc/html_extra/roundup_short_paper.html0000644000000000000000000001700615046233326021635 0ustar 00000000000000 Roundup: A Simple and Effective Issue Tracker in Python
 
 
Roundup Short Paper		[LFW]

Roundup: A Simple and Effective Issue Tracker in Python

Ka-Ping Yee (original site: http://www.lfw.org/ping/roundup.html)

Please note that there is a new, active Roundup project led by Richard Jones. Please visit them at SourceForge.

The Roundup prototype is open source. You can download it here (roundup.tar.gz, 32 kb). Or play with the live prototype! When prompted for authentication, you can use one of the test accounts: "test", "spam", or "eggs" (password same as account name). Roundup's e-mail address is roundup---lfw.org. You can't create new accounts, but you can read the mail spools for test, spam, or eggs here to see what they're getting.

A detailed design proposal for a more advanced issue-tracking system based on Roundup has been submitted to Software Carpentry's open source software design competition. This first-round submission was selected as a finalist. A more detailed implementation guide was submitted to the second round of the competition.

You might also want to check out other Python-related stuff on this site.

This short talk will share some experiences from developing and using the issue tracking system used by my development group at ILM. It integrates two modes of access: e-mail for gathering information, and the Web for search and retrieval. We currently work with it daily and it does its job pretty well.

Fine-Grained Mailing Lists

The key strength of Roundup is that it generates a small virtual mailing list for each new issue. In a way, this is like implementing private conversation rooms in e-mail. Although the mechanism is very simple, the emergent properties are quite effective. Here's how it works:

  1. New issues are always submitted by sending an e-mail message. This message is saved in a mail spool attached to the newly-created issue record, and copied to the relatively large user community of the application so everyone knows the issue has been raised.
  2. All e-mail messages sent by Roundup have their "Reply-To" field set to send mail back to Roundup, and have the issue's ID number in the Subject field. So, any replies to the initial announcement and subsequent threads are all received by Roundup and appended to the spool.
  3. Each issue has a "nosy list" of people interested in the issue. Any mail tagged with the issue's ID number is copied to this list of people, and any users found in the From:, To:, or Cc: fields of e-mail about the issue are automatically added to the nosy list. Whenever a user edits an item in the Web interface, they are also added to the list.

The result is that no one ever has to worry about subscribing to anything. Indicating interest in an issue is sufficient, and if you want to bring someone new into the conversation, all you need to do is Cc: a message to them. It turns out that no one ever has to worry about unsubscribing, either: the nosy lists are so specific in scope that the conversation tends to die down by itself when the issue is resolved or people no longer find it sufficiently important. The transparent capture of the mail spool attached to each issue also yields a nice searchable knowledge repository over time.

User Interface Decisions

The web interface to Roundup aims to maximize the density of useful information. Although this principle is important to all information presentation, it is especially vital in a web browser because of the limited window real estate. Hence Roundup avoids repetitive or unnecessary information and tries to fit as many items as possible on the first screen. For example, Bugzilla initially displays seven or eight items of the index; Jitterbug can't even manage to fit any items at all in the first screenful, as it's taken up by artwork and adminstrative debris. In contrast, Roundup shows you about 25 high-priority issues right away. Colour indicates the status of each item to help the eye sift through the index quickly.

In both Jitterbug and Bugzilla, items are sorted by default by ID, a meaningless field. Sorting by ID puts the issues in order by ascending submission date, which banishes recent issues as far away as possible at the bottom of the list. Roundup sorts items in sections by priority so the high-priority items are immediately visible; within sections, items are sorted by date of last activity. This reveals at a glance where discussion is most active, and provides an easy way for anyone to move an issue up in the list without changing its priority.

(The following has been added for this web page and was not part of the short paper in the IPC8 proceedings.)

Screenshots of the Web Interface

Here is the Roundup index, the first thing presented to you when you go to Roundup. Note the use of colour coding and the attempt to dedicate maximum space to the description of each issue.

In comparison, here is the first screen you see when you use Jitterbug. No information is actually visible! You have to scroll down to the second screen before you get to see any bugs, and even then your view is limited to a paltry eight entries. The boldface on the item descriptions helps, but the visual effect of the table is still swamped by the powerful green header line -- which contains zero bits of new information.

As another example, Bugzilla presents somewhat more information than Jitterbug in its index view, but forces you to go through three bewildering screens replete with form widgets (one, two, three) before you even get to see anything. Examination of the index view shows that one-third to one-half of the screen area (depending how you count it) is wasted on trivialities or empty space, and the most important column, the description of each issue, is shoved off of the right side of the page.

copyright © by Ka-Ping Yee updated Sun 2 Jul 2000
code-001c16ac87ec/doc/html_extra/spec.html0000644000000000000000000016332315046233326016471 0ustar 00000000000000 Software Carpentry Track: Roundup
[Software Carpentry logo]
[ACL Logo]
[CodeSourcery Logo]

Roundup

An Issue-Tracking System for Knowledge Workers

Ka-Ping Yee
ping@lfw.org

Implementation Guide

Contents

  1. Introduction
  2. The Layer Cake
  3. Hyperdatabase
    1. Dates and Date Arithmetic
    2. Items and Classes
    3. Identifiers and Designators
    4. Property Names and Types
    5. Interface Specification
    6. Application Example
  4. Roundup Database
    1. Reserved Classes
      1. Users
      2. Messages
      3. Files
    2. Item Classes
    3. Interface Specification
    4. Default Schema
  5. Detector Interface
    1. Interface Specification
    2. Detector Example
  6. Command Interface
    1. Interface Specification
    2. Usage Example
  7. E-mail User Interface
    1. Message Processing
    2. Nosy Lists
    3. Setting Properties
    4. Workflow Example
  8. Web User Interface
    1. Views and View Specifiers
    2. Displaying Properties
    3. Index Views
      1. Index View Specifiers
      2. Filter Section
      3. Index Section
      4. Sorting
    4. Item Views
      1. Item View Specifiers
      2. Editor Section
      3. Spool Section
  9. Deployment Scenarios
  10. Acknowledgements

1. Introduction

This document presents a description of the components of the Roundup system and specifies their interfaces and behaviour in sufficient detail to guide an implementation. For the philosophy and rationale behind the Roundup design, see the first-round Software Carpentry submission for Roundup. This document fleshes out that design as well as specifying interfaces so that the components can be developed separately.

2. The Layer Cake

Lots of software design documents come with a picture of a cake. Everybody seems to like them. I also like cakes (i think they are tasty). So i, too, shall include a picture of a cake here.

E-mail Client

Web Browser

Detector Scripts

Shell

E-mail User Interface

Web User Interface

Detector Interface

Command Interface

Roundup Database Layer

Hyperdatabase Layer

Storage Layer

The colourful parts of the cake are part of our system; the faint grey parts of the cake are external components.

I will now proceed to forgo all table manners and eat from the bottom of the cake to the top. You may want to stand back a bit so you don't get covered in crumbs.

3. Hyperdatabase

The lowest-level component to be implemented is the hyperdatabase. The hyperdatabase is intended to be a flexible data store that can hold configurable data in records which we call items.

The hyperdatabase is implemented on top of the storage layer, an external module for storing its data. The storage layer could be a third-party RDBMS; for a "batteries-included" distribution, implementing the hyperdatabase on the standard bsddb module is suggested.

3.1. Dates and Date Arithmetic

Before we get into the hyperdatabase itself, we need a way of handling dates. The hyperdatabase module provides Timestamp objects for representing date-and-time stamps and Interval objects for representing date-and-time intervals.

As strings, 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 with the time always given in GMT. The full date format is always exactly 19 characters long.

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; and suppose that the user is on Eastern Standard Time.

  • "2000-04-17" means <Date 2000-04-17.00:00:00>
  • "01-25" means <Date yyyy-01-25.00:00:00>
  • "2000-04-17.03:45" means <Date 2000-04-17.08:45:00>
  • "08-13.22:13" means <Date yyyy-08-14.03:13:00>
  • "11-07.09:32:43" means <Date yyyy-11-07.14:32:43>
  • "14:25" means <Date yyyy-mm-dd.19:25:00>
  • "8:47:11" means <Date yyyy-mm-dd.13:47:11>
  • the special date "." means "right now"

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

The Date class should understand simple date expressions of the form stamp + interval and stamp - interval. When adding or subtracting intervals involving months or years, the components are handled separately. For example, when evaluating "2000-06-25 + 1m 10d", we first add one month to get 2000-07-25, then add 10 days to get 2000-08-04 (rather than trying to decide whether 1m 10d means 38 or 40 or 41 days).

Here is an outline of the Date and Interval classes. 

class Date:
    def __init__(self, spec, offset):
        """Construct a date given a specification and a time zone offset.

        'spec' is a full date or a partial form, with an optional
        added or subtracted interval.  'offset' is the local time
        zone offset from GMT in hours.
        """

    def __add__(self, interval):
        """Add an interval to this date to produce another date."""

    def __sub__(self, interval):
        """Subtract an interval from this date to produce another date."""

    def __cmp__(self, other):
        """Compare this date to another date."""

    def __str__(self):
        """Return this date as a string in the yyyy-mm-dd.hh:mm:ss format."""

    def local(self, offset):
        """Return this date as yyyy-mm-dd.hh:mm:ss in a local time zone."""

class Interval:
    def __init__(self, spec):
        """Construct an interval given a specification."""

    def __cmp__(self, other):
        """Compare this interval to another interval."""
        
    def __str__(self):
        """Return this interval as a string."""

Here are some examples of how these classes would behave in practice. For the following examples, assume that we are on Eastern Standard Time and the current local time is 19:34:02 on 25 June 2000. 

>>> Date(".")
<Date 2000-06-26.00:34:02>
>>> _.local(-5)
"2000-06-25.19:34:02"
>>> Date(". + 2d")
<Date 2000-06-28.00:34:02>
>>> Date("1997-04-17", -5)
<Date 1997-04-17.00:00:00>
>>> Date("01-25", -5)
<Date 2000-01-25.00:00:00>
>>> Date("08-13.22:13", -5)
<Date 2000-08-14.03:13:00>
>>> Date("14:25", -5)
<Date 2000-06-25.19:25:00>
>>> Interval("  3w  1  d  2:00")
<Interval 22d 2:00>
>>> Date(". + 2d") - Interval("3w")
<Date 2000-06-07.00:34:02>

3.2. Items and Classes

Items contain data in properties. To Python, these properties are presented as the key-value pairs of a dictionary. Each item belongs to a class which defines the names and types of its properties. The database permits the creation and modification of classes as well as items.

3.3. Identifiers and Designators

Each item has a numeric identifier which is unique among items in its class. The items are numbered sequentially within each class in order of creation, starting from 1. The designator for an item is a way to identify an item in the database, and consists of the name of the item's class concatenated with the item's numeric identifier.

For example, if "spam" and "eggs" are classes, the first item created in class "spam" has id 1 and designator "spam1". The first item created in class "eggs" also has id 1 but has the distinct designator "eggs1". Item designators are conventionally enclosed in square brackets when mentioned in plain text. This permits a casual mention of, say, "[patch37]" in an e-mail message to be turned into an active hyperlink.

3.4. Property Names and Types

Property names must begin with a letter.

A property may be one of five basic types:

  • String properties are for storing arbitrary-length strings.
  • Date properties store date-and-time stamps. Their values are Timestamp objects.
  • 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.

None is also a permitted value for any of these property types. An attempt to store None into a String property stores the empty string; an attempt to store None into a Multilink property stores an empty list.

3.5. Interface Specification

The hyperdb module provides property objects to designate the different kinds of properties. These objects are used when specifying what properties belong in classes. 

class String:
    def __init__(self):
        """An object designating a String property."""

class Date:
    def __init__(self):
        """An object designating a Date property."""

class Link:
    def __init__(self, classname):
        """An object designating a Link property that links to
        items in a specified class."""

class Multilink:
    def __init__(self, classname):
        """An object designating a Multilink property that links
        to items in a specified class."""

Here is the interface provided by the hyperdatabase. 

class Database:
    """A database for storing records containing flexible data types."""

    def __init__(self, storagelocator, journaltag):
        """Open a hyperdatabase given a specifier to some storage.

        The meaning of 'storagelocator' depends on the particular
        implementation of the hyperdatabase.  It could be a file name,
        a directory path, a socket descriptor for a connection to a
        database over the network, etc.

        The 'journaltag' is a token that will be attached to the journal
        entries for any edits done on the database.  If 'journaltag' is
        None, the database is opened in read-only mode: the Class.create(),
        Class.set(), and Class.retire() methods are disabled.
        """

    def __getattr__(self, classname):
        """A convenient way of calling self.getclass(classname)."""

    def getclasses(self):
        """Return a list of the names of all existing classes."""

    def getclass(self, classname):
        """Get the Class object representing a particular class.

        If 'classname' is not a valid class name, a KeyError is raised.
        """

class Class:
    """The handle to a particular class of items in a hyperdatabase."""

    def __init__(self, db, classname, **properties):
        """Create a new class with a given name and property specification.

        'classname' must not collide with the name of an existing class,
        or a ValueError is raised.  The keyword arguments in 'properties'
        must map names to property objects, or a TypeError is raised.
        """

    # Editing items:

    def create(self, **propvalues):
        """Create a new item of this class and return its id.

        The keyword arguments in 'propvalues' map property names to values.
        The values of arguments must be acceptable for the types of their
        corresponding properties or a TypeError is raised.  If this class
        has a key property, it must be present and its value must not
        collide with other key strings or a ValueError is raised.  Any other
        properties on this class that are missing from the 'propvalues'
        dictionary are set to None.  If an id in a link or multilink
        property does not refer to a valid item, an IndexError is raised.
        """

    def get(self, itemid, propname):
        """Get the value of a property on an existing item of this class.

        'itemid' must be the id of an existing item of this class or an
        IndexError is raised.  'propname' must be the name of a property
        of this class or a KeyError is raised.
        """

    def set(self, itemid, **propvalues):
        """Modify a property on an existing item of this class.
        
        'itemid' must be the id of an existing item of this class or an
        IndexError is raised.  Each key in 'propvalues' must be the name
        of a property of this class or a KeyError is raised.  All values
        in 'propvalues' must be acceptable types for their corresponding
        properties or a TypeError is raised.  If the value of the key
        property is set, it must not collide with other key strings or a
        ValueError is raised.  If the value of a Link or Multilink
        property contains an invalid item id, a ValueError is raised.
        """

    def retire(self, itemid):
        """Retire an item.
        
        The properties on the item remain available from the get() method,
        and the item's id is never reused.  Retired items are not returned
        by the find(), list(), or lookup() methods, and other items may
        reuse the values of their key properties.
        """

    def history(self, itemid):
        """Retrieve the journal of edits on a particular item.

        'itemid' must be the id of an existing item of this class or an
        IndexError is raised.

        The returned list contains tuples of the form

            (date, tag, action, params)

        'date' is a Timestamp object specifying the time of the change and
        'tag' is the journaltag specified when the database was opened.
        'action' may be:

            'create' or 'set' -- 'params' is a dictionary of property values
            'link' or 'unlink' -- 'params' is (classname, itemid, propname)
            'retire' -- 'params' is None
        """

    # Locating items:

    def setkey(self, propname):
        """Select a String property of this class to be the key property.

        'propname' must be the name of a String property of this class or
        None, or a TypeError is raised.  The values of the key property on
        all existing items must be unique or a ValueError is raised.
        """

    def getkey(self):
        """Return the name of the key property for this class or None."""

    def lookup(self, keyvalue):
        """Locate a particular item by its key property and return its id.

        If this class has no key property, a TypeError is raised.  If the
        'keyvalue' matches one of the values for the key property among
        the items in this class, the matching item's id is returned;
        otherwise a KeyError is raised.
        """

    def find(self, propname, itemid):
        """Get the ids of items in this class which link to a given item.
        
        'propname' must be the name of a property in this class, or a
        KeyError is raised.  That property must be a Link or Multilink
        property, or a TypeError is raised.  'itemid' must be the id of
        an existing item in the class linked to by the given property,
        or an IndexError is raised.
        """

    def list(self):
        """Return a list of the ids of the active items in this class."""

    def count(self):
        """Get the number of items in this class.

        If the returned integer is 'numitems', the ids of all the items
        in this class run from 1 to numitems, and numitems+1 will be the
        id of the next item to be created in this class.
        """

    # Manipulating properties:

    def getprops(self):
        """Return a dictionary mapping property names to property objects."""

    def addprop(self, **properties):
        """Add properties to this class.

        The keyword arguments in 'properties' must map names to property
        objects, or a TypeError is raised.  None of the keys in 'properties'
        may collide with the names of existing properties, or a ValueError
        is raised before any properties have been added.
        """

3.6. Application Example

Here is an example of how the hyperdatabase module would work in practice. 

>>> import hyperdb
>>> db = hyperdb.Database("foo.db", "ping")
>>> db
<hyperdb.Database "foo.db" opened by "ping">
>>> hyperdb.Class(db, "status", name=hyperdb.String())
<hyperdb.Class "status">
>>> _.setkey("name")
>>> db.status.create(name="unread")
1
>>> db.status.create(name="in-progress")
2
>>> db.status.create(name="testing")
3
>>> db.status.create(name="resolved")
4
>>> db.status.count()
4
>>> db.status.list()
[1, 2, 3, 4]
>>> db.status.lookup("in-progress")
2
>>> db.status.retire(3)
>>> db.status.list()
[1, 2, 4]
>>> hyperdb.Class(db, "issue", title=hyperdb.String(), status=hyperdb.Link("status"))
<hyperdb.Class "issue">
>>> db.issue.create(title="spam", status=1)
1
>>> db.issue.create(title="eggs", status=2)
2
>>> db.issue.create(title="ham", status=4)
3
>>> db.issue.create(title="arguments", status=2)
4
>>> db.issue.create(title="abuse", status=1)
5
>>> hyperdb.Class(db, "user", username=hyperdb.Key(), password=hyperdb.String())
<hyperdb.Class "user">
>>> db.issue.addprop(fixer=hyperdb.Link("user"))
>>> db.issue.getprops()
{"title": <hyperdb.String>, "status": <hyperdb.Link to "status">,
 "user": <hyperdb.Link to "user">}
>>> db.issue.set(5, status=2)
>>> db.issue.get(5, "status")
2
>>> db.status.get(2, "name")
"in-progress"
>>> db.issue.get(5, "title")
"abuse"
>>> db.issue.find("status", db.status.lookup("in-progress"))
[2, 4, 5]
>>> db.issue.history(5)
[(<Date 2000-06-28.19:09:43>, "ping", "create", {"title": "abuse", "status": 1}),
 (<Date 2000-06-28.19:11:04>, "ping", "set", {"status": 2})]
>>> db.status.history(1)
[(<Date 2000-06-28.19:09:43>, "ping", "link", ("issue", 5, "status")),
 (<Date 2000-06-28.19:11:04>, "ping", "unlink", ("issue", 5, "status"))]
>>> db.status.history(2)
[(<Date 2000-06-28.19:11:04>, "ping", "link", ("issue", 5, "status"))]

For the purposes of journalling, when a Multilink property is set to a new list of items, the hyperdatabase compares the old list to the new list. The journal records "unlink" events for all the items that appear in the old list but not the new list, and "link" events for all the items that appear in the new list but not in the old list.

4. Roundup Database

The Roundup database layer is implemented on top of the hyperdatabase and mediates calls to the database. Some of the classes in the Roundup database are considered item classes. The Roundup database layer adds detectors and user items, and on items it provides mail spools, nosy lists, and superseders.

4.1. Reserved Classes

Internal to this layer we reserve three special classes of items that are not items.

4.1.1. Users

Users are stored in the hyperdatabase as items of class "user". The "user" class has the definition: 

hyperdb.Class(db, "user", username=hyperdb.String(),
                          password=hyperdb.String(),
                          address=hyperdb.String())
db.user.setkey("username")

4.1.2. Messages

E-mail messages are represented by hyperdatabase items of class "msg". The actual text content of the messages is stored in separate files. (There's no advantage to be gained by stuffing them into the hyperdatabase, and if messages are stored in ordinary text files, they can be grepped from the command line.) The text of a message is saved in a file named after the message item designator (e.g. "msg23") for the sake of the command interface (see below). Attachments are stored separately and associated with "file" items. The "msg" class has the definition: 

hyperdb.Class(db, "msg", author=hyperdb.Link("user"),
                         recipients=hyperdb.Multilink("user"),
                         date=hyperdb.Date(),
                         summary=hyperdb.String(),
                         files=hyperdb.Multilink("file"))

The "author" property indicates the author of the message (a "user" item must exist in the hyperdatabase for any messages that are stored in the system). The "summary" property contains a summary of the message for display in a message index.

4.1.3. Files

Submitted files are represented by hyperdatabase items of class "file". Like e-mail messages, the file content is stored in files outside the database, named after the file item designator (e.g. "file17"). The "file" class has the definition: 

hyperdb.Class(db, "file", user=hyperdb.Link("user"),
                          name=hyperdb.String(),
                          type=hyperdb.String())

The "user" property indicates the user who submitted the file, the "name" property holds the original name of the file, and the "type" property holds the MIME type of the file as received.

4.2. Item Classes

All items have the following standard properties: 

title=hyperdb.String()
messages=hyperdb.Multilink("msg")
files=hyperdb.Multilink("file")
nosy=hyperdb.Multilink("user")
superseder=hyperdb.Multilink("item")

Also, two Date properties named "creation" and "activity" are fabricated by the Roundup database layer. By "fabricated" we mean that no such properties are actually stored in the hyperdatabase, but when properties on items are requested, the "creation" and "activity" properties are made available. 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).

4.3. Interface Specification

The interface to a Roundup database delegates most method calls to the hyperdatabase, except for the following changes and additional methods. 

class Database:
    # Overridden methods:

    def __init__(self, storagelocator, journaltag):
        """When the Roundup database is opened by a particular user,
        the 'journaltag' is the id of the user's "user" item."""

    def getclass(self, classname):
        """This method now returns an instance of either Class or
        ItemClass depending on whether an item class is specified."""

    # New methods:

    def getuid(self):
        """Return the id of the "user" item associated with the user
        that owns this connection to the hyperdatabase."""

class Class:
    # Overridden methods:

    def create(self, **propvalues):
    def set(self, **propvalues):
    def retire(self, itemid):
        """These operations trigger detectors and can be vetoed.  Attempts
        to modify the "creation" or "activity" properties cause a KeyError.
        """

    # New methods:

    def audit(self, event, detector):
    def react(self, event, detector):
        """Register a detector (see below for more details)."""

class ItemClass(Class):
    # Overridden methods:

    def __init__(self, db, classname, **properties):
        """The newly-created class automatically includes the "messages",
        "files", "nosy", and "superseder" properties.  If the 'properties'
        dictionary attempts to specify any of these properties or a
        "creation" or "activity" property, a ValueError is raised."""

    def get(self, itemid, propname):
    def getprops(self):
        """In addition to the actual properties on the item, these
        methods provide the "creation" and "activity" properties."""

    # New methods:

    def addmessage(self, itemid, summary, text):
        """Add a message to an item's mail spool.

        A new "msg" item is constructed using the current date, the
        user that owns the database connection as the author, and
        the specified summary text.  The "files" and "recipients"
        fields are left empty.  The given text is saved as the body
        of the message and the item is appended to the "messages"
        field of the specified item.
        """

    def nosymessage(self, itemid, msgid):
        """Send a message to the members of an item's nosy list.

        The message is sent only to users on the nosy list who are not
        already on the "recipients" list for the message.  These users
        are then added to the message's "recipients" list.
        """

4.4. Default Schema

The default schema included with Roundup turns it into a typical software bug tracker. The database is set up like this: 

pri = Class(db, "priority", name=hyperdb.String(), order=hyperdb.String())
pri.setkey("name")
pri.create(name="critical", order="1")
pri.create(name="urgent", order="2")
pri.create(name="bug", order="3")
pri.create(name="feature", order="4")
pri.create(name="wish", order="5")

stat = Class(db, "status", name=hyperdb.String(), order=hyperdb.String())
stat.setkey("name")
stat.create(name="unread", order="1")
stat.create(name="deferred", order="2")
stat.create(name="chatting", order="3")
stat.create(name="need-eg", order="4")
stat.create(name="in-progress", order="5")
stat.create(name="testing", order="6")
stat.create(name="done-cbb", order="7")
stat.create(name="resolved", order="8")

Class(db, "keyword", name=hyperdb.String())

Class(db, "issue", fixer=hyperdb.Multilink("user"),
                   topic=hyperdb.Multilink("keyword"),
                   priority=hyperdb.Link("priority"),
                   status=hyperdb.Link("status"))

(The "order" property hasn't been explained yet. It gets used by the Web user interface for sorting.)

The above isn't as pretty-looking as the schema specification in the first-stage submission, but it could be made just as easy with the addition of a convenience function like Choice for setting up the "priority" and "status" classes: 

def Choice(name, *options):
    cl = Class(db, name, name=hyperdb.String(), order=hyperdb.String())
    for i in range(len(options)):
        cl.create(name=option[i], order=i)
    return hyperdb.Link(name)

5. Detector Interface

Detectors are Python functions that are triggered on certain kinds of events. The definitions of the functions live in Python modules placed in a directory set aside for this purpose. Importing the Roundup database module also imports all the modules in this directory, and the init() function of each module is called when a database is opened to provide it a chance to register its detectors.

There are two kinds of detectors:

  • an auditor is triggered just before modifying an item
  • a reactor is triggered just after an item has been modified

When the Roundup database is about to perform a create(), set(), or retire() operation, it first calls any auditors that have been registered for that operation on that class. Any auditor may raise a Reject exception to abort the operation.

If none of the auditors raises an exception, the database proceeds to carry out the operation. After it's done, it then calls all of the reactors that have been registered for the operation.

5.1. Interface Specification

The audit() and react() methods register detectors on a given class of items. 

class Class:
    def audit(self, event, detector):
        """Register an auditor on this class.

        'event' should be one of "create", "set", or "retire".
        'detector' should be a function accepting four arguments.
        """

    def react(self, event, detector):
        """Register a reactor on this class.

        'event' should be one of "create", "set", or "retire".
        'detector' should be a function accepting four arguments.
        """

Auditors are called with the arguments: 

audit(db, cl, itemid, newdata)
where db is the database, cl is an instance of Class or ItemClass 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() 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 ItemClass 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() operation, itemid is the id of the retired item and olddata is None.

5.2. Detector Example

Here is an example of detectors written for a hypothetical project-management application, where users can signal approval of a project by adding themselves to an "approvals" list, and a project proceeds when it has three approvals. 

# Permit users only to add themselves to the "approvals" list.

def check_approvals(db, cl, id, newdata):
    if newdata.has_key("approvals"):
        if cl.get(id, "status") == db.status.lookup("approved"):
            raise Reject, "You can't modify the approvals list " \
                          "for a project that has already been approved."
        old = cl.get(id, "approvals")
        new = newdata["approvals"]
        for uid in old:
            if uid not in new and uid != db.getuid():
                raise Reject, "You can't remove other users from the "
                              "approvals list; you can only remove yourself."
        for uid in new:
            if uid not in old and uid != db.getuid():
                raise Reject, "You can't add other users to the approvals "
                              "list; you can only add yourself."

# When three people have approved a project, change its
# status from "pending" to "approved".

def approve_project(db, cl, id, olddata):
    if olddata.has_key("approvals") and len(cl.get(id, "approvals")) == 3:
        if cl.get(id, "status") == db.status.lookup("pending"):
            cl.set(id, status=db.status.lookup("approved"))

def init(db):
    db.project.audit("set", check_approval)
    db.project.react("set", approve_project)

Here is another example of a detector that can allow or prevent the creation of new items. In this scenario, patches for a software project are submitted by sending in e-mail with an attached file, and we want to ensure that there are text/plain attachments on the message. The maintainer of the package can then apply the patch by setting its status to "applied". 

# Only accept attempts to create new patches that come with patch files.

def check_new_patch(db, cl, id, newdata):
    if not newdata["files"]:
        raise Reject, "You can't submit a new patch without " \
                      "attaching a patch file."
    for fileid in newdata["files"]:
        if db.file.get(fileid, "type") != "text/plain":
            raise Reject, "Submitted patch files must be text/plain."

# When the status is changed from "approved" to "applied", apply the patch.

def apply_patch(db, cl, id, olddata):
    if cl.get(id, "status") == db.status.lookup("applied") and \
        olddata["status"] == db.status.lookup("approved"):
        # ...apply the patch...

def init(db):
    db.patch.audit("create", check_new_patch)
    db.patch.react("set", apply_patch)

6. Command Interface

The command interface is a very simple and minimal interface, intended only for quick searches and checks from the shell prompt. (Anything more interesting can simply be written in Python using the Roundup database module.)

6.1. Interface Specification

A single command, roundup, provides basic access to the hyperdatabase from the command line.

  • roundup get [-list] designator[,designator,...] propname
  • roundup set designator[,designator,...] propname=value ...
  • roundup find [-list] classname propname=value ...

Property values are represented as strings in command arguments and in the printed results:

  • Strings are, well, strings.
  • 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 above.
  • 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 -list) option.

6.2. Usage Example

To find all messages regarding in-progress 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 find issue status=in-progress`; do
> grep -l spam `roundup get $issue messages`
> done
msg23
msg49
msg50
msg61
shell%

Or, using the -list option, this can be written as a single command: 

shell% grep -l spam `roundup get \
    \`roundup find -list issue status=in-progress\` messages`
msg23
msg49
msg50
msg61
shell%

7. E-mail User Interface

The Roundup system must be assigned an e-mail address at which to receive mail. Messages should be piped to the Roundup mail-handling script by the mail delivery system (e.g. using an alias beginning with "|" for sendmail).

7.1. Message Processing

Incoming messages are examined for multiple parts. In a multipart/mixed message or part, each subpart is extracted and examined. In a multipart/alternative message or part, we look for a text/plain subpart and ignore the other parts. 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.

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.

All of the addresses in the To: and Cc: headers of the incoming message are looked up among the user items, 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 web interface does not permit logins for users with no passwords.) If we prefer to reject mail from outside sources, we can simply register an auditor on the "user" class that prevents the creation of user items with no passwords.

The subject line of the incoming message is examined to determine whether the message is an attempt to create a new item or to discuss an existing item. A designator enclosed in square brackets is sought as the first thing on the subject line (after skipping any "Fwd:" or "Re:" prefixes).

If an item designator (class name and id number) is found there, the newly created "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.

Both cases may trigger detectors (in the first case we are calling the set() method to add the message to the item's spool; in the second case we are calling the create() method to create a new item). If an auditor raises an exception, the original message is bounced back to the sender with the explanatory message given in the exception.

7.2. Nosy Lists

A standard detector is provided that watches for additions to the "messages" property. When a new message is added, the detector sends it 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.

7.3. 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.

8. Web User Interface

The web interface is provided by a CGI script that can be run under any web server. A simple web server can easily be built on the standard CGIHTTPServer module, and should also be included in the distribution for quick out-of-the-box deployment.

The user interface is constructed from a number of template files containing mostly HTML. Among the HTML tags in templates are interspersed some nonstandard tags, which we use as placeholders to be replaced by properties and their values.

8.1. Views and View Specifiers

There are two main kinds of views: index views and item views. An index view displays a list of items of a particular class, optionally sorted and filtered as requested. An item view presents the properties of a particular item for editing and displays the message spool for the item.

A view specifier is a string that specifies all the options needed to construct a particular view. It goes after the URL to the Roundup CGI script or the web server to form the complete URL to a view. When the result of selecting a link or submitting a form takes the user to a new view, the Web browser should be redirected to a canonical location containing a complete view specifier so that the view can be bookmarked.

8.2. Displaying Properties

Properties appear in the user interface in three contexts: in indices, in editors, and as filters. For each type of property, there are several display possibilities. For example, in an index view, a string property may just be printed as a plain string, but in an editor view, that property should be displayed in an editable field.

The display of a property is handled by functions in a displayers module. Each function accepts at least three standard arguments -- the database, class name, and item id -- and returns a chunk of HTML.

Displayer functions are triggered by <display> tags in templates. The call attribute of the tag provides a Python expression for calling the displayer function. The three standard arguments are inserted in front of the arguments given. For example, the occurrence of 

    <display call="plain('status', max=30)">
in a template triggers a call to 
    plain(db, "issue", 13, "status", max=30)
when displaying item 13 in the "issue" class. The displayer functions can accept extra arguments to further specify details about the widgets that should be generated. By defining new displayer functions, the user interface can be highly customized.

Some of the standard displayer functions include:

  • plain: display a String property directly; display a Date property in a specified time zone with an option to omit the time from the date stamp; for a Link or Multilink property, display the key strings of the linked items (or the ids if the linked class has no key property)
  • field: display a property like the plain displayer above, but in a text field to be edited
  • menu: for a Link property, display a menu of the available choices
  • link: for a Link or Multilink property, display the names of the linked items, hyperlinked to the item views on those items
  • count: for a Multilink property, display a count of the number of links in the list
  • reldate: display a Date property in terms of an interval relative to the current date (e.g. "+ 3w", "- 2d").
  • download: show a Link("file") or Multilink("file") property using links that allow you to download files
  • checklist: for a Link or Multilink property, display checkboxes for the available choices to permit filtering

8.3. Index Views

An index view contains two sections: a filter section and an index section. The filter section provides some widgets for selecting which items appear in the index. The index section is a table of items.

8.3.1. Index View Specifiers

An index view specifier looks like this (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

The index view is determined by two parts of the specifier: the layout part and the filter part. The layout part consists of the query parameters that begin with colons, and it determines the way that the properties of selected items are displayed. The filter part consists of all the other query parameters, and it determines the criteria by which items are selected for display.

The filter part is interactively manipulated with the form widgets displayed in the filter section. The layout part is interactively manipulated by clicking on the column headings in the table.

The filter part selects the union of the sets of items with values matching any specified Link properties and the intersection of the sets of items with values matching any specified Multilink properties.

The example specifies an index of "issue" items. Only items with a "status" of either "unread" or "in-progres" or "resolved" are displayed, and only items with "topic" values including both "security" and "ui" are displayed. The items are grouped by priority, arranged in ascending order; and within groups, sorted by activity, arranged in descending order. The filter section shows filters for the "status" and "topic" properties, and the table includes columns for the "title", "status", and "fixer" properties.

Associated with each item class is a default layout specifier. The layout specifier in the above example is the default layout to be provided with the default bug-tracker schema described above in section 4.4.

8.3.2. Filter Section

The template for a filter section provides the filtering widgets at the top of the index view. Fragments enclosed in <property>...</property> tags are included or omitted depending on whether the view specifier requests a filter for a particular property.

Here's a simple example of a filter template. 

<property name=status>
    <display call="checklist('status')">
</property>
<br>
<property name=priority>
    <display call="checklist('priority')">
</property>
<br>
<property name=fixer>
    <display call="menu('fixer')">
</property>

8.3.3. Index Section

The template for an index section describes one row of the index table. Fragments enclosed in <property>...</property> tags are included or omitted depending on whether the view specifier requests a column for a particular property. The table cells should contain <display> tags to display the values of the item's properties.

Here's a simple example of an index template. 

<tr>
    <property name=title>
        <td><display call="plain('title', max=50)"></td>
    </property>
    <property name=status>
        <td><display call="plain('status')"></td>
    </property>
    <property name=fixer>
        <td><display call="plain('fixer')"></td>
    </property>
</tr>

8.3.4. Sorting

String and Date values are sorted in the natural way. Link properties are sorted according to the value of the "order" property on the linked items if it is present; or otherwise on the key string of the linked items; or finally on the item ids. Multilink properties are sorted according to how many links are present.

8.4. Item Views

An item view contains an editor section and a spool section. At the top of an item view, links to superseding and superseded items are always displayed.

8.4.1. Item View Specifiers

An item view specifier is simply the item's designator: 

/patch23

8.4.2. Editor Section

The editor section is generated from a template containing <display> tags to insert the appropriate widgets for editing properties.

Here's an example of a basic editor template. 

<table>
<tr>
    <td colspan=2>
        <display call="field('title', size=60)">
    </td>
</tr>
<tr>
    <td>
        <display call="field('fixer', size=30)">
    </td>
    <td>
        <display call="menu('status')>
    </td>
</tr>
<tr>
    <td>
        <display call="field('nosy', size=30)">
    </td>
    <td>
        <display call="menu('priority')>
    </td>
</tr>
<tr>
    <td colspan=2>
        <display call="note()">
    </td>
</tr>
</table>

As shown in the example, the editor template can also request the display of a "note" field, which is a text area for entering a note to go along with a change.

When a change is submitted, the system automatically generates a message describing the changed properties. The message displays all of the property values on the item and indicates which ones have changed. An example of such a message might be this: 

title: Polly Parrot is dead
priority: critical
status: unread -> in-progress
fixer: (none)
keywords: parrot,plumage,perch,nailed,dead

If a note is given in the "note" field, the note is appended to the description. The message is then added to the item's message spool (thus triggering the standard detector to react by sending out this message to the nosy list).

8.4.3. Spool Section

The spool section lists messages in the item's "messages" property. The index of messages displays the "date", "author", and "summary" properties on the message items, and selecting a message takes you to its content.

9. Deployment Scenarios

The design described above should be general enough to permit the use of Roundup for bug tracking, managing projects, managing patches, or holding discussions. By using items of multiple types, one could deploy a system that maintains requirement specifications, catalogs bugs, and manages submitted patches, where patches could be linked to the bugs and requirements they address.

10. Acknowledgements

My thanks are due to Christy Heyl for reviewing and contributing suggestions to this paper and motivating me to get it done, and to Jesse Vincent, Mark Miller, Christopher Simons, Jeff Dunmall, Wayne Gramlich, and Dean Tribble for their assistance with the first-round submission.

   [Home]       [FAQ]       [License]       [Rules]       [Configure]       [Build]       [Test]       [Track]       [Resources]       [Archives]   

Last modified 2001/04/06 11:50:59.9063 US/Mountain
code-001c16ac87ec/doc/images/classhelper-issue-all.png0000755000000000000000000037372315046233326020670 0ustar 00000000000000PNG  IHDR sRGBgAMA a pHYs%%IR$tEXtSoftwareGreenshot^UIDATx^{tֳqoo՛FKZj* Rl `!ȡRT*b 'II PB+5_Zޟd2ɕk3\sgfa 4hРAC m 4hРA, *q4hРA YThРA 0ѠA 4daPA 4h G 4hАA% 4hР! J 4hРAC84hРA, *q4hРA YRK}E߿S.WN?hE2kРA 4D!8};]c?R0鿛:c¤/8t%坢A 4h!L\qE~G ==+]|x?W3P<8\靨A 4hв!Ĺsf^P3hzؔiOĄNL(\P|}?NנA 4hhX\+x,|~'L*}~{e'Qܢ%,z~s%.^N+t^xW 4hРAC|v ̈Q^}͏s%/FO~O_PLQ9KV{E߹--}DQxY/1 ͣ=5p=9B ʴA6EP/]Bp}tSDqHJ1UܢrHv 73̄*dPBsխ C!D-6kn(Ȯ s MSlx!$4AΕ٦7(x$h#!)B_62F.Nt˳$5k7A'q;!2أh%J`AM$\K/4x!l 9Kbҕ/Κ{Gr__~xG;{u(HD=B' ݟ?•!`#/.)JeF<.^fw f#* d#j3+?GI^̶y ӭ.umۭtCU6k9)ǭKpzsQkou$l/7H1$9b6J{zk^Em\Kzp ;E+B_/Ejke%*)A:ړE8'xfH {O?/q疭[0oys]LK/#[˯w_4{]M=>{yٺ>?e!:.,=v zd2 n館n~ɹJGNwݴA\7Vh)!JCpi`6HdYO52Av/6vʡ >x,ynmhDp&C^G)|.'<ꥻ9OܒLb><Q q09=aI87vJFJHS@iwV΍ZHifZ*mK[~vX#/(^fóWpnz^D4|{J tNۯF?}sld٢)8G$?ʛӈy ͫ&,*[乒?REH@ 9xy㳟 FU0%])o]h2أ޹ 6LR}8\ n Cu7!4Hl{v@S%Q"BuvJDz!Azb9< A#xR]K-+ׇH烛 $Xd1|n1-w 6,`{J2Ox}lf t4E*[8ӟSO=iPOn|ߌI(q.]U+d󊗭~rȦ]$) n&\%$[%g\R%_s)*dIȐt fN]AaO""gf{q{bBF>6H(Kw"=A%6:Ф`k `iFBc6UZ2|YᙩlXl^IpOX x2xfܼi׍Et_4wNս;7w $LȢWqJ~b I3- Q}E2'A%N+ إ_-* 4hȦZ\TrH 4hРBG 4hР84hРA, *q4hРA YThРA 0ѠA 4daPA 4h G 4hАA% 4hР! J 4hРAC84hРA, 9*(d9UEQE:T((QEQ% Q((JGQEQ,D%((YJEQEQK.+я~(yiij:1EQEQZ!z+oĹK^}FȤW^y%g7(5m=-۩Sō g?0eEQE2枖ܹ,LYEō(d1Mѧ8^zi^^)A9~hFQEQf8MoJLS((9#Ld|*H#X-EQEi#4ᦟT\~F$[nw} fΜ!Cb%M((\vHDի?,++ݻɗJU(9?#ٳgF$!9'@~L)t9e,┗-Q+q~4`\6ͩ)meMP+Ks6>1!W_+b$8dvhڧ~i-3ɫM,ґ8M=REQ6@dK=vXϞ=MR*NوǎkӱcGSe*,(fM:uq e 36-AbgضwיN:a5$8}ūeKXGGvo"21~xcX?x)+_K_QsT5 k6/]bb3cAYNݏu".1S/wORYY9W]yt|嬩3{~H8w:.aS371aEL}y"Oސ]hW(HK/Ȑݺu{c[v5jM7dN=tɰ}ݻcԗ=GFmWN{T]~)~䗟܎P[Yt͸-Y/C~ؗ'u2˯7]<֑EQp8\yF?ĶZ{^{M#e͚5=z0|S((ù8W_}#>|K/dRYYvdܠ[8(7V~#Iӭ[!C?~̙'Nկ~E9qSuUQEQӄ~RU@i~WܢGQEQTZ$//ho vJU(( !L^ڥKP2rEQEQGܹ)qEo((J}Z.]8AQ\QEQƹā+2.͛ z;GQEQs7@]v~/[q(Jе^i+9ikYU/+f}NN+jE$~}J'9k(ȓ+LLQZ84)$N%{OR1Y$ *9.i5U;S.siũ\WP%yQLlߐZ kᢞwkxzݽ^%G85wB-Sj2TLJ%BQyhU;ia;' )[7坦G!%N1몾6 8;+E7P85kLy=.NJ%2Qyĩx!Oɹb8D>*F.*2b}b͌Y)?kݛ@1]%ZQyĉߍHu+@zﲂ!ymhgfE\#n0֡G*qEi#q޳BCʽK Ş$jx>_\]5GQ!:goyN鉬|0\w^L4<+)[5i姅1ɻ8ֿG%T(ufEBszMl/{,Uwe"i}ha%}b?|SpHIgo.NYQg3ȣG *qEiҖ85E8U%v4~\bBU;/Ĩ*TesKTj$Y.e^7nePA/8nsq!K%B0]OKwqHGQ!SwSglKn+ P`^c`{QG=_QEzm(JЅ^i+(Jе^i+jkAn9Ne뎛se:ʹB%(C Ssv9~ZP~&r^"w쵕%grne$N\01Z ISGi.T(j]I #%wїK˷>?WtҮ][Kg<|ݩq~x?/*+/'âS]f=T^>w!s9jwy99ǯ"`L %Nj׾uj=3rqeחi.AU$A%(C8erh{uGԿ{Æ U˪RXJ"=8^z"rĩ)C >Wm-ٮޫ0rDD }u Zګ䈉vpHiLRMvw-Ske12| Ie.)p;ZAUPXT/%ìGIJEQps{gr]Ѯ{~Y{"eJvK㉲_HBK`Wj%R͎N.NU]; MtP _K;^Q/\F8k<dk*q$QyH%qbT\{QvݧV؍/L)/g#ρĉk8]/?gi=$Xɋ qz7i5Uw͜8W^L$N;=KZ3{LtJ% *qEiґ8qj=::Lpޭ[_WU,iށm:SQZ>3+j>8=sbf.ېEKH5ʈǻo(Q(J*qv̴"uU^u[hdJ.~]E6]9sX%#ce|Z#Ԕehj.WG%(C)43 A^"Q%8GJ󻑷Kv~)%N GxVJ>wq]Hy fb^۶e6wqFGQ!i_^eKxޖXZgBuCQ<_rIm/qbT(b9vIǿQ.Ug+}&JpιU]*Ծ1W0K$8IFpT(<8lK*6 S;G#WTOYyO_W]/qܛC ύ]t _^'q XsͦX~uwqgfe1ٮñ߰Ylnur YqԮh].I8!5])>]@QGQ!āvvTĕG򂟶_y9\SMθЮux1tל_ev/FuUK޸ؒΩ+ٽ_ފma.K uqK΍bձ_x6;xvW3nb_oāC~@,Cؕ6JEQ%lT5U;J u\~vnك;kgnG_isr[@sc*秄^{bȍTU+j״Vw' (kU=](84G9dB_Uz]zͭz';ԢGQA%N }Uin-/__2C84*qZ,Y迮*]9r:PJ*JT(pqi^]GQEIA8yfi7|U`5KeY$N\8*i2SUҧ[T((~PU1 3{ *:ƮfJȠGQE 'Sspѐ˳ĉ *qEQp-q'ޕ_VibYMsJ%eUy=sɥ塡.d[^TxO8a"8OH}T((4JT٧)nTm-{q!˫_b.le)zyb:͈ۭ'ͻ`Y<#z[X^O{:rtuhenOL('(aLɺ %NM!]ܫp_Ik 7t|yXjimHaYy>]jһbݺdrXR;\Swkrrn_P͝;~;OL" LJEQ%K#r/ SS1;d:Sg\Ž,t/'(㻘<xMZ1vY7"{mbrX](#%p$ ZVnDm=bs\5IG-5NMPujp5xMDճp,R$HH=UtHb}PUUUo]tE޽$r/&IuP(03sr剽&GM\jQCDԔ1\PqsSf]vB.")vw?{v̼p]9LRxusS^ςձoukc)5Ե'qvF~Ynĭ8$0~AR߀JEQ%Iv=owG*ӵ7<]gnwD嗛sUqͬ}2<~Zu頞0\F; LNXAc1%4O 4%N g4&b\eȘ噠!|;AÉP(ӈ׍.}H{-y}${g^Q\)^ufxثq<~8}A>ةRd&h wWW.!K8XUmŹZOQE 's˩!IgZOQE %Nղ^I^4~t(NKOlӾעgVܶM:z(J8/q}J*IO7(xPU0{YFQ9[+ NQEQү+(T(($Nrn+IDU%л8(d!*qEQEBT((QEQ% Q((JDK/ RΝ;g̘a~B錢(َJlJ$A`̙u+U9FE0{=Dߨ1cF7]#Kd5f;hT}f8> :b(JVxaJ#pTG%( ][ #pTD/>*qEi]"b'z8Q(JB8a+zNj 3TJhKwXGQFĩ *q"N%Ο~gU(⠋xaJڠ'QuxaJڠ'QuxaNsK6۷S߮ϓ 1CsuJeG'ËS{8w/Nt↷' Y%N}ғ8~q^~ /y"~Ê%~˜]n{ƆɵoqqKv~dOXDŽM&=)*qxaNsJ VsԣIޗmOR'Dj9.uhhncUSHv|O,}iUєgR~???cK/cEoO~oI=fճ~2=f?ğd n8}g}8FE0%U'N69/&>O(BR›'H`J)qec˪#'gdAl}FzXg⏙Ǐy{ ]HAT)Df8u¹+S/>rՊT%uEԝhePM: !'}Z1a̎x-qYx<T(D|PC^wMPL<$~eVXIpJ(ӭl-)^*RMu?r;?<%H}JEQxaNnX %V %I1Td= 8?ܐ:I9w$\mU*qE xaNJtE819=QdGU*qJMcݫRWMsCafP:Q%.-8-"qld/$@iJDK{R'4Z=aL2EoxuNY5)|gcϡ^Iuz 8E0$NSuVkjW08a`Rq-q^}uoy_z~y&ή +T"qdGQF4]1*S{-JZL$]UDKDLQ}?ly&#j>4qiK^ZҪ ?lݫ"S^]}XʨgwqE"b:#zU)?C=>Ƞ'}G%ND9W |vOuq}W!~`Q(m][ #pZ] B|aJiQ6.-8*qQS8.to1Q`JQuxaJ#pTG%( ][ #pTD/>*qEi]"b'z8Q(JB8 FĩJEQZo.R* gƌ @GLEjto1TD3TJ;wΜ9UO钢(Y.-cJq0cƌ[-4^tWEQ% IsWij`⊢D3QE..((YJEQEQ8(d!9=EQEQ8(d!*qEQEB]EQEQ8(d!*qEQEBT((QEQ% Q((JGQEQ,D%((YJEQEQ8(d!*qEQEBT((QEQ% Q((JGQEQ,D%((YJEQEQ8(d!*qEQEBT((QEQ% Q((JGQEQ,D%((YJEQEQ8(d!*qEQEBT((QEQ% Q((JGQEQ,D%((YJEQEQ8(d!*qEQEBT((dٴiӰanS?_*J(;w1cƃxˬ {$m۶}(- ~*GIv3g;Պxc68oH!*x$f7JtI㝭8v[%;% >[%;[?*q\GIJ%jĉ"*qZL*%UӇt^;{݇L/ILuECnҞT&rQϸXz6 _W|W.-msLjܺPD 8QD%NvVfFl*I/+ z.7t-1 *4SspY~v9 ),[Y]c1UGUoj%~]]>KvF8JPETdlffDU4;{~ׂյmQ]p|bﹸ{R琲݋/4{g^)mH̓J%jĉ"*q8-ޢٔdU$5c%&i<5gLSOx}M5 ƢJ%jĉ"*q8b<ÐSPa1 ssK[8z )w:j&ײzlPc$&iT(QC%NQKU * =⚊+H T|YqdikzE}-UYtC@7.NJ%jĉ"*qoכX&eF4.q,p"$^99k1k'J ſHӾEMJNMu%bߗU0y$W]9}ojNN~뺍'L=&4*qJ^rgz٤6QfD|jwt@T sԔv?/Q_W])|z̞qSXH^%M!YzQg&ר3>M*qJ&ߍKn[i5QfDbFV/qbϤgbqCMtOL`jv^.OT({3ώG|}/Aĉ"*q2D[/ƕMη=pJk>5(3c>9rǜUZĩew!Q=q} uW7 dgftQuws`TD8Z{Pc?"I8ˆzboLg8o╃Fr&&4r']nֲ#^ E 8MG:6Tĉ"*q2J93z^Sd7rT{@DL2Ჷ†A8_g4|M7=v[M8MJA%NQ-*3ƱQ3*qZCESi{9$wqo۽̾߆T͡VJ&@T5)*qJ&%^7zEĊ'_̧RNi'o&ʒ'흙Q {/&7#%wu+L:Im }'i:K^qN1EV'qjvto.P)7cәqSv/&712pݡʊe{Gwbt6~i'iz[n;:}Y:uꔓ_>b5)_o&jqiڊx/^_ZLQ8_v=YarC%P?oR[ Ǐ_z_3qĉ2FdF}t2T0ȿ~zo]II7{o6l1| :tO>(fhZho͂jX\\Ĺ4شi"D"ɓ'ю&/2LQDbŊ 7%:;3-;8HɌt%Nee%&͛?4w}cǎ[l1gwy,X@D7vJ(TرěVZu!UUUptt鵻S"-Q$_Ed(q?q%NmفFcDJf+q q>OgHx'XwX}L7,/$]uUđ=?kU8r馛n .B8$-$_UXi4FdFt%NMM \=#\p[oEE{Ǿk+O?h# *mG7nO(3Eb:gϞ>}$|Lj9-m矓Uc֬YH ٷoȈΝ;o߾'N>}5_bPh)1'.ʄ2 Ilk( ;HD⋒#G5gϦ#,u(ٍ}77oIxH9}JJJzIh;yyy9g2t4]8p}M2S0J1g}6~x;vT!g3˖-ӦMCUVJq͋m ؎;lEa lMo] ;A7`urebСCRpVDq*+i)'O'Yjֲn3bFq_|9,Vt9VA"B,Pp1&Z K{qyKgHpber!:ald~ Y>OX Ta2ٯ3MxI=y S ~ƍXG ' inlقaR`Νh1I +J3gΰY5ce?(f_B9YM$qv,**կ~ /k\jvuvP08ѣGz 5R4< (rbYL.]J~F[na6zh_V:őǦdc+%P[%7'>î7/9SA8xGei8ԋb7Ǐ"N)C|,z1o<4b'j OBh[;Cqx2? (mѢEׯmf̘45`L)#ᓑyyy2Fٙ9ʅ˼J|pw.$[īZ`oZsi g(*Ν;9^y~m kg8\襗^toĶ֭+l >#oCV96cZeaah1#)A&H?b 1L^IީS1csjbgрI&*#tx3g#a󓨔i@\;DQ(Ŋ1,+,4 G;C x0ސ2J A:0qzmjaqar!fʕ+.2k[Ki *rV-7eLwcݻcg:k.ISXI СC\β IX &koGb)ܚՙ){3w6"(,?Y >8ƥ̙#7BU_A(^n#J커ؾ;'xWU&qʩS?6))2x#>)).!]14,??ߎ>KKKݫJ)΅K Bc<ޱcH4=`))SLq57z^<Ii6Ӎˍ#f"pj6{S#}cF#R`M-&5@%הhj. YjH(pPw\r.:tذa$qGw"no#BK`ZV[RWѿo\$-߫+!r?)˔^]F) w5a1\6P#\\>,]w&^XO~&ӹ J2HR"ϼ඙iM%hI=LH߼rjt]v9P#زe Ӑ(A߈p A^r@wD"PRDZ>v⑬ᆢ X=*XZ< 'ꙅ5 YrOBUTTXxv8\㇗BAz[ o踧?P۞#@4\ 6jqM1)0>X}"-qKOG>` #رcV"9=BNzf8B6?#R8|W^)]lu^] S2w0ś&YenôdrJ W6?ʂkUg1ZJZĘymT; ,%@0ū"MO( Q\w hZdλކ;y<#$>}zv.\ ˜ z%jMe`7[M 4䡇JHQ2bA JX;d{졜Ar<㻭bҵ6l3/xmF~m޼[nCu)*17n]fX1 JdJٹ) v#Y= b^pp"pWK@S0 $aC u&zlBH܇+--G T$N^.fOB ]ڵ5~H9.z qqP[{ 1B4`g4MH21jiM磏>b]ꪫmvFG,)W&ȂNz sxnG{!>|tѣGo6yC2'C \Mx;ee4@Vb`:ɞk{0UPDڶV^|ydkA҆mx͌%ܠ%@0%Xn^D1QiN>g8g퍑#GZF_\) ?aO=',^C %oZS^r(K>.^G/#c D[{u -фCM EBam[RΣ B]nQ's!XZHihbDJf6l>WRRbuhp8#&ȂNzd06n(Y\|^zq1ѱcDž {r]uw0 %E`Փo$tqo:,3S3|Ż.u*k(qP^{3HU^ZJZĘy6۷C-)*,eW01>UDŽ/'({ЎBJxOS n/Ϫ@.Q-0SBpn(w]zgHg4 BF 0^OBʅ˂BBI#V> qfz .OwX:.!(!nQAtn`i,\cFDɔ!qdvCzۡ/<69"I_nwܫ#/ϭ]D Dȣ(vd\YYY<Gg͚EuCn9p̙3jJKeJYY"h0E.-vkA`f&[;(rW(gq}XI|k隕8w„ 2},ܽ‘m3/ |Z},Acwh@L_I۔p>I ۷oGVIDRܷq9DYIqI唆b.t>C2t| yW㺄,\dg+q\&ev<.eCqh5ce;S{QB ]Q")˔#`[* Y XNAaT1J: 448 z:tx_r-\j gƌv69:4iڴiد 2q#RVZ%bGTTTȕ4_7x#Wl=ӧijWrs|˓-EիW.i0p@4)It?Y< Ǎ7zh pݺu۶mvhTdw!Cp"~hz]+ƶK+7oe˖02ӌ 6;n2c|`ʕ؇͛eh)\bb9ܹ3^Z8emF` !r!_,g?`x ٤I؟h0bM~[)ToP $]:&NHۘ&tsҥo(sH }G7|pرcXSp/%¶%BU@~yH42)!\~vosb2ME8'NGXLQI$%!"x;0}ja\ױc++VPeuWi'X.Z~=W|MJ+LF ˳y3ݘ$6xyiabؿ1ְ'qO9)S p刢h}0|&Ev#0W9FK5JZ.xS#dP89r$P2&]S#S4^O$Fa.a8ļ2ϡ@(ָ;i$)3{X$dڙ_wکg1OTmơabanq\HX&x2(ѣ7K(QjvM ?'D{|bqXԩSV,)ٳ'Lج,.N(9;B[ l9f@#,YbvY *` ;/up.2⥸R yQ .K (WrzRg -*ź9*fgUMC/.lf d>~W;p3F6Z(%@sz(d 8=e{#F4GU)e-u"tL…ƌC(C FC90K#¶oɓ'K8dx9sT&] J4=|q"k2L)Qo毉'J!?RlU)e!dZPu;HW !_~y„ ,_~9YI\nݺQ.-̙m#[s%j"m?xҤI)%Ҳ4]Jϟ϶m6Y|Plyyyi>iY<Ӵr1"%3 q`3f@脃~Bi\$M6M _Z\p1'v8xCBvӧO;6>())N49g׮]k-)0k}"e䙅 UmswRwy睢svWkرcsm)L&vڮ]gA9xApwJ3,+('Z0E>}qpM6M0ams޽e_~'(#/c=eV֟%K=~+|W<'Z-x\iu*q"uÆ HyGSN,1m}%);=:eyߖ[om-?le `DJfQEQ%Z*qEQEFdJEQEQ)GQEQhaDJf$Nu!=oiLk"EQEi;=X((*qEQEFdJEQEQ)GQEQhaDJfQEQ%Z*qEQEFdJEQEQ)GQEQhaDJfQEQ%Z 8&n4͹((ibDJf+q7I3ʔ^=:y#FH4'˞~&p̙q]wu~!ѯjÆ zGP曊,[$#GLl4Y61"%3ҕ8 鯙25*4?jٿnnn7tSN}]Z+_x1-(͌JY]v۷(7Ǐ^/י8TDDɔt%'\ }<ʦ<ɔ8DҪO>,@i~ԅr(a,(S\\hMI&Nљ᯽څ^'%Ӝ*q<۸+ƈh2sߋ&'|.%8q"_Bo;~ƍ;Liצ{ӧyסCzmlD;vHBΒ؁ڴi_|AoYjU^M߼ؖbXzر6 P&d ǂO행M8CI!m$b[eũl_lSUPPЯ_?۰t/.pYz5Gqd (Vl'L-/`5k ˑCAJ4L&5\3|&#)0g8\tja pwoܸ1^2h!͜&H_n˖-(vܙaN3jНisbwn-ZgYE UP$ێEEEկ^xe\jvua^NfgbJ a^Vs!%^%В |zKS8cDT!0_vɡr%H!4湳7LBKP-,.LN9L^r|`e@xmk)MTAEnݪkjjܻ2;hݱ3ݵk)n s!.XgY$E5ݷ#HnMIy Sp뽙xberJ]ğD,e p9s`v>XH*5E mD}ۗp >$N_]9uy&%EFo'%%!1pgzii)#[oQ)΅K Bc<ޱcH4=`))SLq57z^<Ii6Ӎˍ#f"pj6{S#}cF#R2۳ZSB JCeJs!ڝ$ 薌+y$J.Q uhYmIC^Gq* F|)v,SzZ840͸Iv;j+ˇ%"kDmnLӧsEemeEleym3<)JВ^{ Uyi FحvsʡFeVmFP4}#=B4&xq{!u z@ Kj a fwG..`alcj/g(V*{4df= 9TQQap^ z 3Ϙx qqO1'rK=!F`i l:}cF(0zV7><{ބK(l$>R+x"woTAE$QǛ\n?8*#4)_>|+.:x)ekyWh!ɼS:k׮ŻvrRB\4t!yA-%)n^{B,;7X:McF#R21L3bX^ nh)H3 q]Ȃ6QYG>ɜnϺxu%ě)˔^x3hk${En{RD&?x:t9h|U^ZJZzy63ӧO˓p`ByDab: oo9ֲ5:e48e'gDArM rBR iÇqŋedpwv /'N7m&l?o( kCݒrrv=F BJcF#R21h+J?}{be$W_.Oo7"w@pG7v\0y87g٫W/.&:vpB{Q&zM.MeJ] Sjbaqo:C{5I 8(k}$*/t- -bL< nB!`p>=z- IC`[eqLzBȏ} (1= Bz@ Kj ;%"q5=MF:4h:5j-HpYPH(iJa![o]pwֆKbg$[&Hyd=K>[C,ޛl)RKD4t͕8[n1P555#G$j _}UT2Ν;{U!B4&`{Ĥ(p.M wNQkON@ 0}vzdDI$}7|]J唆b.t~Bfb^8O8hp5KE@Vm5\:0Q4(>}:V1~-6̝)ǽq(!2I &^ 1ҐU Je)xC[qE~DȏRr-~W(Tq\dڴiد 2q#RVZ%bGTTTȕ4СÍ7_.}ӧijWrs&N^^\l,^:w3D2%?)t'K'P`qqqFM\[n۶mts׮]80N9dNd?SO+3u%]^xvۗ-[FL36l@XɌ+WVWWc7o E؟EXN;w|ko9zp1یmB~BX~f5I&?`ŚSߠ@6*I:`'Nm3f̠K.o~C9;w.DR>گ_ÇKǎ˜+~)-ǵ-!>Cb.II  ss\'ȀBsb2ME8'NGXLQI$%!"x;1а"vpwb L*dUK7E!ۛo4gf1 iIH9l ca%NrSL LI.xE q` L!F`r5j\FȠps ٷ"H\dJF'ap\҂czd(qLjIn@(m+ѝwrw ^{5y I 3Nwکg1OTmơa%=lo>`9 ^1B6zqFt %pH, ,bbԩ>X\h/>uuGvϞ=_=Fffd(uq"GٱַX8dˑ6z Hg7#pNj@)tb()¹VXȤAoRJ)L߼\3,m,\AʽG\Λ7Ϻ9*fgUMC/.lf d>~W;p3F6Z(%@sz(ey.^{뛒]v_b5d9n oPQqq196mB$H8y֭[M$_|FvLQDbŊFKa\rI8Ȼ?۲+ÈHWTVV"Y>li0o޼Hf|=z1e̙oDK.=zM}ܢ""F`%ѱcC46lXtf8Z [K]S"-Q$_Ed(q?q%NmفFcDJf+q q>OgHf07n&o{^ysT`EM8F^z eo xeC޴?:3^ UDDt|U%Ngbw`X$dV:uoܑ~@&!ȂJmGT׸q?|'hY6ݳgO>}[:txꩧܮqo9-m&X5f͚ʼnd}ɉܹs{ >\pӧO(k Ilk( ;Hꪫ_|EIOȑ#GFFSٳgqx= 7p|͛z)"Ra={*#;?Cln:t(C)C]L)G HŘ>?~<ю;_+v6m_|Az[VZ*yc7/)>c0n@QXGp[z B|,djklQ:tH n *(Neb" ɓd޽Ydی1gܗ/_N/h#UPPЯ_?۰t/.ppd (Vl'L-/`5k ˑCAJ4L&5\3|&#)0g8\tja pwoܸFi!͜&H_t K;ẅF5NdXS*;;K} ($qv,**կ~ /k\jvuCxR@pGer"c=fG}Urss}]9J,K.%?#r-0v֍Va(ֵ?2,-QM8qbJ,ѣG"/+őǦKYt0/ڈǭzJ7/9SA8TVVQVIw<2-[ԋb7Ǐ"N)C|,z1o<5b'j OBh[;Cqx2? (mѢEׯmf̘45`L)#ᓑyyy2Fٙ9:lذ{ｗy@\HpWsG d\^Zy.MS|ٹs' 5 v۶mc@5|3G.TK/P+8Ç΍7ވm׭[W|O>#P{*ǦCuL+5,;;x#Л 2f1"%3J4,-dΒ4@;&M$0s< i'DLJ/Fu)X",+ ^˲"QB#yv(A a4ϝ!ed0dJ5Ņ)+W컬m-ITm[uMM{W\^ƴQhݱ3ݵk)n #JueHRz\0Y};Kt{f@0{=6}zo.^F}|@岒e'p8sYa`\zΜ9!>r BQBtQ`%%9E­D0WW=cIIIIq rav66w'^ZZʈp;B.1C4!xǎTz/#r\p*lTL2֔yDzO#P$EjL7:.7rB6 R©QMMHɌ8\nzx [eȬv' HED•< Gq%r(:!@أ߸T#H~[WWB;R)vLf ӌK|.d,Kx.뮻`2km  !_]kÆ Ν;^d,`kBCq C!6t1,ℶ(e=Ҽs 4f42%݂ɿ~z+ @nBzgO{"#sޝ$6ѐ/Snc,iг-Vob,Sz9@V!8XAz>L]*-d)Mbɏٳr a h!ɼS:]v)E^B!}:<rv=!F,\L1) 1[ކ;y<#=w?>ѣv!! &A2Lf xu=ׂD}zSD&?ú|:4*/t- -b=< nӧKAKz`J !ܼuc01|p#GlHSlžzq{a!OTY.J޴ ! !(Pf>|G]x1joc D^xx8q¾iK4',eS}CQwX:(P[ 7B4\.xR3^ⰍT$ Euh`JⲡȂ6{ظq|/O>d^ر… =F;"7Y7R)vLf xƵw]Tݻ$5PZWz ]KiC6<}аyȡ%@0%X%ܼ=z؁L!0Xt=\aa>fڟA^U](b)\^-AQ[`0W#xv9Pd#*zv( h NeMʅ˂BBIۗ'qX3{*kC%d%D-*n{,= bh(Һ% (8|f2w/\RNx=r{wtn^q}nڵL$RhFEѩx^Κ5n9p̙3jJKeJYŪ Sʚ?kRJ97%Q\-k[K׬&L9o g13-AF< %ġN6ϗh敮g֭4A~rJ4ٹs'{}*XH bЀe) | jI (AFoN:OZB.4s[n}'Nλ%dᢏ 5\:0Q4(>}:V1~-6̝)ǽq(!℮(`eJ-r,\pF0T*MDdH#M< 8ȏRr-cs3sjVny(l,**r6i E.2m4R7"eժUL!}TKEEi֡Co+6L]zڧO66+iɹ\Q]N^"KիC|W޹8p JKXBʔq_N) ,..7nѣ)+um۶nڵ QG) ‰Lǣuz)veFY2إQ~ؕw~˖-ad6lwd ʕ+͛7S1"_,;wƩY _La W.lXO`!4i g{L |٨0&X1/6qD6c t7߹sby܌A$27|pرcXSp/%¶%BU@~yH42)!\~& (;'f{!T#{x>ɾxQ%>tAR\Bb(2s.ס*>WXAQi֝W_*bI&[h=܃_1:d{7C+zLS)Hay6oӰ//0L7V9)d vA{7bh !s:n&mP:&|\cƌG!!wa7xɓ}L29*.v%C>85H&n7?Jf)6*v Nc2Xv:؝`DJf+qIjYp!y'L_֭[BbΜ9, of=".YL%@4s%j"m?xҤI)%Ҳ4]Jϟ϶m6Y|Plyyyucd$N+Sl9ƈhā۷Ϙ1 /e Ap4m4.w3khqnہ %R4]O>=v؄q9g׮]k-)0k}"e䙅 UmswRwy睢"nfرcsms^y]׮]۵kנ6B<3('0HE&S2eY9wF8т$/ӧÇoڴi„ ˗/ol,[<=Ey{-[,Yd \Q櫯zXq[qqM;;Oͧ_/`~(l^ o6 Pi-D$H8y֭[M$_|E]S&$-Q$XGؿ%\$ ĶJ0"%3ҕ8͛7Hpm"jѣ7+WDH믿2e +ydɒӧOKCe!c9F@hFǎ:dҠjذaљnҥ/kzK9IW7J?O\F*fb[v`C07n4׿e>ő^(w% .x뭷LȂjȚhRbz^{ /TAAiNU8Qm܁FcDJfnA]W_}#GL<3<ӧO?,(qvOǍw}9" 1kϞ=4СSO=v~;Giqn6i<ƬY8 o>9;wn߾}O8ӿk9 B@ MdeRd{Ҥw65q$^uU/'A5jbuϞ=1M)vC_=p)OIIIϞ=iy~!6///,R> 8p}M2S0J1g}6~x;vT!gW@ ?mڴ/Z*?TxǦo^lK1,=va ( k`h2xbAA۟W-pB+6H7Ŷ&Sپ]٦HH9y$>ٻwSNY1b#θ/_^Gy.*HDȐ ;Ƥ|\_~a^8]/zj .>PO0%[_25Hzk֬ ˑCAJ4L&5\3|&#)0g8\tja pwoܸ1^2h!͜&H_n˖-(vܙaN3jНü%X}% `⍂P$ێEEEկ^xe\jvu,D[hq3f`+`M)SJrdC^^ekv&$p6{ea%>P;-\\Q-Y`7l43FNR eΝ /ǃ<?03n۶1qpPK/BQ\;7x#]n^aSO>B@!1װL@oj4ȘĈ۵kE0Ù3g^y.Af((fY$pxۤIvfǛ8}%Hʴ[ QFl)X",+ ^k;ӳ2Df.bvJBXH*5E mD}ۗp >$N_]9uy&%EFo'%%!1pgzii)#nKv.,\b:%hC`9;^FGT٨;OI2e;)ǽ(駟FHN#nt\nĥm4Sٛ3 qZ[`zߗyh4{ ݉+y$J.Q.CjKlhoRյ{u%DN'ekx3h5ӌK|.dF.|X:.MvA'?|< ҵ6l3/m|G#eS ZkS*7/-\ڨ5k׮UFeVmFP4}#=B4&xq{!uݑ(%>Gd]7]Qƒ^8Q,QTh%͐{r/'? VC!n:ϣ "0Dn',=$Z\SohbDJfdɃ3g<0%ӫVܹ3f͚%d!s'  wtx3M!GyH)_>|+.:x)ekojfufwA Ӓi(q,\8p+ AV Ťk)mhcg^"}ŵxUi^'OrٱcGk:ig!Ec!<[aIDB (x}D03H)ɺn'xNhY=ܯJ.Nµakի8F())k(? (18kCǽ"Nh[ ,;7X:McF,9YqUU9L6I9x 3 2IAo< jlv.rkcɜ z%jMeJ6SjBX =P{ir 2&Qvg{۳g 4VmxEgyk3ԭ[7O:HǼ§}ڵ4Ún˖-|R?C^)++H]H`O3+<|<ܣ> )6xICq!7j(7WZZ*Q1F H杼\̞j@Ё]v-..޵kkr\/ڧ#j.(Iqkb`i޹i3Y%qgq={TdAz܎,C}GvmNdNzg]Iob,3Sj"p|pdϵȍqOSD&?x:t9h|U^ZJZzy63ӧO˓p`ByDab: oo9ֲ5:uJҥ) ?aO=',^C %9e!Xo)GB4Du8}/\ /ĉM[ 8a9.,}CQwX:(P[ 7B4\.xR3&q4x@Aw@hs;?<[ ƍ3˓O>٫W/.&:vpB{Q#'dItJYڵ0ś&.vAS9w^@"k|A2HR"ƴϼy߾},4lr(hI=L Va 7/SGvab:)ӽ}lL/'({ЎBJxOS n/Ϫ@.Q-0SBpn(WH޳d3 ASY `_ۂ F? }^9.o\?˵@!6t]BQB ݢn's!X\+,!ƌ&q)Y%qu.A,X^8p`CNx=r{wtn^q}nڵL$RP0hyEKJJy}8:k,s3gδI+-NvLYő%RS⮪n0ff(}E/roY-??_f%0ayko<ɞl"5g^p,l%\8v\Ki ?em }_sMLJ`Ȱ:A=퐁Hm*‘=qBd_^;u6Y0m7N0` X3)dG7nDPWT͢!6gbԩ>X\h/>u{@62&}DcַX8dˑ6z Hgb%Fjw5]/X Z.c!Kq+@<3}2+\6P \Λ7Ϻ9*fgUM,ҙB\vǻnFFw;723uT {={lt08NX‡,``Ѡr#F h,R8ff c.bK(C FC90+#¶oɓ'K8dx9sT&] J4=|q"k2L)Qo毉'J!?RlU)e!dZPu;HWY"?hBaP=} .y[;ʅŜ9sXްzD\xK~a>I&5U6yhΟ?mo۶mVb|^Ӳxia)6qcDJf+q>Q%MH6mhmT#5bhƌfސP"EcǎMJJJ298v7o^l)HɌH8x-[6޿i I߾}2e\WE$NKzwЗ&V9vܹs{hJ3]k׮AmygPN&a8 >L!$FɐI\\qSVVuÇ&LX|yۜ`wfׯ @Q qRgɒ%G_2_} a-**kneڴi׿@Qo6 8ii&DD'OnݺDR_ߵ0EiB5iNR+-q.V'qwwG&eVh IWTVV"Y>li0o޼Hf|=zƈEqO>A؞>}3Ќ;:t$AUUհaâ31ҥK_Х׮)JSOs238ӟtiUĶJ1"%3ҕ8_8|3qL$37tS4"/..tEEE&1&T޴?:3^ UDDt|U%Ngbw` qĉP`V'Og?c2dHEEE-%DWo;~ƍ;b|Uiצ{ӧyסCzGYovvm9X5f͚ʼnd}ɉbܹ}=q.ӧr1(ДٻwSNY1b#θ/_^Gy.*HDȐ ;Ƥ|\_~a^8]/"o) .>PO0%[_25Hzk֬srP ~5̟?hʀ+L:#Z\ŝ7nb8Zt3$1C)۲e %J;wfDXSAƌt'sZ-Z*gY ks.c ;Iܷ~_ 8p]&OlK=z)ʉ=" iVyFiXӥK[ rb=(j2deQk/^ w}5*7d#(߭_k7mDf$رc)9Dܫp%`72FI>v֍Va(ֵ?2,-QMA4|aKoKGfyݿ?,l?6Ŏ ˢyF@u?nD[ܔTFH߼+N*,Zb߾gd}s8*#HXLhԋb7Ǐ"N)C|,z1o<4b'j OBh[;Cqx2? (g͌3f&)%xt9|25Mw5;S^8G v2(ܝ .jy%,Xo\# sNA￟km kg8\襗^b (.WpÇӝoۮ[)'|Y!FUMVDkXvwF&75dbDJfz#c|! 䐅o:n4@3,p8J4i4候f8.FB%*e-QΜ9C7bŊxأ7V F!2s`GpFR&Qi!XSƧ&b&\R>{ SL&Q"n555]qyӝ{ؙ΀ڵKRV7BR9tk,C"X cu3)8zl]x2A9e%.Opº_Wĥ̙c!/ E/D ]Rl_Z+*@8 z~uԩSaY.Jokcs 饥8\Y tJܹիe-A0BII5\C!!]DǡwX:GqB[2Hh`i޹i3`iy^PP`BB u"s+!mѐ% 6p@OOdN1jMeJ6SV`y衇>3IwLXѧ4mmϞ=3h T[g|UYL҆mxȯ͛7w ;-"wr1{Awڵx׮]CqPk;?<ܢ$ŭkOy ѣv!!J7S\F) ZA`e`:ɞk{02&Qv^|ydkA҆mx͌%ܠ%@0%Xn^D1QiN>g8g퍑#GZF_\) ?aO=',^C %oZS^r(K>.^G/#c D^xx8q¾iK4',DžUԾ(P; wKyZ-JR!X{. 3x5wJn E6:⮫Rl7fРAT֨׶ eA!dk+yBj8W[ouލ|wX:.!(!nQAtn`i,\cFDɔ,LiӧOEI#I_nwwnvϑwPiL$RP0hyEKJJy}8:k,vˁfΜiWWZ2,Sz=h0E.-n$s;]3FJ97%Q\-k[K׬&L9o g13-AF< ɂ%ġN6%XiWJ[c#G*^*dΝ=Ѫc!0CbRJ8Mڦ;''Mb'v߾};=J"$⾍j%rJC1ufc!31Mw /'N`w5KE@Vm5\:0Q4(DB#j4ޯaÆ;7n%DP )P!FTApჂPc41"%3ҕ8Lu\hiЄA~[n.<\'Y"%?(GZHEMF 7"eժUL!}T ȕ4СÍ7_.=ӧijWrs&N^^\l,^:w3d@i KCH:N R(xܸqG@׭[m6k.FuMvd8 ?~xSO=Ůԕ vic{ؕCo_l #3ذac&3gV\Y]]}n޼Y&ab9ܹ󭵿)ׯhl3S b9%X&MDk{L |٨0&t̋M8͘1n.]7 wܹX7cI>h~.U;v c dײ_ضXH0 "Dam&>:A=퐁Hm*‘=qBd_.lozʕ\rIII|.**kneڴi׿@Qo6 )..n۴i"D"ɓ'nj"/?4!Ao4')}uŊ^o߿I@}џmفaDJf+q+7o6,|+~Dɓ?X" RQQѠGK ŕ8ێ>nܸ?>ϬYQ`{ӧyסCzGYovvm9X5f͚ʼnd}ɉܹʢk / / HӐCl0F@<|D(C9x|ЂE,gb r("B JE ߇.ogbmk53kZ. t%>nz\kҥ0h|H&ȬU#ۃHi(ߟʇ~x7o9s&??ccǎ?>36a*cݺu &L)OIIɣ>ʨgϞEw.jFR-~諪#F# b~ʕɓ'Savׯg͚uU]kY~k?tXǦ^tQ,3<5D%zͅ刍6xl"[U#-pO:%BWYJ1*Z#MglF͊k֬a|ԩLv,GQp9+2x`X*3^{M dƍ\.> V|vȐ!h/QĿ5A{[lW\r8{N-[3{ȄES1~hc[tO%1M Ҭ]EE:"|5L4&-uQAZ,dYYYnn`XL0I̷| 61aÆit>}I jjjpQn$^̜9Ss '@_ULWZE{"H޽Ɠ'O"mHLxGa(?B"rUfmߪa¦x g1BŶJ~v!|f۹sg,Ƥt'ND2D E>h۶-zho̘14pڵ+BQĵٖ5SLI–}ܸqǏ3_̌5<%7Bݱof5KRW/-3fBDI;UYAƖt􋹢7Xg߲̔U hGK,!+=E8)0'N@  Xb۶m͜9s &h  )4Y#QF=3ZM_HĪFoKg4Y#Ӆ>|K~9;v,g,G&tCqtznn݊UhYQ{Vk;;X#hFDIJh)f!Ytb}L.0ԋ ӦM80$2u M)׮]k~7II'H1GvQ;DcxzdR߭AxYZ.8\b֭['-w)Qh&E#sfׯ_7˘ϣ#GܾXJ[n,9u5,aHjD{T9L_WWIZ/dU z3wʕZdI*JO~{1Ev>{l3~VſL YHF.wѹ^*.@QI|NRWWAII1L٣(u6:7Ǐ7mĊ-W_.QK %PY|A:5Ց_ FŞM~JMaaI=m?rY,XEjwݘ<(Ĥ"M"9_!e̖k$JRFNq@ɸY/؍hG` sWNb#afI8 Kh-іPHVʷܢTԿ[cy 7c86nGbl$QBΞ=R9*j SKCEtK` AnEe$ѢNbr) ***>VP Fwy*,t$1-D@b.E@QmணuE)аyUDXSB"RUOa3 tU^Fa*/DŽ| rҥQ9BwS#zUDxfiǣp4Тb:uef&Q0v! w6/^9Qsڵ#Gz"tp s4X. ͸*>uTq3 @@&ڝW\,wJ*Sfm߭<h"`pK3gVUU`*`iLT(Sz3p~СԤ5pk.RTImm-'ΜU RcЯOV6LD8EBWŵ>PerH6DS+7l۶>G_D"\Wyy9A6n(,N:!Dc"OAHJr ZuOÏ1BYへJpYK)*33A3 i8q`<yKkm2;,tOwt-[IML,N*Sfm٭<h¼$D_|ʕ+Ro"LS,#Mm=z9Ç'ao ,ԒPR/Xc&›vN ׀e;v,..4c"XsA;GB_(1{Q+ͺ.XNQI4fر$4;vأ>j~R/$Naf(ZX/[o߾3，,>i=5qIeʬM5MWGe{0Hh;k֬Rgvoj SKCEK`u={vnnj5n_1EN>{ 1c0Zƺ:'?L-Ph_T)֔="x饗h)/snBHvuu5rJ U_FFiiFnץKM[q8vTPb.k}]IG.B_(1{7W+ͼ\Ⴅj!23(Ii'`f8<[,3孷z8L,_\1ʹ8D=%K\)L@qv rNU3!#ܹ5wTVZR*LXs$6j5n_E LT'2LJq_Z w}w… ImLwBYVM XKŵ>PTnGn`Nٯ(13G~v*?N %F :T_ۂK!C"&!?R:c̖>uسZu7Q\MQY+f pGI,Ei($őb"bz\ڼڵkȏe: ov ?hfg~~>WVV#QCCN#_E1쒒X[Ν;F_h%2L5}UFUŋO<0v<3Q@rWr%E^5Əiz U?Y=#Qpux`̀%5ayyybۉVЭ.RLQ253ٳg=~1c(o@J9|0{~*m3~WB JWlZ7NE'Cb'@:߿i&ԘoV)'UеkW"\OL\|%xs$lCa8S4( c >QFޝt󣸈IԘ;xn._ Ne3(IiM#ő?JѻwoN+Vӧq˖-3AJ`t9-d$T1Ld֬Yq{̈׋B}zgP4c=z_ L @ap<=IND)FnnA7zlW~;3l0zFBhȔ0qFœ&M7n9nݺu߾}LW=(Y&n'OL3ou@Rm:=1Bd_?"d Rc♲GQ4k^v;yC/ ok" QcITMoȟ~iա١CHWZP;Rhw .\Hm $4TSֆ ;*Y)N"L e-Fb^XO f܅cXtlE2K2GGE;% 8pu`p{%ц9K6 S]ʕ+@8?u4C@3lo>tP[qe%s[C3f}vNtMP @krM }=>.\ աX]w8zhnh@33I*}q#Wٱx![hMĭ2^zbwn~)д0͛7S9k׎@&wŪ1;E zJFH Ϯ@sRg#\d-*j'C/&lfqCg"߲U9vǦ~=̌ь*EZD2̘14|h5 1n(%K( fJ}WGf X\혙Y#B]/3B&K`0؟B~immAAXPUqv  u7/DUǿjhE%RMpaSu 2q+]$alٲ|EcTe K}@`vڳg--ZD#%(* ?I4*`iӦ%Mq͕tٲel{C5+Ź{G?L4TS(..&I@pH5k&dԧgឧ8̙ˁ7A} (6k׮M81n~PRR8GS%KC"JRF=R8ydEE 7i 4T}Zƹe.ܫ'X'N(**"-s-^-4\:vF>K.%s )N/sG2$Gi Kq43`R դk֬ivJC@ pE9s&GY"7n+qƄ jS@#JRFHq2Gk߾=!ŞW!|Ksğ>}4?olE%) #8@ 2(Ii! @ YDIJ)N "JRFHq@ dQ0n8?;d&5h2f<@ =8< @ ,R@ E4@ ,$a'@f%) #8@ 2(Ii! @ YDIJ)N "JRFHq@ dQ0B@ QgsdLDԗ[n8p`СW3g'M3#5:Q0ڵe|G̘1_nNv޼yYYYw_n6mF0'r짞zJ¨[hdB#q~+++Ko8% ߏjϟ߸q><1=BDIJH5Ź~: ~۶mQ9-]6j(2>ܪU+̙3,g޽x8aduwҥ}N:bͽ{$ cB ܹ$)*d{ ɸz!C0"d4&Imuڵ }hόY@H=*eee͛7Wjt[}JFԘ;w.7!ǎYŋ4ҥK| ۛ={_ŢW~D2Af-DNkLE!tʇ~x7o9s&??;vLC 5ݺuk׮]ݺu &L)裏2*#8pٳgݻ#Gr¢ Q7FŨʕ+'O|Yz5z`5kk-ׯwN1Ջn eؘ:1&刍6xl"[U#-pO:%BWYJ1*Z#|lF͊k֬a|ԩLv,GQp9+2x`X*3^{M DR.> V|\PP@K\e?+10qN:-[ gd5eAc&\ N/,bz%qJ0cY#s K:t`EkKi8M,_ ޽!AcǎmW_F#FHq C4Q'1v,**z'7l1aÆit>}5N2 gQB\ in8Ǚ/+%8h !zɍ@wok-fA/KKbƌb$}\%J/XWeTz_ϟ?3S>{l3~V1r$p"m,Y]) V/L1]8qb4~wXPmŊ۶ml̙H1AkPHL|͕5BLM=1)~\5j3<ߡ%> DK '^z,F8kp^Çs/ǂ6cǎ P}X#e{Ȅ>Cb8`LGv֭X`3?wy@(ǦCwEֈZQ/ef Q0RÂ3KT2=Dr RAGMW>`pȟ6m'9f1q66?)L1}߼yk׮5VKX"FO0Dc$\BՙIQF=iRfJ k!r O^n|`% D;E邎]_~|*./c>~H9rNcA+++FnfXs)kYԈ80r b#:3_S[cz7sW\EVtPr$Iwq/V&-Z1][2(f!yE`ߥF7Nz0E]&19J]]m&FVk&3ed`Ǐ5Bܴ?~Oߴi!A/x(I%,>x H/b&KP?\֤랶,,X@"5;TmnL\xbZsN2f5RWff%) )88X>}tsdZ$יF :tAp~=zhTq9)m,'%$D.E̋+z_~* UW\2e֠aԭ<hq$=r䊵!w҅CpTBΏϞ=.R9*j SKCEtK` Aʦj5V^NZTձ[wKiPQQAf`o$qۘg2R9 A LGRB$ Rzqmu:ZX$_QL WeKԋ_8EK-("^.ֆ9m,I{qU5uTȗg=7"]$o@0 "`0#Q6r7nԇLkJ w !|y bsZuOÏ1BYへJpYK)*33A3 ɤ8{L7Oly} @ܣG}bӦMw׮]/\k^oM'0Gev=!ڵkÆ }87E3R}GlE3K!^K8mlYWŵ>PerH6S(͛׃G ሓRԯP#;y=Uk2;WVV1 O}R# z/SԘ[(f ,U$JRFHqDT!Ϣy.XB5خR_SI6lcEM"l2};}\(֍&.c'Q@J` 8'؃q=*&Ev"g׬Y*@ThOz38{\y դ5pk.zuc20Q|ncƌalȀ wwBY(/kEɛ9_IW!DZ]]]\C՗Q?p&Uz]tIߴw1ފ1$#z/SԘ+f pRTI4&\p86 h<:?rwnNkm7XfAZoq۷oz0|r}([ aK&naSR&& z.9KyTUs|BQY djIu2ux`1;v@!\MZB/ue`:i>>UcܗB{2w}w… ImLwBYVM XKŵ>PTnGn`Nٯ(13JwHeHhNJ:tIBD&MBL]7uǘ-9&'аg9 1n񣸈\4W+ͼ\+23XP2=!0a oTqk׮[~%EWAh닼e: ov ?hfg~~>WVV#QCCN_puܹtg햪_]IғNR2k#!R5rG/^|'ԇ,`؁䘯7%E^]t?^/Sϫ~4^~GXG䳦8?//O6D+H`)^ٳE]~}̘17 ?Jq>|GZ6L@![Q)JMZk |dHH_13#$\#@.@VVjLM9 q HK7s\Ob$@m64`E]v#DŽA1}^˽F2;麧Gq#4a Q?-z5Щcf%) #WIr 4?pDYڙ,ҰaY6%`q-؟"_ԟ=ȟ8`"f͢F.cFԬ_^ "蓵8p JNBb,++G?u{=`#xz'ˉrss尅d߸qv<Ȃ2BG3D5 5,..4iҸqȉp֭c(h0_܈O<\g޼yʸ4ƶave[z51(//gvn|`ݺu?3k.Y_{s>wl۶ ͈M5, a9%dӦMcbfL{Z6a˷ĻTԋM2͙3iZG.^cf,"5W_+];w N"-ǴۊPdLAjLvB [d$) 0AR_}ѣ9W*xs;f&cV<P /%X:5~Z[[;h db~9sU]C4Hq~čd qporcQ bE9\u]ãLJp9DIJH5d-˗/烟>믿F7RD{awŢEq6{$$E{9F iӦ%Mq͕tٲel{C5+Ź{G?(0̙C䗃"P/8$͚5KrmwSpSC}'-@F^vmĉq󃒒Ǚ?TVV.Y2 Ӱ ",L8WER{ĉEEEnfܹs/C 42 1ײ;ҥKɜrC ©ܑ ˁ4C%ygwYPPf͚`G!l <? G^ā3gVTTy?޸q\̍7&L@$Ws!i8X 1-l[@P޷%ӧe[Ϗ-M@ h'@3$8@ !! @ k) D{M4O -hOq@ 4KB@R@ ͐@ h'@3$8@ !! @ )N fHHq@ 4C;9yE&N)0}-[Dw@ L87$.o;vi_\\hԐ=OThL;֮] QU͛&Mҥٳg)޸qO>|4/n:pСCW^U5X3gOLfGk4u5Yh *CrȍrZʺuiӦ?3ŋ&LhӦMVFyܹõk֬Y3`Zڔ{0LҎMӧO\2;;0HvFb Hx&7nOLd2L8qǎQ!58Q5̆fΜYΥKn;w|_|Y*履~!FII Jz]_|ai>FHQ!ݳgOTHիW bQ&pq%1Ijk׮mym۶mr)1"=%p =5!YٵkWTH²Bٽ{+4z[ngQ$XnY\Yaa!f6mjӦȑ#\զ qhsԩ*.^H9NVZz@Yaԭ -\k4iLRU8_5G4 OlHfJKK--**"i$믿 ?1K~ӷo_M!11J<ٳgx$8k-h?I*RLni)N\$%D#9s&*wggg?~uuuj6GfY5k0 F>uT|xx̣(8wN|LW^;dȐ(_Ԡ-[q%\wiٲe8#) 07ЏLXtza!0oߎX/8FE$P  UTTXС+Bw]^4DJ4U-~fFM6aSL C/$ێEEEO> ˘԰a4M>]å@H01*]pMEYڗ_~)WK0]j {O<˗scݑ $|0v!L*>ĭa¦x g1BŶJ~v!|frΝM885dv>m۶Ƣ1c… Lk׮ E׾{jh@Xd[B֤b3"_q^ɤ/+%8cIDATh IAFH;V7PuŬ?^2ziU̘1C]ﾓDI;UYAƖt􋹢7Xg߲̔U hGK,!@W{*|K~9;v,g,G&tCqf:=z@[n*ˣzD96í(vwFrz)3iq) N:3VYYIJKFl^3qB^%|&gvGd 6m4pm,H-j~~͛7)ʬvXaZ=0Dc$v$ LȤ(#`J*S#r O^n|`% D;E邎]_~|*./c>~H9rNcA1![n,9u5,aHjD{T9= ":355iY 5뱩z3wʕZdI*J.ɟpa5aLzѢEߵU/S!bQ ]jt.~ >Pe#!ӟձІmRjdeFlRjLx H/b&KP?\֤랶,,X@"5;TmnL\xbZsN2f5RWffR{lNT:0K!L-ѕ,9f3<)IkPerhbh~E14l^m,Q/~-TzdLB.8p@cr1a; \tiTs]ȅ^DQ9Y(\i N]IJq[C)7odx,-G1\Kf "tp^6sܤ ͸*Þ:uT3zHڛhwV_q.t÷[cy K#:1E8gTUG!{eT9*ҘL-Q,;fEСCQIkPerH6DS+7l۶>G_D"\Wyy9A6n(,BzN1 aQ9BeﺧG,@\%Ҭ{]ႥL%mLw^/^a{ 1c0Zƺ:'?L-Ph_T)֔="x饗h)/snB S"rJ UGiiFnץKM[q8vTPb.k}]IG.B_(1{7W+ͼ\Ⴅj!23\p86`A[>)qG_/"tpam,Xoq۷oz0|r}(q&/Y⚸NIeʬAݭ<ho]킜SGULq;wl~g)@T(Szc4lrդ5pk.zqݻBDu"||l8~B{2w}w… ImLwBYVM XKŵ>PTnGn`Nٯ(13G~\"RYÇg$ \ 4 >1u%ߐac|g[ƞ' \Ǐ"Fhr_ 4^p nPiʗ_~a"/pNO ̴~>WVV#QCCN#_E1X[Ν;̿RUUk4Izw@T̚Hnŋx auoV0Q7%E^5Əiz U?Ysw/?ң,#C)˓0 5!X)Wf8{a0GQׯ_3f E :㏱Ri"fѯVy*P>Q)JMZk |dHH_13#$\#m\.@VVjLM9]xbg"-A;їI4m)iM3xûvG $Wc0{GezwuOϏ"Fh5Rc\FңtK(pt `0t*똙47feigHÆ c^za啕"GhϢ[0}U/1-"f͢F.cFԬ_^ "蓵8p JNBb,++G?u{=`IZpr/[rj oܸcj$g$h#SSę~ƍC '­[)+Ew\M׿ō8ɓu͛ǮJ ml{6l`WfAi߯_իW303rfG1g ֭[?,[q_{LC}-G nٶmJcͭa!\,@ 6m~ִŭ llTbĻTԋM2͙3iZG.^cf,"5W_Y}YܹshUpi=?V<6kC!.`HDK9 7N"%IC:l}Fڿ[L)HgEX{ \^XQQ;\k׮E2nj"D?CC q "w`<w .\HZ04<04gΜDO[ @F^vmĉq󃒒mN8K,i{Ec8pɊ)@ oҀ4hsU]$ŹWON8QTTD~[*Ν[xq}Ziu͍H}.]J3R_Nd)~+܃'O/ɋ8 (--P]]MXPPf͚`G!l <? G^ā3gr%{q27nL0I>49BDԗ[n8p`СW3g'M3#5:ڵe|G̘1_nNv޼yYYYw_n6mF"Ν;mڴyꩧ1;wNˏ?سgOavTmB>}zʕ٪U&ȄGoVVV3pr#K@6Ο?q|0xbz'i7STNGm۶E崸vڨQl@pVC3gtSNq#?Oؒ{<3Hԩ?'O7/()..^R$)*d{ ɸz!C0"d4&Imuڵi8۶mR 1bD{bK6@z4jwߑTWWGXdɲeˢBZ޽{ŊTUUn>{RW2_~Y+oܸ1c Ba~~>ٮTф*J/eZ*.6è[[֒iӘb$7 LqkbHSLq'dM8IqۨKcDCh+--XfF'O}6sʨ~޽{Ϟ=v6 (DCbbT yՐN:{mӦMHq2Z2~Tl58-܀iSH,HW?s;Əo;^|yҤIZHU4gƬH &;z$5o<3Bqޯ_?F۷O?Dܹs9v܈A,^xРA.]C֭gϞm~_(򕟠1LYkKF&SQ߿?Ǐ߼y̙3m uرg"k'Fw[nڵ[nT"a„ ")))yG8ٳ|Eȑ#YJ}UUUaBb~ʕɓ'Sat!wa3WFfͺz*_޵:xcSW/e(bcԁ:1&刍6xl"[U#W/F'\SN:i`訴RJ碁Bkdb?x]]ѣYq}͚5̂O:) %( Ν;S zWKpk[ CĊ2% 5ho˖-\9rWb`:uZljʂ:L #^XL۷1K<n= `41HFBw(";t]ר23 Q.M,aU8l0O1E:cQQѓO>afI>}K ExacU`&@_ULWZE{Vwxɓ'|rn޽;2Gv!L*6èU,M@`Fժ(UC$7{`;wsNM85dv>m۶Ƣ1c… Lk׮ E׾{jh@Xd[BL2D_~ǍGx=~8%aG$tP/74pŬ?^2ziU̘1C]ﾓDI;UYAF0sEoG ܙ)=6e9TK6,YB΁UxR.N8A1x;,(bŊm۶a6sAW$ 5(S$XxwF>^Np5gnB%V իj2iF !s/ǂ6cǎ P}X#e{Ȅ>Cb8`LGv֭X`3?wy@(ǦCwEֈZQ/ef -.a ԙ)rtfz-RW$֩ԄPɴrk^$`pt=m41XIQdsU05׮]k~:"E@#aIcxzdRL0n F`֪tNp9n:lK MwF4)7~T\Z Б#Gni,~)Xs)kYԈ80rn{ڝD,UuDgkjҲpkcSWfʕ+cU]?). 5aLzѢEߵU/S!bQ ]jt.~ >Pe#!W?h6)5X#6)5&){%?~F{MXq=CpO0)X՞eh:5Ց_ FŞM~J ;I=m?rY,XEjwݘ<(Ĥ"M"9_!e̖k̤ť88nNd'-y7GI6CWNb#afI9"@ Z-5r W/QU2Aګ|-?IeʬAè[cy Sc]86nGblX.]pwvUqٳgsҁY 1G%X djIutx`1#1HT\MZ"u2ԋhQUnݱcGS.AEE JH1]es H@,¥h(2 unH4e66 pZ$UOa3 tU^Fa*/DŽOim11_uOݏ\ET㙥9f @ԕ?~IITF1)q '|ҥKQ9-$Naf].4ԩSu"_TWW?CDNIeۭ<h"`pK3gp{eT9*ҘL-Q,;fEСCQIkr:lܸ:F,B9UG<!G1랆)b* \tqJu STfff OIq݋n,98sTgҤI֯@|tp s4XfG*))X⓮e+Ieʬ15M/^rEMdL 4)=vQ >,R9*4&SKCEK`k׮]]vE'O9r9ek<ָ]^rxz/++c >YzϐwJKK=i,z-Fne!`^@Qm 5[\N٣7o_<۴ik,HN^.fOg!̝jqqqee|y= BLw!u?2EIٻ5\iֽpRuLZP6@P r qݻ;o1p\ƒ}{U/w s4XfG.B}ٲe555}w$>QM\,N* n`E"p>8'齊<ރiRm'r~x͚5YYY̮QY djIutx`1g͕p]MZBQ_7(1fF֨ 8pwqgj)ĜBLJQiAKyCptBe1ԕ+Wb22J.ݴM6pk.]oRq}}o( 1$#z/SԘ+f pRTIKIq.\Aw`+,,ؖԇHjX]<w%{km2;8'k}vLpy뭷{1999˗/gRQO~-,wJ*Sf n`E!Ns*>󨪞)aΝͯ,ԒPeR/c>vC.nۅW/^l d`:i>>UcܗB{2w}w… ImLwBYVM XKŵ>PTnGn`Nٯ(13JwHeHhNJ:tIBD&MBL]7uǘ-9&}Y֭g9 1n񣸈\4W+ͼ\+23XS &X/аbvK0Hk& UV^m7׮]\R&$p[o`vL쇻seee2r*puܹtg햪_]IғNR2k#!R5rG/^|'ԇ,`؁䘯7%E^5Əiz U?Ysw/?ң,# XYSƟ'atk BSTLLq`h_>ftc8E~*m3~WB̗D+E^6i'! A~ό4pDj̷qDYY1I4夊vJ`K)_8y35.HنhLqLh*P;#DŽA1}^˽F2;麧Gq#1DLSwl۶ ͨMZ5, a9%dӦMcb5tm JLxz1)S09s0MG.^cf,"5W_+];w N"-ǴۊyKAEuuu(V4)=zhpl'UFch>rd̀@k"nLI(bwY90yfQqS8gvdX5f2SW/ rgyyy9ЀDKډqЋ YЙmHrI<Ǐs -ӦMK-i+[e'l-6777k-Vsw!)ʁNq`s!CKLf͚% ;BԤ)!>ѓbD H\]6qĸAIIIF#8K,i{=Hq4AHe; U-sw^=:qDQQb9wŋLC̵cǎnnDtR2MaH?GHq!3`R ;w,((XfMt#GSz#/̙3+**<ğ{oܸqLƍ&L xOM4OprRyG}{z6_ -I QSSSXX(TBHq@ 4CB@R@ ͐@ hܵ{&Mƌ'C8@ %! @ )N fHHq@ 4CB@R@ ͐@ h'@3$8@ !}-[;@ RQS7|sǎR`/..4ejjjYG' 4&ǎk׮݂ 飯pI&uٳoܸQ^^ާOO>Dԗ[n8p`СW3g'M3#5:,ZXSСCd9FQ9-yeeew}ݺu۴iӟ]履~߿?,zͥQ,=ztiA{upl*>}zʕO=Q&ȄGoVVV3O?m"?~ƍ>`)N&Ө)ĉwRASQQϵkFEfC‡[jE9sf9ONzɞ:ujʔ)$50#A_|A@ATqqq;w$E vϞ=Q!W^2dFݚ]ĵL$]}m6HFؒ 8␬ڵ+* waQ޽{ŊTUU=í[(_:rU_ +W6<$'')J/eZ*.6è[[֒iӘbu믿S&-ـiSB[iiEEE2D.]\DŽ?^WW-w1!dȳ={fݻM6!@\k@iLRՐd'pM3Oq".]j~Ks)˗'MԪU+O~gVd ѣ ͛gF(}wsF رcr#xAuֳg6^믿P|'hpL$0j dvZc* ?<~͛7K}\Μ9Pǎ;|&Bס][naݺu &L)OIIɣ>ʨgϞEw.jFR-~諪P7FŨʕ+'O|,իWFHYf]zzZ֯_b<뱩2ALf(N̫t]3ؘ;DF[&:*:uJ1HFGbT:ݕF@Mmm-6))5ѣG5k#:u*SA<+ q.&{l3~V1r$p"m,Y]) V/L1]8qb4~wXPmŊ۶ml̙H1AkPHL|͕5BLM=1)~\5j3<ߡ%> DKoݫW/՞egN ra.Xfرajܷokuoч~H A nݺl~.t^Caq@5 ť8,;Ǚ}K؊GTNfEiӦxpLJQds5??͛e_vmoZŠF98ڑ B,3#TnafJ.8\“׭['-w)Qh&E#sfׯ_7˘ϣ#GܾXJ[n,9u5,aHjD{T9= ":355iY 5zl5QcI*J.ɟpa5aLzѢEߵU/S!bQ ]jt.~ >Pe#!ӟv?h6)5X#6)5&){%?~F{M3W_.QK %PY|A:5Ց_ FŞM~JMaaI=m?rY,XEjwݘ<(Ĥ"M"9_!e̖k̤ť88X>}tsrI-X6զ)S6XNJI]@5h%@z_~!3*UW\2e֠aԭq5lFL#>&YzkeCҥ |gwQu`vϞ=R9*j SKCEtK` Aʦj5V^NZTձ[wKiPQQAf`o$qۘg2R9 A LGRB$ Rzqmu:ZX$_QL WeKԋ_8EK-("^.PerH6DS+7l۶>G_D"\Wyy9A6nܨ׀@HԩBT9&=,*@]4H#TQ;Wu+\T234MIq݋y[*k[i >o: Fwf(zBҵk׆ pxʾ5g"Ieʬ15h¼$D_|ʕ+Ro"LS,V4)u`uvQ >,R9*4&SKCEK` oڵ+z8yȑ#)[" c/{YYPUTT ң(~SZZȀMH4~w`)Dk 7r;- *X6Ln`wEݼy3??6z9ܦM(_c4OGwr1{> ׀e;v,..4c"XsA;GB_(1{Q+ͺ.XNQI JqDT[*#m$Nѝ2;w1b˖-#ﮩ۷%IM\,N* na+$W{0n#[Ҥ(5f͚,ufW֨2:TD{:< YٳgK&[v! ܨS RA3f ek# 8pwqgj)ĜBLJQiAKyCptBeʕ+1T}HnڦMU^.]7m)]rLYXS}CQ@]w% }_ 4^p LZJs\TO^^g,H (kmtg̎cZn߾]>\z{DNNo)'dk;%QհM]s*>󨪞)aΝͯ,ԒPeR/c>vC.nۅW/.ٽ{w]hNdmǏz\hOf.\PW!)R9 Ҫi!p)Z6*m`-)E3&b(үn"RYÇmA!ISW ~1fKg}ֺukY~Beﺛx(.b(,J3W ţ$4f„ $Q9jݗ_~9pDRei#/pNO i fk \̑H цLT>w0<9& \Z5jI==? 5hnC%[:D9p kSY̤81(K;ӀE6l-~c\c Cg͚E\0#j֯_/C…d-`P4ʒWKb{6ӓ<^NTba %RqFL3<2=5L'o(A z4iҸqȉp֭c( 06qɓ'̛7]6lUо_~Wf`4f̎Mc[F?1fY,'o`[ܲm66#6ְW.lhK M6c?k[@6*I]*L̙4WZ#/^13ꫯPdLAjL49BDԗ[n8p`СW3g'M3#5:ڵe|G̘1_nNv޼yYYYw_n6mFb\vmܹ۷aGr짞zJ¨[hdB#q~+++K GMoܸ !d5Ź~: ~۶mQ9-HVFEfC‡[jE9sf9`ȑ?E35fsԩ)SH7/(*..&8FR`Ν$IQ!ݳgOTHիW bQ&pq%1Ijk׮mw?~m۶M.#Fd'dG8})KuuuTN%K,[,*ݻWX MUU?ܺu>Lj***:vؤF;\)G&999dNQU \x+s<\mժUtFݚµL$[ů_5G4 OlHFMq|Q9ƈ VZZjmQQL#HzGBhyS*gϞ{mӦM nMZKOc'=p mye(WW;vx/_,EKq̷wҤIZxi1>ӵ"c ;zVVּyU"{~o߾? sF رcr#xA]t[={_ŢW~D2 fl"Mf5ؿ*JǏyf˙3gرcϟD:؀Y{֭]vu֍J$L0C\B?%%%>(b<={޽9rkBq{U{ctZ\\گ\2yd999̗..lf~֬YW^޵׻#YǦ^tQ,3<5D tb^M'U5r2 WԩS"EA5:*ҹ讬52jjkkIBM]]ѣYq}͚5̂O:) %( Ν;S zWKpk[ CĊ2% 5ho˖-\9rWb`:uZljʂ:L #^XL۷1K<0U  UTTXС+Bw]^4DJ4_T~4 6a>=MI̷| 60kLjذaݦOR jjjpQn$^W}(OEZvv_~)WK0]jY޽{'OD˹{ȄGy".#$)Wefjf1b*mСC0 |w Vs;w1)ĉ|.QC@Qowڶmh,3f .\vʨPq￧Xfʔ)(_&B>n8Ǚ/+%8h !z1W$oh&ZYK/d*!u1c(>%J߱ 26\@+z#?>qL1-[ȑXzdrtE“'X0`vq waAq+Vl۶ 3g"9`A"3e3!77Ww25ĤsuԨQ< ~p.jxH`$ov^T{I#5B8]H/ÇcAcjܷokuoч~(; nݺlF(=QMp+5\^@Z\ÂXLf#N޾}^xbt?V>r5P/08O6MF8s6cl$l~Rb\Ͽy&E5׮]k~:"E&E0Dc$\B`` ^L2BPͻ5*S#r O^n|`% D;E邎]_~|*./c>~H9rNcA+++Fn!RԩS׈!q`R;+XԤe-XǦ^\5VtPr$Iwq/^hjx H/b&KP?\֤랶,,X@"5;TmnL\xbZsN2f5RWffRO>9)r\%ZX6զ)S6XNJI]@5h% _ѫ GU`i"$) na3`j96#GX+Bp.]8G;*Dk|ٜt`BQ VZR*+Xsgx R6WxH]rBբݺcǎ\J ܐ"!ocK!,9'0IAL XKŵ>Perhbh~E14l^m,Q/~-TzdLB.8p@cr1a; ﺧG."G J3iETuLZV͟?DO!;wnXgV8tZm@f: Fwf9nޅf\[:uB3zHڛhwV_q)L7|5h"`pK3gp{eT9*ҘL-Q,;fEСCQIk.D:lܸQ2  (ީS'=rL){XTsYi"F5Kw<W 4^W`:Eef&h$SI&ݻJ]RT5;; B\JyI63XfG]6l0'Ӱg"Ieʬ15h¼$D_|1Wr4łlHh[VloGEr,団Kc2:TD{:< ֘IvյkWpɑ#GSnE*I&{YYPG|&(H(!.YZZ)6"ݙQ%6|,̫`(2 FuK){uMs׃G 6m$EG y:SY,sرcqqqee|y= BLw!u?2EIٻ5\iֽpRuLZP6@P Xݻ򝟘 E;X6PL'lcE 1e˖wWGn4q;L75h"X$W{0U Mm<]k֬Rgvoj SKCEK`u={vnnj5n_1EN>7g1c0ZF_\dI;SK!,dU5eM Zۯ"-îPW\(@wvS*ZK.零.q\9&;c_Be+Iȅ^%5fxJp+\T-$UffRR .p梲#Q}I63XXoq۷oz0|r}([ !/Y⚸NIeaԭq5H,E gy T.}QU=S2Ν;_Y qGe5%ա"ၥ^0|1 \r5i ů^<Du"||lǸ/Džd6… uژb?L-," Ջk|V`_Q4c"f\~v* ><5tP}m . LLoH01[rL>֭[crb.k}Gq#4EfiǯWy/7V(ef& 87&L 1XW1M6Yۡ<>FR(I ?ݙٙ3ϕHԐWQ %%%6\;w.ݍ4vKUU믿$IKIW'L5)W9T#/>z"Q@rW"wqʚfǏW4Ak,QzA,)˓0 5!X)Wf8{a0GQׯ_3f E :㏱Ri"fѯVy*P>Q)JMZk |dHH_13#$\#m\.@VVjLM9]xbg"-qqM<9i!0SӀ)gw5I`y-5랞EP|\s(ҩ'ʁ+\0]ÿ( :f&>i`TN1(K;ӀE6lzQS@s^?d1zR.1!ULf͢F.Hw5ׯŅd-`P4ѣOl30`q F$-O8Urj oܸ3S7@,(#!4xdJ{j8OT#PP@wl۶ ͈M5, a9%dӦMcb5tm J%ޥ^ lʔ) 7aVzÿ/FH }WJΝCèHK1-1][/!! ,$9'Ȃ8QS $զ# #IŚKjn (2M 5&){Ecv%|sza`ر ~O_v-ŝ?fD$& \駟ƮX:td{Ee  +npBFc//ͰL[A⤸IK.,,d D VG8BwkNQrPϗ kx)Toe FKq$嗗\#KŹO>4Ί]Bd;`IUT9T|hc + @R6 SG~v ?q *20.6:T29í3ھ};y X&( 5& !< '裏 kts e0AtgvG9H[,ZmGKQT?~hThp6mZ'poI\J-[ƶo> >dl)~_soR WNqT4v3g_^c@4k,ɵMHީOf=Oq8 a8$Ezڵ'JJJOg2hSYYdɒxȼW܃'OÊ4TF0\2wIq'NYow@Ν;x=@#s-++ر,])*g08 :>ݰ)N3_q PZZʹzΝk֬ivJC@ pE9sfEE{7Nܸqc„ Or5)xR Z^^N#oߞbO+% 9jjj }[O>}^"T)N fHHq@ 4CB@R@ ͐|@TDɘ@ r'@$8@ !! @ )N fHHq@ 4CB@R@ ͐@ h'@3S'O.ZhĉӧO߲eKtg @4jC~CoرcW _LMM 9ѣD5رcڵ[`Un޼9iҤ.]={7'Hr֭ :tQU?sLĴif~dFSQSE r :t,(*~;o޼[n6m?k1]6wӀLMt?~͚5 hժA!MgϞbvTmB>}zʕO=Q&ȄGoVVV3O@@6Ο?q|0xbz'igĉ;v A ũdԨQd6 |Ԅ04sLrȑ#gj,O;())!YIϠ/ 0z%|;wߨٳ'*$իC 1è[֒iӘ$յk6qm6HFؒ 8␬ڵ+* waQ޽{ŊTUU=í[Ϥcǎ}P}K6mԦM+WDB!:u*J/xeUVefukw Z2~Tl䦁)_ѥ)8M[Ҧ8Ro| 1S Ufۻw/M߾}/]U5 (tAGQU2QSϞ=3E'!@\k@iLRՐd'pM3Oq"L#jǎ?˗ȇggg?~\j31vI&jՊӧ1+I=:`Ɵ5o<3Bqޯ_?F Q駟h@Ԙ;w.7!ǎ1ŋ4|[={_tROH&aԬATY *JǏyf˙3gرcϟD:؀Y#]í[nݺQ &pK觤GeTG?pgϢݻws5#GTC_UUU=\aa!贸_resrr/]]ի#Y^Jk-ׯwN1Ջn eu`f(N̫`9b.ksǟVuD'\SN:i`訴RJ碻& 5uuuj6GfY5k0 F>uT|xx̣(8wN|LW^;dȐ(_Ԡ-[q%\wiٲe8#) 07ЏLXtza!0oߎX/8Fh~W fL4kd.tWQQb)"C1uz)3`:*RFl~Qa,<f__[6m)SQUàG:cQQѓO>a2&5l0nӧOp)`p555(7/Dt6idi_~\E,tժU'o^Np5gnB%V իj2iF 9|0r,h3vX?z@c@տ #:e'⸂TWW3=zۭ[bZț%л'ʱnEþ5‖kKHKqX0v˙l۷o /P.نqB^%|&gvGd 6m pm,H-j~~͛7)ʬvXa)bK98ڑ B,3#dqk&(E`֪Ls%|8Y[|sT`iLThOz3ԵkWpɑ#GSnE*I&{YYPG|&(H(!.YZZ)6"ݙQ%6|,̫`(2 FuK){uMs׃G 6m$EG=4OGwr1{> ׀eJS9&z5C~dA/ewk<%Ҭ{]ႥmAD;ݻw'dG;?1%d3q X:PL'2;w1b˖-#ﮩ۷%IM\,N* n`E"p>8'齊<PY2IQkx͚5YYY̮QY djIutx`1g͕p]MZBQ_7(g1fFXWW'2ǝs m2*ŚGQ-eCU@aWWWc+WPk}\ ;)qXnץKM[q8vTPb.k}]IG.B_(1{7W+ͼ\Ⴅj!23\p86 o8we"2M'0G5N8'k}vLpy뭷{1999˗/gr߿%[XTX7.vAΩ\ϣz8d;w6j SKCEK`رc6j5n_y*DVqԝd6… uژb?L-," Ջk|V`_Q4c"f"ZD $4Ç'O%FY?H2$2i2}cJ!կiʗ_~a")$p[MLL쇻seee85d04UBIIIiii WΝKw#RUUk4Izw@T̚Hnŋx auoV0Qɓ9%E^5Əiz U?Ysw/?ң,#C)˓0 5!X)Wf8{a0GQׯ_3f E :㏱Ri"fѯVy*P>Q)JMZk |dHH_13#$\#m\.@VVjLM9]xbg"-A;їI4m)iM3xûvG $Wc0{GezwuOϏ"Fh5Rc\FңtK(pt `0t*똙47feigHÆ 8W޽9j` cΜ9ܢr Fo>裏 f̘믿F7 ~;o޼[n6m?k1]x~X޽2˗/kH MGɏ?سgOz1I;6!N>r짞zJ¨[hdB#q~+++Ko8% ߏjϟ߸q><1=B4jsu)*'ߣmۢrZ5ąjՊ04sLrĉ'*׭[׶mےK.ܹ?{_|a )sNٳ'*$իC 1è[֒iӘ$յk6qq"CKq$oĈ-ـѨ)w}GR]]S`ɒ%˖- i{+VhBSUUn>ݻR$y7 X)S 6LHܸqc̘1]vp$''ԩSQU \xT,s<EZ*.6è[[֒iӘb$7 Lqk.M1iؒ 86&or ,[r}/3fE1ѣG ͛g΂D~q5-F߾}'5Ν`A,^xРA.]C֭gϞm_(򕟠 L$dҪATO?<~͛7K}\Μ91ԱcΟ?"u(Fw[nڵ[nT"a„ ")))yG8l޽9r$K){U{ctZ\\گ\2yd Yz@FYf]zzZ֯_b<뱩2AL1Djr[\Xn'U5r2 W!+u QiEwePS[[MglF͊k֬a|ԩLv,GQp9+2x`X*3yyQ[ CĊ2% 5ho˖-\9rWb`:uZljʂ:L #^XL۷1K<n= `41HFBw(";t]ר23 Q.M,aEn8Ǚ/#8h !zɍ@wok-fA/KKbƌb$}\wװ 26\@+z#?>qL1-[ȑXzd"STI^c08q i;ﰠ8ڊ+mۆ̙3]0 b֠L`ᙲ+kz;zbR¹:jԨgyCK|@ X5<$0~W^=ˤ!.\˱رc9àԸo>dY@?2?(+oӣGtuVBk t^Caq@5 ť8,;:3f!Yt"k%aO,FpoRŽEM6Md D^[ Ud_vmoZŠ1z!sp$a'?Na` ^L2BP5H"0kUFp9Kn:l˪D;E邎]_~|*./c>~0#GܾXJ[n,YԈ80rn{ڝD,UuDgkjҲpkČU z3wʕZdI*JO~{-wä-Z1][2(f!yE`ߥF7Nz0E]&19J]]m&FVk&3ed`Ǐ5Bܴ?~Oߴi+/;pO0)X՞e|ݴ^VG~9&{6Y)5&]Ef`jwc ǣ"4|pz1[23`} {zr:lܸQ2  (.Yc"OAâr ZuOÏ1BYへJpYK)*33A3 J4g޽8ߍ~ue",^ϛNaf(zBB }k,IײDr2e&̋MAy\"&r4łlHhloGEr,団Kc2:TD{:< ֘IvյkWpɑ#GSnE*.^23AA {<2`<,ߝ)X ZiÍgB V/ .@jXĝGQ7o7 n<yi&)?y:'{> ׀e;v,..4c"XsA;GB_(1{Q+ͺ.XNQI JqDTN;KNҾ۬~GPL'0Gevb,ܗ-[F]SSӷoߙw^F(֍&.c'Q@JHL`zF IQY5kdee3ʷFe5%ա"ၥ^0:bIk<ָ]~7e`:@7ƌhq'?L-Ph_T)֔="jK9_IW!DZ]]]\C՗Q?pmڴQ[u%}Ӗb%+dg{}CQ@]w% }_ 4^p LZJs\TN~HluH yqtۊI6lczܾ}|&[=˗3F9WRQO~-,wJ* n`Eb=oʥ?K!2:TD:< 昏;y%WxqPŋw -ՉL!Sqd6… uژb?L-," Ջk|V`_Q4c"f\~v*?N %F :T_ۂK!C"&!?R:c̖,,g?!wM<~1BSkxJp+\pcQffp{C~3a+)a]-b"N8m=LMyt|9ٙ3ϕHԐWQ %%%6\;w.ݍ4v {5$=i;$)&8"[#*}}'xB}}L=YD 1_ܔyIWeMǫejނyՏ|ˏK H|Fh,+S3S={0ڣׯ3~X4NÇWxbg"-qqM<9i!0SӀ)gw5I`y-5랞ELJ1DLS+];w N"-Ǵۊ.\ աXѤpnݺрf4f8.1}q#WٱH4xl92f@5F&ˤzEM$f hڃ[D͛EQ)NڵkG b՘"L]Y\B#<6Nl4`RԄhVQ;Q5z1a3:٘gʱ;6ۨaf fP)o"fƌrܚ?>vB [d$) 0AR_}ѣ9W*xs;f&cV<P /%X:5~Z[[;h db~9sU]C4Hq~čd qporcQ bE9\u]ãL܊Ct2FMqc.Y磏>*(( @́={ nh"wI.GQ^pqNQcڴiIS%mse+]l޾}$}ͽJq.^;Q9)߿Μ9$:~H~9x)CҬY$6!y>? <0'zr]\\>dik&N7?())?y)Nee%KZ!^qR? +:h Rk5U-sw^=:qDQQb9wŋLC̵cǎnnDtR2p0w$slzRf$/ 0sCuuΝ; ֬Y2ȑ#@ȋ80s̊ "7n+qƄ jS@#8Gk߾=!ŞW!|Ksğ>}4?olER@ ͐@ h'@3$8@ !w-!3|F1 @)N fIHq@ 4CB@R@ ͐@ h'@3$8@ !! @ )N fHc8'O\hĉ;Oe˖@ i7ܱcǮX~=틋MrѣGjɱcڵk`;j1ܼysҤI]t9{,7nO>֭[:tի&̙irN8-"!D8tYQTN ~[nwvmoKz衯:*ׇgϞ $ڄ8}ʕ+z) nM )~,///mg$߿, ~TD8ƍ|RLQS'D vTTTDΞ=BզM+]t^.\еkWAz)_|諸^ Ν;IBP[[gϞW2 nM.ZKOcV׮]۶mR 1bD{bK6@z4jCk׮2܅eG矛akݭ[~饗믨gMqȖȄzѐ#DSNEU)pQFeZ*.6è[[֒iӘbD8"CSLq'dMOqnݺe>?Cz왟ͨ<jǎ+)N\v f{mӦMHq2Z2~Tl58-܀iSk׮|AT68.\2e 6}o;^|yҤI9"XZuj˲v9ep\RzE\!\YD d.Xr?"E\(kR.}d^My$d2y=j ﾼ~ד}0rJ4o߾zj̘1yS0ٳgsrrH6mڔZȧ0aW_}E~-/Fq͋m e|^HX7DO0ޕc'=t W-p<(Tn +)Nebwe# j Ŷ>۶m1%wqCa$СC9DiDpFzJXu LXٖ栉C=g} gJdqd9vd̋6c_z%$Boqsa\#n^Jƍp=9|ed}s8*3HRyvqW"~1[;#}EU85̙3؊垤/P5pVG- "g#ai@\8zG .eY$cge\8"~t抨dqsM"PZWcq!8h"y\ ꤷ&pݦ/_1ݘ>;wL;$GNauc"$'r:2$9b=.q# R-[ӱ:3^ג@=y's͛g>> rPrYɲd4ŹV0.=}t_AQn#IرD;'xWM&qJYY e&%Gfo'%%begg9h#Tnc!b0(9Dk=ρ?uّdt=.8{6*)9cƌq5W9Bd Eru:iM1paIXo߾G\<В"ƴϼOwY\Kz0k"E>}+ΦMZI'=3V `/흕hhL !rP= ^+hцh޼%KM&!t`#jՊJ#q a&JiW!,ℶ*25BXwnX:Ec'XDT1[˜1cW%txwB<^%v$#K.S+cILmڊI 0Nj@͸X C 9{U[-VAmks5͌ڵzza <В"ֳϼE4n;8pO>@6y3i}ŊtÚnݺugQbUҥKswH=޽CaN؄%ڼ8wm'Z:&:ۇJ}h=.G4i7ޘ6m>fwAQU]j\^+0,)C6Q]D2 ={SYwnۂ F?RqX3{|ᇲ˵@%Vv]"(.nU[6BX{. Za0fzS8L=z`&}!wJX?=qcvݫ#/ϭX@".]+)SМ-4i]M^iI8م2i2jGH9E}ɇz0+A >"'?Ƹ$YkeMlk8wĈ>y whE= {+q^d#L4a4,+Cs%Ά  1˗O~nܸ/)}vѪc ޡ1)J8MD;'']b'v߼y3#J"tqdf%%ѐXhݺ_|!$Sty)mWD,\dՆXÕ8tOHtҥKIk9't;W-"NA%G2ؖF#V9+ЈFeӓ 8Ls=Ǭ<{U!pH~Eٵw;B7<mq*C&L ~]>F,^XbGlݺ LYƍ۶m˿+6n;w:#xJZpr.WTbdeeYZY,Y"`ވ:<9 'ʑO(ȡBc BW\{1;v`4h;t޽9A̝KŮ<> ;1 ӍUV1:n c|`ѢEϟ>$qf0Y"_,g͛7o9zpJQQFc-̱)_,g?`x ѣٟ0bMy[7 cR.`#Go'Nd駩g̘q3& /tڵo߾ѣG0 DPײ_ضDXDC_䗇\@2YX7dB!91NԦ! 'IR%aoH2L 9.C09[ 3g;VBt/\Ӭ;7OV$&Z?_1;۶mbsZρ*5g&iӦѓz<\9b8Xî){8“njI.xU=(_ޓ#;EU ^hDL gS>-NMI $R$N"LEYp{W9vᔱD(rMfڸD\DZwCJ!8ܦM)0H/e;mϞ=D'!A&M1蘬!6w]΅uW-aի%"M(@krM YfDs|bqX Ê%]viӆ0 Y=Y88J[Qsv,od-G T $̑2(܏%FZwS4]sYlupn2-^(♩dr (P u^@s@z8sLBĪU5]:XD=_nF(F2vNo%(3n8 xSbI$b9"=DOY"CrH?_~ hw"*tLl!tL…̈C FS90wa-[>}K.ԉCFA>G%R`gP 8qĉɌNR^'kr(G%2Th#ݪxЈ0&aŲCp҇8˗/G>HT!CJk׮ݰa\H[L>; یG%I{J$1Ǐ=ztR.UvWٳgqy)j-6+++kjO\[X{wMZfjT@^^*'u7CJp4a.FS3cuĉ?p"ސPҊ*KW۟fB9tIagb(ׄZ8JuC,Ƀ8;w^t) %%%H#F,X~Ν;Yvz.=EzA?~<3NY1LJZ-D=3po3g}]9$\tG,U,X&6mڄСéSLU D4b8iH-i?5I*'#;Re2_x?~u_L:??A:ujҤɞ={$*m}ڑ~דcs9}a*hhk߾}O=Ԙ1c0(aglڴ)z)(('(?a„[/^<㱩k T鷸0ޕc'=t W-p<(Tn +)Nebwe# ,GY%Y 7S9؍Eرc&73vF895pk"k̜9V,$mIV}pػw/)k1믿^TTL8[!kRGĐ7YYY2GHLJte}';*wc!%^5ГW_}{\ʙ#* ixپ};̀c@5zޯ2\hf *.WpӶm[lrJ3'N#z*ǦCsIBRLCaX Dwan!/%GR H6o=z4GI9n/qqio,Iv Q>/\0VVeE8=eˆ<;C x1FoD$ CmFmrH^h`Y{u[j$MАy˗/waL7hΝg:cɑSXݘɉ\β IX &kH2TKtΌ׵-xǦn^y$\V"$ gq.+LKO>>"ėkbH.9v, ^+n!iI=gRVVEIɑIqrcv66w'H皐8J6".1Ct)>Q{IFSgl3fwZ{(DF+ P$GZڄ9Fqi͎Es}E(}B#uc'Ed ȔUVɊf.]s!uwrea)"b^Tj7H@z"Iĕ]@jՖ9{… \k+.ruʨ.a&e-r+̬1w&}ewk΃4AgWW@ԆxOl*%@5y *_:&cnѢ)Ȫ JΠoDGXDCcgw1 z@ TKZ }7$4yNH4hC1,m,Q+ѕJeF,\ '!njp] z m1TzЊ¤㹥۟#@X{.HNݘI}8 -[$.44j8j,Aъ[Ƌp.7)B1JG%aR())[mk+.҄uwE ګW/I;}܃!, NUIcg7 ȂkWg1ZRZĘ{>_waDu9}4ҿiӦtIόBec Až;DTN2jGk%ސ[S< 9P'OnԨaz_]腋OA͗,Ybo2  !??UVTbQa3TNke qd'UAa ڼs)3=2 JԥǍƌüڏl,",q_/R5!<$ pGv$#K}xjrc,TٖDIQ}so5a\dȐ!q/Wn [IR]gϞ:n - -b== ^_k׮mݺ5v@s&R1p&P#v#QÑg1W9e8yyGk%ސ[SB9P|nCn rPE4$q'{!:8//oǎ#qPk;GB[nU'am޹ag;GsVÛ a261m3/}޽{7  -œ KyNtLL'um1`<ʦI&oƴi,$1# Bz@ TKZ }7$maENr(@uU., hzNe򾜑tᲠP2{ǵ|Bj?pf?aÆS;w88[Un aBVX"N=8n=$Y@X]/=AH0Ĥ(DZ"pAvx\u$]+VH`4Q_tiGLBso۷oҤIv5Iz%dg'i2jGjOIjqqBw`eJ-FrV.=)8 <'5*qu\h)pixu{|RGW=M0 ..8{G h׮]ɱ^Y1-.R0a9낄=nDŋA !}T֭[D]MƍmۖWlwܙu F 앴\[YYYbE%KD|XdB 捨Sʓ_9 s r0//o BW\;0q4`|wޜu^~evefY إY~뭷ؕPwرQnZѱvS3-:!iӆ+&Eɤ D\DPq "ʤ|k<,DZ6mJDF^ᗲx6tϞ=pⓐ MtLVbӻw.B:0bhjJYX 59&ЬY3S}"9> _,\VVaŒ®]J Ptfd(mq"Gٱ7x# l9gBo a A~,1ҺYsC@βePS\sv-ICorFLݼ\3 (WrW^ `=*ź%*fgUC/.lfqD>W;6rftb-!Sjh&Q2ƍs:u*L"F)K%2,,XvW!rNͤBD/\k:9`4;|ݲeӧtB8dt=sT.v@GȚx$ [8'|¿&/xT"#HV9Bحʎ7 cV,;4'}QH Tܹsy;3b/ Bb,qof<".YL6@4s%jǏ=:Qj*+[ٳ^7-ĹRԴā͛7O8 /e Rp4a.wt%C};JZQewtСC|LJ;v̜9^d qҥ RF>pẪ~."qj޽{̙cͬ=ztƌ=4w]bE-Bm5kɤ$5S3ᲬT*q2bIܹҥKn())Yf͈#,XP?lΝ,[]v=W_kT%A?~uXyX|A/p3_3)TcƌmYﾺö_P *qEQE@T((QEQ%Q((Jr$CF&]ۘޤMEQ``((JFGQEQ D%((JEQEQ28(d *qEQE@T((QEQ%Q((JRӧO:tS_|9SQEQ%ejTo.'O~wצŋ)gW2h~O$w[^ydÇy睟9ɯzժUw/*?ϭ[v޽d#Gh$V #/4:5*qOa-0ضm*mdUkܹv[ ڴi~ n߾3gμ⋍7:wO/{LWZ8tмy4i?A0GaT:mŊzr0m޼@ MnرcK,X5T35*qDjv q֭[gҕo}L馛…lٲ/]$N:թS)SFmڴIV࣏>bAa5˫[f "$ҀӧOoذ$W_u]FzKOMW.\x{aesy>hGb}v`jԨA]$Rl<~ 63Y?A8q¤(6r=zX_߿u_|TVM`C̘1K.NMÆ sss[9 }ݬY衩A8&dԶ#ۃ&9SNdvm˖-9r9bo :u*kLjT7p(c|M6dR3ڵWG9>}0rJ4o߾zj̘1yS0ٳgsrrHr q|@0 +CoYxq?4xǦn^l1,# U%z-;DXDjn؄KtK%+>H7fSٱ]H9}4>Yׯ3μ/XQQF11eGԏk;k׮c]9CeȖ%KpgHpj%fu6bh$$4z˗/ǭGJtLUVg&MX *ȅI&Wq~X9'5M͑$6oޜaCRL7RUQϟՀdܹm۶L?p=5#^89s{챷zur? CfR@p('2[-Q,֤IQe1gi߾=xj;w.'} -[ta#Hꔣ2jh^6%=Gb[Em۶FQۺ~yw9F :Ez iOF7jQX׿} L0 ,-Q9ryh\g} gJ8;x2EQ1/U9?htذaR7/%qƉA8>|XʳkxGe[*.Xď;frc8cg{S'&b̙3؊垤)9.C0t,;;D酅8rT*pA{Lr^fGT٨3Ɲ֤^8 Q+G#Ikmˍ#Mf"幾rZ>{1ӓ"qdƍZJVL ' ($\@z"Iĕ]@jՖ9pUk+.ruʨ.a&\6"\R>,wy'&}ewk΃4A޵ J В"ϼM%s&R7/=\ؤ5ƒL4@Hxp so5a\,V!C={V]*ӭd6I#m׮]ӳgOT[g|WYLԆx/u}qœT+=O+Vt֭=\<y|gҥ93x`VV<Z9aBy$cb:y Ooߟ޲5It8ia3; e*7Cɓ9 vII :o<>݈Ѣ.nz3|:u>iK2ǭDž9.wĝλ%i mUIۺ۟h#BXZHj>J[ou#qӠMA~`o# $z܎{\zgqӟts1Ѵiӹs{r]թS'Prl"d^8%3\F/[M,.vAS9T\\l*)qPwq1gW^ZRZĘ{>޽?dC%@6a6/!ywۉN!?FyM&MxiӦYHcqGY%oH ^;hCQE>MD*ٳ':5{-HpYPH(iJ>!E8W|ak?Ji켻DQ\ ݪBtm6\+µa$pyw{%y1|}„ Hvm۶U@rX?n^}q}nŊ9(4|ŮtXYN28&MdWWZNvLZő%R9rQeoqnt'Q\ ]Q"9ʔ#`[X \pC#zRpyLO2\0 =~2\j<#V:tΝKdO?4,>!pq{׳؟2:4"~]ǍYxtbGlݺ Le7n_j߾}ΝYG`^IN努U,1 ^"K%K"|W;XDQ'3D9 9T7|AQ!W+W|;0q4`|wޜu^~eveBW إmﭷbWowرQnZѱvS3-:Wq!1% k9 PvN"S"iG :|}T~` !HKĐ# Eave:B̙Î .*4ƍUE,ɿ.zWŶmۆ\s`J 3ټ 7pڴi$6yhibؿ1ְ'yOGx1ca!c9*!n/ɑ"Z*G ɁJ/4"&)LgKCb $sÆmU'w,Ľ+ZA pAVs \E%l^eT \$$b?x(]V|N!8ܦM)0H/e;m={'!A&M1蘬!6w]΅uW-aի%"M3#,bbh֬)>X\0XRصkW6m(@1 N1mq"GٱoC3P70Gˠp?i݅SLR t!a gٲeb()¹V[XȤx9nTgn^%X@{׮J p̙օ(U1;jzqa3t&{*ݱc}7clxRD;7e7n<ԩSv$`1NX,```ܯ_? _ s:n&}:&z\fD!)e|T绰-[N>ݥK! v)3(R8DdK' Q/?5x9ǣAMnUvahDb١p8CJ˗WgMV$L*uȐ! %EpknذQ.-Om#Ȥk={p%jǏ=:Qj*+[ٳEPIk kNI+LJC}hTI.&L ZH~~f .q8qb;YJZQewtСC|LJ;v̜9^d5-q֭[z 0]tAʄw˸Hںw9s/Mr3fTДjuŊ-Zg֬Y('Nc8? :ʧJQ Gn%ysK.庡8bĈ ۹s'V׮]%(W<ǏR74hW:_?3,h.RPVB3b͚5cW#(JQZZ:fyޖ+?=le GQEQ D%((JEQEQ28(d L✯=d$`ҵMGQEQfֻ8(d$*qEQE@T((\3I67iEQE?=X7LoqcEQEq:0Q((5كUT7*qEQ1{JF%(8fVSިQEQ*q8(R=X%Nu`zGQEQjĩLoT((Jc`8ՁJEQEq\?wErssƍMV?NCEF&{N:6b\r)s=<ȸqlr9SE1I qi/Mb 9rΝ;b IkcDSZQEQf8_~ڵkz!KvիWѣO=TݫURPsQQ_ޓǎ[bȲ駒_YLogĉs=ǿh;AӫW/Ibl_|A_~QLYXdI۶m۷o݅˗S,T3|ɰa8`Ҋ(R0{p|PU\\ܹsg6|w%РAUV tO֭ÇM''Ç>hfz?^{ĉ6JTc1Ο?_7o^fOo~4ID~(\c[}d76y5HDxxLcOG7 $βeL"9tЮ]Hm\J ZIEQEs=$BaܹǏ?ѣGO81rHt9|uH⪙Bzۭ[27lq%'qBQEQfao6r^)cL: i⣞HHT(3fa>|?Ϟ9s:d$`U8r~ӻ8(J5)qN81vC=#m۶]p9vuH⪙yN{&+eLoTNaaJEQa8_~+bB~jIU3q3-=z9rdM]8(RG1{pHs-aBڵ+FxWCGߨB+<Gy+0@U))[~nn޽{&;G'ed`V#5HRF *q25bX6ޡt{I?LUfgLt$*q҈I $ႇo<6hzg?9ֽ-hM~7w wVrsq+.n[ޓv9+o(r6G㐼QteAN;gjW4>_nH~#98ՁJyITdK9|GOFtQ;KɞWnpO #G)pqkNyΤb9_T^or.:ny7TTZzGF/oK;;#=jhœH#}b$/b2JUQ1/8iJ HoOϽHDEsy󤻲n^J11qe3>Y0+l['c&Q<' Ib?Pu\|x nkBF/oAT)B*ʫ(q(ȾJ~@GNN2JQ1/8iJ HoWxۭcyYn9Wֱ:_ؓA@<hsY6hpל2nœ28h6iIڻ?|Pn 's&;LKӱf9: (WJxz!i_VSd"Me|pndwy+exƏm1W$;Z]7_70SY.q?K/7;y'O!ټys5jџ;v\bR`={ܻwovv76mٳ˗/o߾=G)O߿xy-[c*quIc'm9Ĺ\V߯yE?>[<^->-^}3(QE\ ڕ=W=Hooڷ/?#9Qh ur.O'CsZv<\Y n\UT*qeՉ8!LJ+Arʹ5+rTe)JO>]vhaÆ-]tH~ԩS]`wPBLٰaiժo>}p3eeeF?hѢiӦ򗿤q >s(Gڴi(9]%N]R!R\^]Ф MQh_n-j7b TH(\U2Ĺ\<7d=ƤPS/{cFXb+qD;7VXݹ63n"Ccg?{mΔ)SYnǟz꩎;9rD?g%Ċp" n2''xvi %q;+I8uj8(&ՊËoۘ\72(!I+@\y`9$_Iڐ8'!p-"8ՄJ~yYY2ıg 3= PK:f2T$ڥm۶={L;~N>ݤ+gie#IޠxP--/Iݻ>zQčw.]ʤ/UUEAΆ)ߧ+~ďsbR·c"㜞@^Zݓh.IFk^{J%N5^Vs@(qO|9%m1OxIJR%kf9f2T$aH\ %~gggl?i.'<}4jDLsA7Y`;SNɓ'SF%N]%-c1%sBBKuǖ+<RzGyHSbwB7,NůY%WoxyH%N5_rģ$/iZβŗTeD߿+'?A5 QJOđ;CGJJ!҄JJKGL6ᱪ"},/+g}_o9%B4XN$NF|*η#QP9OBT\KTTm!f$izM+rTeW/q9ұco1//I^sĉݻwСdĩ\CS<A#ïGľqG߹ح?kNJoX_86Ycӱ8Iz@d(Twq,8xcܰ~ZV27BIJ{ŕ&$[f"/6VJ[7Cu3UE*O?rd{FvڟgC 6s,%'Oې9l0Ӿ}Y_W-JʵFp1R!a_Q22³8 ?;%忍*a⊿n톊,W$iNI׍cTYPS}P >H9V̀#2D*![=+8n&Fke:T%Ǝ~I 򓟼曢f `j۷/C|DK*+WhժSN\T"QÇw7G}DR%N]ZJ+}ǿQ%”#V+|t~e?7h-gR$2H+_c VF.WIQǶ~oTHPĩ֗0'(-qU9oEQā .\x(. ( dQEQEP((JGQEQ D%((JEQEQ2;((JEQEQ28(d *qEQE@T((QEQ%Q((JGQEQ D%((JEQEQ28(d *qEQE@T((QEQ%Q((JGQEQ D%((JEQEQ28(d *qEQE@T((QEQ%Q((J[/}K_җ2`߾}}Qqq~s۷o۶m֭[ly7+(7(t  AڵC<߿޽ȝݻwsD((3(.h z?=;=TIENDB`code-001c16ac87ec/doc/images/edit_issue.png0000644000000000000000000015335515046233326016616 0ustar 00000000000000PNG  IHDRbYa\ IDATxwTW ,EA 6ClXD 64,)_-PԨQ&D$jcQAP&Jc̸.=㙹s;w̪6Uyi"0@ &i"0@ &i"0;wz\|BhOw/-Bs;ٷ/!D8SDd+!$>!1pʪ*$->pH#zz;w7@ GDR0~ʄ}||;'"2 i"(:W7_%-ov Dfm .]:|zzzIIIMMСC}}}UUT^^>y䢢">hH-Mڥ㼂& ^zhѢdw۶m 믅sDz$`J䫩 Mdc:GtrrZfM׮]sss7lؐJ};/_.ovʕ @5z6|k7byVLOW{Y^^x)D)p=vnݺBuzjҥK"ibfffTT,dy'Vi4M]娹y粲qqQ[#==[5 RЊibFFƑ#GRRR\M~|}}TI՚qFMMMttK>|X^^emm=hР'*++]Ӗu!˗/Av{ [[I&1B\ǤᥐǍAx#G222TTT̙!۷ߟ쨀1 mUib\owC144zo~Ux<^d棿ZUj6Brs7_w˭ؘbcmb+,,xr68|s{maa}w-luppltDJZ+MqFpp0˥K?={)j͐x⼼<255555?SRRǏӹinn.n=߼yǏ !z0`@d#::z􋗒rVݨ8;w۷oܹݝ.<}u|>5+߀d4mϘ؃Jiq75_g&|Ư7B\nCԎ]Q"B6-Jjʝ m[#2OuF[[g{T$~;v\{/5 "%7Ν;/((ʕ+׮];rHppCS SQQit}#k.,,ƍG <}/*ZZZ x<^vvvHHUخ]/nٳф{{۷kkk74]nnMW}vqƮ]N:ž$;IH≎>xիW'NHBBBQGGg7nرclj'!%#k>Kˮ֮vw;=ύ!++EǎzNf:ں_}Pg^[xk^Fk _nY'sWM Ԭ];ݓInkMΦ&TTTLp!SNmj5alğ;wСCf,Y_B~yBz}{^t)551xyу]ܹSOO)GYaȑ#6!dI;wwoٲ[o>W^ٳgTaZZ]_~ۛ5o޼[<^YhlޢE_-Z@ x}{>|?&>B5uvrxx轻w !tqqeíPZZZ<Kew6ΟAPP\U&._LOcSPPO'77ZbEUUݻj{GO^^;ohhHV e||<=-<Cr$`bccvĄx굄|LqzbFfέi-7hllqíH:>|NHHHHH'N@e{, c& 'ƍcOM\r嫯Ip-[ 8ֱc]v:,HNRMMMeCu!;u8 0Y¦L:uaIIqVpk6nV6pqDJZl… ?c)O>ݾ}~ۤj7Ih@`wYv ۪֭U޽^dܸqBmXJ :MW u/￣9WO&+//Z4w׏gLaqpа#M8iD(nσu3}v쳉{ Yp =zuu &L蒒ƭW=;wNxxzZqSN=EEEtaaB̌>\ ehc=&8j>;A} ~sӨYRSS[b#2+nDJZ}ӧ!dܹC ECȦ6u痖R^~q .2244w@:d nӑ\vFܾKi& yxxi7P c}M%AiӦ)))eee|>իWѱI!NNNkjjRRRǂP۷oxϟ?;i$aiB{bw}{ijS—3?ehʔ)4}ACJAdZlbFFFFF"]]ŋ7!d7oޤ."`޽5k֬Y#-ҥ˪Uk|>tӦMoWhc,"4رcn*))r:::&MofYs|>> ח1M$رc'OrJVVVEEZǎKݶL޽{KΟ?^\\\[[allܽ{Ç!g%"2] $&6ȮaO{_dhǫayxQD9s͛ZZZ=z:th"D`:i"0@ &i"0@ &i"0@ &i"0@ &i"0@ &i"0P:tc"( :& :;wUC9z(z ( :#!ׯ'$; ypw DrDOWy OԷedJMb  &16}||yL^/IJSKد+򅛞=sLϞ=544KFFFR<o&&&ړ'O`Jxxٳkkk%[[[;k,N:mٲnͶQQQٳgF~RRRDvYEEeݺuٳgllCwﮩ윚dlfܹ ,xj _M噛 o @Cx&++k̘1zzzZZZ#F'a?'yĽs$DPHc6GL!bpUWWϘ1n^l3JSSS]dFINΓz3f+**bcc_pݺuYYY? CCCo޼\XXخ]KԎMMMzڵk%f͚✜˗/Ӎٖ:.\vڋ/ƍp_rŋSL5j_u/^?~ܹ4WZdfffeeY}< j+Wܰaϧ_>((H___x[o uNZ 03f̢E -ZԤ_>[&#!*wF+W=IPӧ?СCmKK!C\\²J+ܺ(ry}wΜDlv5-W(uzK.۷oR tvz}jԴB!|rͶՑWhnn.|6Hl"c}qtD>߫We˖YYYJ/7L_}%///oj`,_>qĽs$DlB>8E"N6;Dl^\q9R MPoM ?~<9۷7|SUUɓ ӦMȨ\.*.\_VV*\`y=zrSSS'O̸E}ӦMiӂKJJb-D.4iRpp0AAASL\_+"]***+W [jF oazz:cZZZZZZl.!kEWA;GBTF+4#LB$W#lwh^\qɓ/^Lh}&KJCCMF&&'';;;s8.]ܹsa;;;tY.((p֭T! ڵz^~[!S"Μ9Z3gl׮͛lK\"TD ɳ׮]aG٪ٳg.Wex, cǎ5Wߴi.;ԩS666z׮]M L'EqwߙVhaSCzjڴiT|5l"P)--eMwZ""2Ga]zHK3fʔ)TLzfW~~~YYYWپGDF-j@q.^(Z߿?++kҤI򎥙 BhѢEk֬ꫯ&LФu}@&ȍѣGUUU CUUոq֭['p@qȎ/ BZ>>LQ@gذa,"l OD _QXβsz\|B'Ow/yGBWM :ƶ C"cO݄4QF>}yDn/c绽? 'B(# }UU'@XYy!p;n'[Iˡ?`CDWpvL&Ov>ܱѵdk'0?8 |o>}/+kbb}cTOZ ʗ&RdfmpfŊSw\>/(ݭ<mo9_XXtn:LL̉pDŽWpTY2'- eM)*֍2C vRy'OK@ Q4ǷSRcb>֠f;X[w4EQ (GU?`CDuBHAA95K߸xǎ+gϦU'&.&NHٷӹs}<=YNzӅ3fV:x1sɒvvƿ2X/oR~v/0HRu//놋Nվ}OJ<~"v+7>/9;w*+Vc۷DgWOJZ*tNouϞGy}'q617ZŲin^aRꞮ)sN cWGwֱo_ +{w0QAц?tEee5~{eǎK WY:oӦ1̢CDD6&}Eiu; ʝ&֯?C xGBݻZYu`\k߾| (hpǎ/n6ݿF3v"nǪcՋ-tt=lb71|:!L|p_ݝ1̙4`ę4ں5gu"E)w?FT oQV>rOM068uBo]__m7ׯVx-%%hߦIE0HQZZ IDATCWaŊ?mmҩ{znaٸp.甘sF֭gɦ?~c'ڷ~wK87E3qF|^QQqZ_D;'l(kw*۶]*),-}}eUU@o-# :tj;$@@ (&2~Q\\diipPXxVdBd[nNO{̬gię4$266yv]BX?Yleuuu9;kD\r*#3GD % .IQt$6PП|ibW%2V)Y߿?:*~w׮Xv6B}%g}8a57nٵkҥ+j"kBڷan6"匍hhhhhhFFlnS_%<7=#aR,(޽;Y#z3 t1I%FWHg? {JKq]H?#Q6l 6mhXM?`]tn%UUuw>%̛p`X>tan6cǼ?ķ)UHC 7q"匍l  qc77HJG?dTKq]H?#/jn Ǚ6TJKK?w\kG>G +DDFO\Q^)ڌW*cc/O4az @?z`b.;П|Ίi׮ɍix 4 ~\ |V__eKС#0B6&E0ka0OtȚj_ߡ|P#?`i(%"DqRISY ݭ<8І?i!'l M_MB@CBO@(#'xUɓ',k&$yzj0rDZПH4QF||! qD%>ahcПH D`_at4F@q?EMB(#T*@ܡ?MB(#T#@|||"" ܡ?Mݵ|30`ǖѣw[;2 @*\]4kw\nR9"]7r.vkׂowtqAfp8j11E 9ݠS11kkkP;L",6wa7B;d&kݹ˚qkHwIX1⧟=+35m=zt/Zl={fg?76 37 Znb[^s'gcq %7BNݿFaao=[z@J?6J(((73cqPH`A_?~ɓ۷b1OJO("]|իuطU޽;[X\Сݻfd\9x=!$..{ݺ׬|ғ|e<j=8UBW_i NffѡC T(K2 coo^r):&mٳi/fvYt6n)=pŊ?GAt g{CpxYOJZ+4.y=d47GڵGgGKK_Ywٲ={itC֮4NCCd{\Zίwti٠Av::jNNfmСK99elp&m[Q^ONGmZThŊ;v\)+)嗤Gݙ9D-b@UWקRux$dpG%..Ç'iqȬY'n0rBI3B>@Ry0s8|K" 1|Al"y!$8)11ƍ[/Ϟh#R4y11Ύ-ZggbeE.\ #FH%4`6qbߘ؇ز/<~߾ŕƺzsʔf>Z\mzH%Q͛x|*}WhiWTҋ ׼u+NNΣ;:=l88Θi؟y@\ۛlnꦡm;yPNܿO>$.._,UQyG#短NEEej 5tMGyrr1=؁Lqʹr__f$}_zH%4zQuu}]~RwQQ^r))OV^7<ܽ{ϸ\{wϟ۶))Ox (XRRnMM}UU]BB~ӛ{iXX Z6 m޿ooIƏ'F?S>;(!USkf*}7)RCd7|@ɓ)7Ujjrll:Ns!zϩnh8fyQ9!DMMu-&a[ -| bК5Wx (+KM=sεv4 ""m@DdࠆysI5}5=L&&wwK,-Ek &o}Vp@\N?ПbB-RG%U$gkkr ۗl(reoՠnכ~:@ށ(( 7H5"FFG#lҳ'Y+<a zHg3ynn IF".*RYIΟYX˗EGU^%UI$%-=s3yC*/%H߸qqI>|512"BɌDMGq h+C*/R0lyܹzKO>|Ԑrߤ?&>> (tm,WjGC^v\]eΌru WM`@ ˔cqAZZ&~,e-?#->]@ B,G}%%41:: d׮ؖ57lbgOF&S &ؤX5c+l"Agq}W+FSgeGE/;؇]cG@1cz=!̴zxT*}:p jN۴i'3СWN;>6mkooYr)?l=**jwqoO^5k<_~!.e8:$=PANw`ƍc;X񧖖ȑ= ;6Ik&bdBgСݻfd\9x׮= Yίo.e{^F{BֺϧoϣG:w.ӧeh99\N-dFUXlб}XioBBU~`ڵ~ihۛl8zϞԢC.F5ثH,K#zL7r[?MGiZm,WhT?˖ \]]gOK: q˗pwP4 M7([ɨQUTD'#۶I-*hT릉7ndin`Ў50h׳y\\5;qs@aa1ѩZiE}Zгӄ++#z}{zj:-`㮮ߌ=*tvBկ_tPcˇ+qΜ93z:=`rQQ!U^[[_::tsuݞo󰳵>lPBBUG\9m4.V&ov1%I]>1qP1jQ@{x{qwjPĔ)aa1OFN}맴DCoݺ9y^=tTyIIqԴiC_߀t5t;ڃ~0a}&O-= ?A sxz^^ދ5k ſooIƏ'FS;Ɖ4w _zvR !éY{iW7p2}e1 IV12T_?ү!dg=ʕwK>ldHYD??'??'yG4 /&7BȍUlQG<<OΟZX˗ɠAoeW h:謌Zx/4tPƑ%UsȈ'_L '3f5ģG8&(De$ĖYl}m0l7ܹC!D gXq2e[%$?2Tր4QvS\B zm"6pHp0Y[55i, M_aB-"Iӧ4QF<=OROmFBHBB/^ >>>(tmD"';zzSQ tmJii)zΝkh@A8βsz\|BxMHe==?@X2E2B券3Z˗/>|hMKKK[[[(qqٿvݧ~|닷mgIqRoƊR%rssN-x<zyy5zQjgcc<8]Su=zt DkXdܹܺj;"4nz9"mLOjٴ~J.QWW^|8ڷS/Zۮ:!5<$dNs@\QQ#ű칚X70{̘62Ҟ3;<\XX Ǐ>t(L=ƍC;HPlvSS:;wP,zʢ'jlx^𣓓KAG̪qѵΟODŽM^2Сzu7+W}\y !0??3.:}qpj|gyaRRyPdRK+*j۷גP!4tl>jFF_~雐C/:}>詡16]d؅ .[6L]]lٲ*ƭ]7hƍ*9+FqZ_/ѻwguu^̗-~HF]ֱc(Ag==͊Z4 IDATv*XYkUWSӥU;w^.)UUF,ׂ^$$dpG%..Ç'5Ҍ:BĞ=͓|}UPQaΙVxϞ):ihp\Fג.hZ'I}8`mSؒ*G5iu :ۿz]W/dii!ܼ! !vvwӳw<M ի"".Ѕ66<[[@ B DJLLLԂDong3gUVq{|;v\Ɂq5؇kfsӦŤpzm򤮎W]]8(6-- 'Ly.25,,&5)˿{iXXԩBibwfpH]iiϟ?^RRR\\\\\ԳO?зů\׿²k$k 9[B…dÇ;VV.[v\׭[/Rݻ ޵+޽g|lt>s!zϩnh8fyكZ֬B x}sK hTJKK?w\kGlVE;(@Ċo:@:~ù\.5I+2KxqqqǏZؚ4O֬+7,ڸc,k栳yzZ/Z{~KqL&䬢BZM)q$(e\\ʒ+(3%>rss ² \]]%T@vӹѦ0 &i"0@ &i"0@ &i"0@ 8BHFF!ޞB-Fp6 rssktZ2mcee%5ݽ{2jŋ,A pm"@[kMQ6Z Mhkrm"߿cypssqg777ΜsεVt R63l0UP;8GeScMfxn"s้m Mf6DDh-HD`4 MHD`4 MHD`4 MHGTTTH)me\\ʒ+`m4XZZJmÇsss h .B\]]%D6"77w|\n}}}}}}]]]]]]mmmmmWnn֐&i"0@Жuرy+"Mh:t@166nƺH&*G4#SD4<^ *--@@O4MHD`kڎ i54c_Yr :Mh#rss ² \]]%T@vq\%<75߿u%9wc6l˪H(Gi%bdd԰} x @TZZ*RҤ Mh?NO7uum)6#G$Hڶ歈4 MH~jf\\:H[[[BH\\\5--- MODym+Q"M/BHDdxÝJQ!M/ BgeDyGF^|oRjfܫA V4QFӃ% 0SrĹ{ !Ç mIx&#NgPR>>>Q {sVjv>pHDI\]EJҋiz$AKVb0 EH@2mfB@i4M]+{Rag]ft|x N35&>:7c9u*EQȞ@ǕbK{[L}r!cy0D^5k<_~@S]; -Hݗ\n8Rgd鉬.H!rPXqkQyƍ7l84<:M)W7rK55 :&Z}2O ਐwFtu tt,;)U/xο{yz=^@lԸw kW{| ѩ'xYI s+媛S) j^?/{Ԑ[^AgDI$ܿB/bba(:MpTnܬv쪫A5>yy??铺וPVmbnbUi"à3țc;\ڥ yr/\~Myu]-!GZݲ&@Щ^n^>!=# zs5amU'5^}5־>}³NUu~4@a!MY>iB H"Uj~+A+ݺ:-k{k!D4ZN_ CP!Z:jjUռ/)Si"C-SGUyn܄AY8&b&iȱu ML i(K?1o 8ie+VUX1,,t={w S(X_a+)){={=~jܰpKnvljlتE358|@K& uw̩-7ݳ˗/iܰ5nXOd/ 89a?J*Z޺̓-5ݫۋaly̛7NhnԠHa>|v'ofNҢ^;;=qadgg^¨͛N4>5 [~n];54obS)P^r^$` b!M,9W _``ׯ⩌U" z{?|}Z}O= ӧh[>$8kOX"}޽m$LD?qlPpuysfNcF{L@``]=eK]ۯ_K~WysGm.^(HCC}lSN,$؉O6RI;ORPhap0=}S<%O,m5;;k|obq[qp_+,)))ws訪UusʔZZZD[?2*kɭֿuۧADu!偏U;}«[5x-ҏpš4 {JYY»Du+۷oV&773>~L:DͿ;Yt2ݻ%&&eDD흜uҵnzEҿݸ~u挩"mF^^t嶶ԩMPj7ĒSZZZZӧkϞ{O&x\fׯ[vYCCCd5''[iQ{$UҺ zOLLS.\^=.n];ӭoҾMRR^[zkҢuiH3),,Kzh4q"U@5kҸq^ ھ=oEjӆթQ#ڻ%K\FFAѾ}GjjOw AF^%?CωT*%' eĒS|E8qsu]ǖ(+?&Pz.ԨQ+P833W.JSIG w <ߠWVݻrll,W^fMް-[c@ҥ+]͗MUUrq+KhRSkGL4gh?oS>AݸAF+йsr%] U`+WhDrsϟ +?tV)5e֬Ç)5K9" hÆ:߹ U eĒS|epW.%$$dggǿ߰aMVmتf͚푖e> w+/IJJJLL\lq~\H&$q[oQQ4iΝۏ=njO'OmzzZllw'ګW+&''%%%\+2ts߼7;;+<Ŵ3DGGeffdg ,xN=QTѿR@)&6F$ [lIo͜I7nPǎy%+Vо}ԯSt(-Z$59˗ԥ 9Wq#mNffF&&momoOjjԾ=mJWuN_ғ'ymivM GӠG٪mwޓە+׸-kݪ٨E~`ֻw֭ۨNN F: eә3ZwΖwq߭lfۚGi"rs#"Z'ߢ9:6@@ZZC~ Mޤ_H@׮H;‚S' 塡_EϟZZ/[Y4gojؐZ_(nF;! QttXoz+ݥuď $PvmG:Q˖4iկOEjjyU?NcѣԳg~Ϛ@*O"*TDPA\SIS3o5-UoKKzuJK;֭5[iT+8Z(p50{{f劥?JLLXz%wհdS\\[7;7/Gv>ZEADtdoOǏ2=;֦ ݹ#E _-W}|~. 4kmB  SP!M,9%ܔ3:: zֵĉSJrVJN&[[ UI+VǏ]$ᝋ]Ѝ4myx,^Lf/edׯt.s΂4aݾMIyS҄ GYYO&дi[MHE4q"͚_5t(yz+z%Gƴ :|j c1wt8M@u5iBnn9##n'3:w5kh \26蝳zMh, u%ޞ~#(&4yhذfΤa_.TTёM[0*Pfཉ%d~MvPw{˽{r K* P\M,9X|IC7S@ i"@@u޽P'CXBLڷ;w_ IvBx+ib 177%"oﻊ };&ssSPV{@ Di"H4$@ M &H@ Di"H4$@ M &H@ Di"@0 J\z=qDHHȗ/_~VZ 4}rR!!!.]zUUU ҥKAll fΜY^=ksƍ ]vIttWtt42ma{+g~>y̙3?NNNlРaÔ {?&m$1}[~JSYH EOsirss'OܤI ۷Ѿ}S֮][b?+39\MܱcǶm t+))M8=s'@zj}}}wwwoo'Ojii͝;ٳlϟΜ9s̙D''YjsssMv̙9sܻwowdܹDV¶?jq}:t8t萯ѣGk֬qFn)Ji~j&(3 ջwzxxR{CC'N6CCCC-Z{Wq(rl=RǏ -,,$iI>Ҹ=Nc(m~& ~D!qȄlkkkhh{v۷;vxʥ^M5i҄]mڴ)WX`׉J*Q+8b*7@@DiVGzҥKl1c޽+ӧO:uxӓ l۷oj]>b\"Ν;gcccjj:x`oom۶!""BP˷o,--'M#u&ׯ_O2C#F$Omfff"tg0ϟ 60QHS'B"##׬Yvʕ+TO5kfoooi &L`eeefffoo%\[njcnnnnn')n6m4طo߬Yܹ@D󏳳{֮]o߾{qGѢE;w=z433s߱-ys޽{WXdɒKի[d rϞ=:pٳݻwܹJ*-_\9r5hЀ]e]e޼y#Kmxx8͟?Ғ D^JWq(1 ü~ժUD4`~LCo IDATm <҃.]gwfoGnvَ;QTTԦM|||nݺ5hР={U>>>...k׾zۥ=;lٲ3f}˗/ xF-{ Oc$>իW͛w-q}77ɓ'߽{w˖-4E+*- 8rJe˖o;ceB:Qjť̚5k֬YUV%v#Xis ?~͞=[֒Ꮔ(½"&gx(Jk̲eo*H E{FbG v9;;G"CammͮϩPaW߾}0Lzz:veddčP\Hiii§S 655dߖ3zhȆ2>CEfi[9Ϗbl# 6?i6y7J; 9skNb0ş('''CCW^?644߿H2N(Р)'|RJi +3g ())}OXl痘+\% m۶ITT!jhhɭ6lؐ[\2wJG_^ L>ښ-HKKRSS#l"Ԕv쿒SNu֡C#)IZ\qAݓ[```nn۷o7XB]2cw3z#G,]nݺUn]mr7F_|IDzzz* N:$tߜ𦒒pOC< 4bĈN:hX'@ŅK ImѺukJxY. EOEs޲E>"^CCɓjjjG XŜ(0"2dp۷oE:q/^H;4(g&O<ԩ"^nnw [Ο?_OOoǎkVSS611-O?¾GMFܴi@ 7oJ/_~}Jrr2 ֎QZV-zcM$OCQRRqqq~pG*MǎwڕPFǏ:Tby;;;:TKK+77 QY}y Ϙ1gϞ>ܰaÈ#실?CgB=Yrm0QDQ1^M4la\\d(dqJ*4(D>,v-{ց$o֬)S=~"<qO<p'O]wM6)))L1,‡U.:::Eg9jwg#'{{'OK*44FED!!!µyҀ)LDM6uppXrÇ?E4iҤ ?}[^lC(1Qy{ #\._(=z6,Ŝ(-ZPAFىիWDԬY3t_qD333 GGfffΛ7O=Ǝٳo߾L:߻woJJJFF+U͚5?~,rψ#VZ`Cuss{9rذa]vm۶MIIEjvޝw5jpk^F-[|yƍD4f̘F3陔t^l <-rUVsUݺuۿ׼ys":uTFFƫW{O 6mڔiӦ"sɒ<~xhhhjj*+,ڵ]?޵kWhhhnnn----(66͍aÆÇwuue7qƍ:]paϞ=_ݺuWX!ę3g:_NK|iqLL̆ KFFFӧO_>׌ݻw7n=ztǎ%NZ017{EH{ 8~xpppjjA߾}w.ˑ0227oޡC޿_V1cƈ8>}zݺuW\a?)Çk֬nذ… ww5z=@}U|XKRRRwm1sO ÇҦM3fw$>EܻwoΝ5jٳg獡Cnذח*lBϞ(3cx\OOݻwԨQ{6,DAMaaa{ JMMZj "??ݻw\6m$Fi/P>'MYݻ]d)'O￳gVt %'<<|…NRt +*Kx*@ :~ H?o߾[hQLLLNNNDDCRNP. ##5j]0WW&&&ӧOm͚5Ww*S(\Mg7@ Di"H4$@ M &H@ Di"H4$@ M &H@ Di"H4$@ M T:a:.]͛?5(=TN)ýi_ > M T%op_Li" @y"4QeOOyn4GG?q7/rriԩ֭b/] NKKX7}6OO ޾}VF̝OSҹs[XilܕXqyӦii)W4i-M 8JDdc3͛4WDRrm;mY^@p"ZQ0))]WO766bjj5jmթӐ~.hn:VQQ=^=IM]w_̘#5),MiE 3:8Qzװ0CEx. K++\=..*77ӧ7Oakw_hï_STU55+Q*/HaW7n9uꖛ7o6۷ZZUtu[9qװ_chإO $HNfdiggg}͟  Di"H4$@ q/^,8@\]]b@y Di"H t622XՊ/I;wB3f%@4Ֆ^xIηaԩS[n%_D&_ʢ2zذ?|nݺݻw͘1CAg?s```},R^fӧэ7K9'k׮l]]ݑ#Gv҅իW>|˗ʭZ={sDVvmkkkGGG555,Xo߾'\tǏ .400(B`;t/>p@lllZ{)]^xADM6urr211jѵk<<ryB.1~j֬ɕ1yQ۷/]tk̎R~d[h$GNNٳkժUBSў={x6Y`AÆ lmmMYǏ7332dyyyl>a„+ZXXpTXcǎ 228{SN^zժULBDok׮\ᖹw#)STZZjsݺu\_BB}JJJݻwn&mn<\jI5!!ЫW/PƇϋZ=|}}())W]]/=z0"b۷oy6c455(77]MHHضmRRRNN[GԩCDjzHIIaaXǍ|5[neff _!s  UOtttU62&}:::ZGGm۶?# SX8~xUUUww>\zu̘1EyDtԩW^-]Vʍ?^IIiٲeϟ?|ٲe˔ƍ'=11199yD4j(ޜ6mRRRƍnڴ)999))iӦM"qm@,[a+++46:p)TIJ*D뒉MX-,,={a&lllhrUXغu={4nܘdȑ#>|8a„"trʎ;zxxtU سgOΝkeeeee5w ٳ{o/fر={[dH-dӦM}ӧOvvM/?GK.ٳs޽k@uIII!)w-<@>RIٹrʶ~ng`c>+)߇ w%%LQ*g^ArLyώJ޽{mVJׯs @PoDvvvo„ UT3geP3H D@κ?^b  P?|J|ognn( MR8+:9۵{'Li"j~cR?3HaiDHCHCrzm@>mGXf͚թS'SS!C={Vl<ׯ7n1551SUGF'|v*|999[l޽;/ooBuA:?~,ARa"⨨KRhLhC&Lƍ}||֮]{ݽ{UK.9sݻwO?DGGX9nܸ;vx{{\޽{D{S2,֮]ۻwoOzxx,Ydw cرW_r)Q+JK8AG޲eK˖-UTTǏU'Oo߾O8Q`ӧ4hnݺ˗/%;w2|CBBD\|y 4PQQ100pqqC(%BǏDX(RϢє}ʊK?\x*"| IC4;~=IK)f$==RWMj&MHM zҥK 055۷ŋ|||Faffֻw3gpFFF3f033ۼyŹs#Gؘ=zM8Q 4JJJrPP9WeaaT`m1xGFcdd$rKh#!}mܹ剉:::jF={wP}'^3QL?^)e͍llH]6nMkwIUjբk˫ۼڴ!UUjݚlkWmȈԨUb(C>|%+>Sղeh}}}v۷իW/fr'ym4F:IQܩSD^ vwwWWWgW Ϟ=366fWCCC*IImۖ[+p_<!<-[ңGdiWny^B4QM͚5O:WVmZ$VV=66ADMޱ}kn=߻xrg_2F[:|mK;vP߾?|ҙ_ts-#Sʢϟe* Ja?5y2SV={F&ьyfф W5}z!,=zW^|r\KDDDvvvjjτ  pVbXjNJ%~P\R}L9dm4x:,tcѢEqqqV4hBY/_ddd͚ܿ5\[hhhvvW֭[UOJEzjW^^z'2t 4=lzdxkt>tH!C/\0͛_L:Qb3i={^biRRRbbemÖ[XX}|+6k֜_\WƆ#MMѯa ɪU4e / "c%KRRi(0rs‚>w!SҀ-5lHgСyQj*AK вe4lO 'ڵkzz9sjժ5f̘ŋUڵ֭{Ennn֭ p߾}9sjժ5dȐ 7`B[[[7oLDSL.s玖ڵkcccׯ]jѢŨQ\\\޼yoIH]SUy|јΚ5+..f͚:uڱcjq:#\SmժU=z`YflUΝ\\\ԩ3~ UF9/ϟ;w.rDfڴiYYY>|X~O;JT/!ݾ}׼!EJ(z\ e{V-:|p:8ĉժE#Gψ)@֫WUV~jժ{iboWZuٲer PDRUXpJu7d5ow.7PjB MiB#, &@fҾݹRt r}פ};EGa_?۸ҙognn( M Di"H4$@ M &H@ Di"H4$@ M THIIyCժʓޯXaCD6)jbnnέ[GKn:P-Mlܸe@ϟO7nR^@IMgVw{'srts\fn8͋:uu4uتK<"#R*VM_MWQPjӦ*[>~PFN=n-rOnibbm=aJz͚n}F;wfs88++ظ+88&楣MR"#^3iF*"MW^:~۷oL!PÇ7nɛٿP] ʸsݻ'2t&}9NRzDt!WDRrm;s9Owf44QPPB}\oUw\(v5ZQC DTvVV" bcÉhjG¤8v^=؈[gרQ_WUNC~:ωWx}bխ}rܓg((u4ĉ5DԹ0@ʕ+/khT/wppzuϫWORS?{]!3f:xpItGYY Ԭ;sfga~ /"P3M$"c7n'Y4 zڢxmu\(=kXߡC zu4TUUbb^ujkQ\\\(+,*']]O(+KH@{[YY…qqQ9>%ܼy [cBC~Y4hV`NS"zBVVF\\kع0"|ygjǔXx="`E﬈Ɔ߼y8:ٷo_63޿>}Ʋ9̙M99ٵj5iȡC˄}!Nju:uzj%%un'rOibv 5ϛwPѱjr\ ݻ(66<'';)ٳK +W>uH\\--@iWD(i"HP^xsuuD@? /(: 93iTQi"Fl4Yсٮ;LdH4蔚@_ϝAPt ÔQ#BDBD*K_OǓSdiIN_]fI իmiGuuu@Bm+?xI+ 13*))ijj֩S|…޽+B'r+W<ٷo_--ʕ+7::Zڴ7jH]]?m3 ӋζSb+AĔLQ*3ETѽ1I|!bڷ/٘Ĵk1ׯ+8Ԕ6mDDfffVAX!rF|H544BBB܉|}S\\\ҥKv޽De˖YڋCackѢy]"E-6}AvOĕQk׹+zte"]qcRW-EZ#5526KSZBkӰa_{鑚hA VU%"\{]~I۶$%O@@mLJre #n@@AAyVVԡC'$^~c66r)22׷Yf'OnڴÇٙOYxAٙ3g455+Uԭ[W^qU7o޴PB ,,,<==E:OOO6mZ͚5%v.ȑ#zzzjjj-Z8xHuʕ544Dбڵq-[x… իfll,/^8==}ʕ\hҤKFF[%sv {QUU)W\!6mڰm۶%˗/R{"ӧ{WWq() "mmmvUGGKEI?jW٫C2?3NڪU~cccpIOg#G+K"Ғc޽c 0D̟Jmݚ!b=/ٲ!bz/ٓ!bn?֝; ӡä0 s@^q y30Lr2̨0 0 3~|.=bCC,Zh1 þ޻rD$ۋ<lIv^xj*vq㆒_߱cG%%7noŋ\iu1>>&wQQQСCLLLJJ# :tϟeȐ!j+G?ijODuJ.\xѤIx:?;,X@D~S(##]MOO'ʕ+R[Z5"255Xj-#K 1di/r3<HbĘvD%m ʄKz/XTv@mDq'VZMCCWog!/fK__GUUU؉3k׹7jXUUyW{^F 2jjjp'D{#"<{'On+++"zѐDDܣ{QQQ ä}W^1 #G?rLY$"UUUQ͚5y:?;JwMщsqopg=lذA=hQ_[$O֬YÎ[RRRbb-HۄﲏZk׹O#>}>z]6}O8vp{Yn=|?1sv {ͮN>U6l31Q_@ѱC3wY31< ĜUa^I Lԩ۷yU 4qz륆1?1k0 ì^1P!oUy>}bTTaetuƍaaTT=fg3DY!ݻs%ݺu#ﳫS|--nID"MMMmsGl$B $FDv*q_\iF'w5ݻwFVQ.xvd^Jw}FbWѤVTĮ5h@@8m{x3<Ŷuf͚TX̌jԨQ ~yibT,=}̭֫}TzuYgUeevfZ^eϛwkժ{mm#b#^kkk{yIIg%%UΉ4dլIii;Uq@^ii)C QP4hP*2c`8P?ԌaD 2Rx9?p\L_χ93{iF?e{ZTTh6XǎDDސ=hϞW9}~ǽܹ3Çt>>.]M ;bޟXnҥK[hcǎSlllVKJJ""[[[sɇRc _Z]jH":uj̓ȐKv[nqJʻ.]4> -MCCMOw{Nav9k\ԹiٞZڭaI 1&'y9q!bGWX,-ǏG]޽WinCH$ ~=%6m˗2Cf>F1֭=rv3Zq60^ji63\]]+廸Ç# 6ܼyPuDT9+ cƌa_133 KT;+]bŵif/_.++{}d&}I7c\?|2==}׮]}СCdd$ িQQѕ+W Rh;+WQ˖-SwﮧӣGRܜ=zTz6QU"nuUj7kׯ_/--ܹG8-ڲ?(=ɭTD$;{̘cw6ƝQ.&o},sq^t$cf͚߼u+V622,h*7 La„:H$>Njw=-bggסC:۳o&{]''N:ȑ#bUhk­xwkm}֭[GfE hAc7oGD7.ZݣVV w1ypv:iW[Ӳe;V[WJ4+))4x0 L7o*nYM@uP9 HKRS~=@'OyQCWDJJOr ]5srD*+i""_ߚږ2 IDATluk "e˔Y=,_ND`bD{Ӱk~/S]Jȑth[.UjtdC5J&ԢF&:;sCW х, a"4RV{\M`#G6k(YlQ ] Q&?/UOw6-  L믿*|aumM43318s$tD0x LD0x LD0x LD0x LDQWa<XQxnCYfOg_CYoDLo(pɃzPWab\\ܠAΝ;JSMh6+IzM0ܹsK, EAQæNS^u&?{l„ "9rHv6JՍp阘[[ݻ0ӓ;v}ʕVVV=zسg|h˖-|An>͝3gN>}uV6ɓfffݻw6lخ]dW7=%ޤۿ#e˪ڐJ5Q5̜?{׵k޽{O<ԩSA]]=""bȑsϟ?mmiӦ=y%0H\Aj200HLL& Iq(ĉ'J6V[yQ:p^ntuu9";zk>>III]v?>7k֬Y /YM6޽;==}ǎܬ+VY&--ҥKjjj_~%7K`bve FU&L_ɣGN0M P7?]f̓jW4YA^YQQQ۷og f%p8 61/hTʿYsپ}k*}< ε366f'e.,oEEE΃e{lO>b,\e~wccce7:qD-XYYM2ݝÇU7";*5JxVWJJիWUTT6lؑ#G $\C1QK.;v,o^͈?9Ȗeaab v[aSmU[ 3gΌ?lUe͛7LMMa5?rzzzbYfMLLǏR)ps%l65(ە*RiqUʹr^}}+WT;K钓k5S,?7661b߯_?]]ݑ#GYQ:::ׯ_&ʥ՟={ƦK,F FU رcbb^BBBN ׮]322v1jdaNeU:::ͰQbN_м)Ç}zllRQQ-E EPt/Wk<'LpQzs5D*{…fԆl*p7&;wq줻sLVJKK?٫5tK.۫q\^xڶmNհ=㭼@YTyR#Fϝ;wVhE5wߕ|BB7Kkf{YX>}æFVVbb"w-))IR<5lJߕ5Ǐwtt\zudd]jkaÆ?s{YCO6lX||ѣɤZnfPpl5;}@sqqq针LMM+~&}_|yڵ%KpF痓SVVh"n{\PPPRRt5Ke͜9sOYYٵk׼g͚Um)K,;w.Vaaɓ'f])/ٞr劷77Kkf{Y333RiNN΁}1+.Yڵkeeeׯ_fVV]jzzkkE-^… eee/sT=8 ye͟?IIIkF=xӗ'凉Ν355&MMM+aÆ7jhhZJ0qO?t=zpssϹޫW/___???nΝ; ҷoڿ,Pyf̘ڣGiӦ}'ӧO33ywپ} [t[oUܝOD}X'''OOOww=z$R@@Y˖-;q℉I̲d'hiiM>O?uvvv J%V5a„jkK`XYYY믿ٳG}$eK1/@,GGDž ~ZZZnnn_|kJ?G a` :yӹy ]lYLL̰a.k4Ș̴ꮈҞ={~#RTzӹ~}M"FPzŋ_xR?~|uZ@/<7M)S,^8%%k׮...z*pn~:*$D|4^Ђ0aB';('tD0x LD0x LD0x LD0x LGZeTa3@<&a"@<&a"@<&C aׇ^^ [F>j"hU?@))Ld#ӧYǏx墢BU46vo8X֭>>x2*jK?/-7#FTlո]{Gk{|{_škxDEŅec\ҢEo _-[[eǍV:&&D77))tt,u̓Ү&$=6mۮeV:u9rȑc?yr0:u!"O|R5mۼ_ya֒v:QC4.磏;0QEEME üa۶uf&ZXL;w׈ 茳ke~sw.߶m[":x`]Txy֭555UTT>6ӳ}_b=444꿶tɓ'qyy9MѣBd}뭷K.ӭ[7"jժ5`%; o\%o@Vt=}G줏Onnn``T*5668jjj>z(::=q:w\PPPXXةS'"*,,$"555vӝ;w6o7Ps<^xID֭[n9w6mt=##ѣG7ۥK'O<}TCC#77 j*ovzzzVVjgffΕ7ySIJ{3443g:txŖ-[dWQUUo7Ȃߢ/.X@hZ觟~******b c3hɒ%w4hI$6G2xeԩD|h;bٷo_iiiXXM0~ZT\]]hƍs4hޔv5QOOujjj}󳱱QQQagYfÆ ]vuww]k;wttt6wqqH$lӦϞL .ܹɓ'ٗz1wܙ3gs탂_2| 8bdGGN),|͐woukfrcucڷgf`JJ*򋊘O>aڷg45gд)ċ/6M߽{wСlzȐ!OHHζ211ꫯ [7d[!KپuΝ+Hd3ܽ{W\hmۖw񈈈$.Ν7nH$ܬӧO[YY-\0...$$k֬aٺukvvѣG=m۶n/_f{@f7~x;Y#[[ں,xɞUBv֭$t?vhW:EQ^OgWSzl,]FQf&XQlRZ]JJi%@3Đ֭[iii줞T*eRTOO|??e˖WGW+B-}1_...b^dɪU V\/P.4Q<`iii>͵`:::l$7HAjmm]-5LL~56=Pj~d"䩺0q#$&Y);ٻ7sFE:+|XNNEsU+Jt-F["ܽ[}W^'W.]~^z9ڵ+..VUU%"6!թS'"Zx=]  ^mY7((h…-ZTvZkkkUUI&U@hrrrr4 'OL8Tyslm۶&R)fڹuٰaO?*HH@~dydO՞ciLQ4dȫIٝܥKE}{z[׏*YYԻwEOм)'L "s(?99YOOnܸѯ_?nį YHŬgqXMMmÆ lcjgѳgO"zl]uVv҅lFFFö:th@@]paʕlS~xc7NVgܜh"V|mO+ߧ*ݻWdjjRZ(-[TlmmCBBrrrnjoo/TXXXXXhjjZվm\T |W\UZZz̙۷ϙ3G U```~~~^^rvv^vmzzT*s,,,>}?|Gʮ}7iiieeeeQyЩST|'x;C}ٳBWN7oʝs]z])S/egӓ'p!MZ9e }%Pv+@D4i$.'66}NNNl#;W^CffSIIwb\$/_Z!-M/1|pwwgϞ >߿4GKXlIDAT~i|ww={xzzfggg֬Y mv޼yׯgǛl&&&^^^{^z5)܊طX7NV=+)xA˖_ٳV*M~_OcңG;75,Ԕ{=ɓϯ"sj;zN/?j|cǎlѣG/_|С$%%EFF ?x`NNN111wr劼yyb YHL}D"ߎ9~1o2suuݿӧO" Tņlzƌl:>>~̙Ǐ_Bm,E[[JSSӂ6]PP0k֬K lڶ@SWZZglllaagn_KM67lΡC &M5a۷os]zѣGv҆i"Ο??iҤQF/l&o?h*7U[ӽLMM ͛ûXn&yH7sa;;QFpaaaֺF#௿Zl٘1chტرfffaaam.o%%%˖-SR/^6l{СC!Cݻ'meeebbW_*nɶB-yݻwŗ om۶?~<"""))߹s7cbb$Ipp07+>>>44VVV . 9}5kenݚ}ѣGfddl۶˗{xxƆ&''^bïWݷo_Q3;v8}ի'$$_jnaaq++uɻ};wGFFfff EL? w;fCBB?i#”r޺u1--ӓJlZ*U痟_PPl2jbVREb]dɪU V\/j̀tZZ߿Ϧsss-,,شN~~>...4 0+++nZ[[yKj&"""33S6Sz ow E;v,b&yGj"斗5Aށ#ޕ+WhmmZ)S^[URd?۬uzz:~<ԅV 7/]~^z9ڵ+..VUU%"6!թS'"Zx=[  ^m>>>k׮VUU4irMŦ=ydĉܤ ܹ3h۶mITʦsssٴvnnn]5@y6lO?J$ooo3337owUrڵ7o'1x(ihhpiy;Z^8x?O>2n8-gyyt=&  e?99YOOnܸѯ_?nį YH 55 6cǎ`XCSѳgO"zl]uVv҅lFFF.]R:5tЀ"pʕ+٠ЌvW%K.]pjqqѣy7ղe˒v#" U!>>~MMM۴i#P UgEu%33 lbxxxpp-[*EW!!!999[nwpp *,,,,, 455}j YD|ʕ+JKKϜ9}9sT]W`YYY,ggkצK;w/"000//ӧ?G}+7|VVVV^^]P:uJMMm6U[JKK%I6m=z$P`o߾'O[NsޓhyMw }tƍcǎm@37>ikkO8lܹ ]hpx3@<&a"@MXZҒڵ# rs@}@qť+P7&4Cvpp044}{Efq1*uN6JEɓdmMԵ+}h& a"@zi++ Ņ>}|͚52;wqFxxxLLD" f/_,ݷo_6?$$QQQ7W+JTΞw޽{矶m,\[n" Kys+QİS:u;ve=zC8p )))22R8/vrrٽ{+W䕘{f/f1yhUO6-:::**o߾_}:Tņlzƌl:>>~̙Ǐ_Bm,E[[j.YRR[7yu.==p޼y999l~iiŞ={Ѣs!{{{I&%%%EEEM0b\vvvFruuMII6TVV?vX3306SGG',,ZWWaTiӦq<]ud[ͤg/^8l06}ݡC!CܻwO8?!!!;;䫯*,,Tnēm,E[t?~Y MkLLLttt߾}m۶?~<"""))IvӧO[YY-\0...$$k֬ZD||;N>mffzhUl߾Ν;ᑑ\~rrhΝ7nH$2^ŗ/ou7C[n9::zzzRMKR==j -[#\\]M YHfyXXX8heeЀ57vvv'O={ĻڵkӥR;wucNRSS]ͤD4i$.'66}NNNl#;W^CffSII wP^BvEE[j3믿w^Ν[6_L[bE@@%K455bbb|oVUUuڴiqqq [z0w܍7N2fϞͻ={<==3k,6_^7ǝL* 4ta"@<&a"@<&a"@< (^{IENDB`code-001c16ac87ec/doc/images/index_logged_in.png0000644000000000000000000003737015046233326017575 0ustar 00000000000000PNG  IHDR~ IDATxwX.. HSBH(hłQQ(X IXJTFQ4*F EEFu?f,̲)̝3gg{sϥ`lDGIA$ H"D$ H@A$ IA$ c~n zӋ 54sh8J/66UAt8;Pu@t:Iv@} H"DR1 |YDl*^e˖6Oԍ7}nnn7nLMMm3]ޅ 8PGG[b)AAAϟW3ȔɌ ^x&~"::z?իW8~vgϞ]xqXk//sV/BDzO<W_yxx8;;)FEEeddTVVjhhX[[O2eРARK_0sssE|?zQvYY9^*nsΙl߾] p۷'%%_z5<<ĉ<0`h51|ڵu/^XPvoOZX3*ի#GjT0k4ٳgP ;SSә3g&%%ݽ{w̙[Y,@  䐈͗_~)kO>D9^R]]-ω|.9 >~fCm-%)ICU:u*33FKKjҤID!/_Ȩаyӧo35UI  “'~MGWz*~͛%%T k]jՂ $ewwwWM\ 7>~x;wq۱cčak-[X,]+%ҙ^)))m޼yفUUUۣ桤vر63gvKgE-[" Lh .j Ԑ .ݑA h4A$ H"$vT H@AЌw4#6d\ƺ!ڈf"#ψ)LLL/)) {" q˧H"F$$ mma$ #A4FSxJ"DffZ_|ma9;h{zK-og 'ݷ/6/qbfnf\m#Gj԰,UfP'HC\DCYp>cA̚Mnu뎊JdJm[UT~'NS+OT43W/42u8qV]'$d>lh"""}@GGY1=zVׯF2D3&Q敏ZZWRAGGL`G]]l͚@hgohjj(55 ȑݴ#vڵF42L]MIQvt S +,K^aaݻUl6e&uOl)իd:sOBM:E/+:%P\L}bc#oN.a"dJET{k=G*0`+Wd~vdRu+L2Q)cc7haH~e_M%ߠ2j޽j^kթ&VYISJn;#Hz=e6fb";*>AG;02,]Z~jDD\M\L5Dþs 5ʕlxyx×KK@__[Dlmy(O"Qj 齷+W0rAOO}b.Я_M0i8!!*557 [[^vӧf+D5YCCldt[ԙ  ohe'CVT48L`Xп "4a&Nde)EF2F:ʣLuuN#.VUEa)O({ym*g@~@~XJErm҆ cj*X`Դiݻ糕a|=ɓ:xZD*`0#RyJz_P@ Pg03,[VlA{4χq4Ҕ1UTDup̬{Gɩl9b:HCP`bwAaxD$ H@A$ IA *ڣO/ж\\#; uv@ 5oP_@bEEJw(&$tI -DDbbyy |_#v;2LԬH9QZ } &::H<%wwucc-}}m ?Ű~'MĞ\Ʀ)k,Q<Ν3g腅{D(o+gf*Qfi;r/\en.XZjWAAuc _BBT`Kg`8:j__{Jrr\ڦnH!*'pFƳg``Zeh({MVt=G~۷i3gz2yre'Nr{U0n\ ]\hnn9GxD;M? 7Xz0"̬a&P89rrq=m(H//Ɣ)3H@\."+K/xB%`dY-s 뒒$@iUUle''r#S"֩;6y_ SYIYHj>~G/uH֭;v47Mʩ,^5OUWw Ė뫖: BK =SWĩ w@Q9EEJOOҥۣ6ID9tBx/ IA$ 0bbebU]-xF;M4.njb\H??&01&iSL$s&>TQAqr} QPC[#%?")q˖++í[o՘9S6G.}{ <\eڡCyt:BCk-SåKٳ˜9 CtӋ&[WwhMVV`Ŋ &(0QOÓ_F4Iz<@BΎ'س'fgkdh#}G&)*Q,0Q<11W 8<dAGL,+$%ъE}VܹCktijg~h$MMMlx. F52%rfkUJLs&{jΊKi/Y40JD&sr<6 &vd&xDKAA;jj$;ZAE;(7 HpznR}=@ě?=lX{dhy0'))3;E}=GOOkNhnN>|--oˏ)jZ⁉ EZņ}WT(܉AУGkv>" %% L܌#1[@͛늊ϟ` "0_S$ORPmm?R? "BNL_K]3&*"ځ7 XIcn*JroSwTJ޽VND&nn{K@)MY> @]e K>gf׮99/l.v^6ՕRigJS0aIȨ(0rFH"D$ HyG$#3=] diggh fo.ue""ө^F4d>vv6PVE:OfCa}x ~p}8 ks%?JvDZ1bDkĈ"t2ksv:]R"2`ͤdރ,9cJ\MȚkJ跅ٖӎ];jrawܣwDocƸL&GtZ-irUZZZ4q'E";y2iP~}&O?9xy}}u,-YZlXX__aب9a_]ZZaؿ>5r~e/ܾ0nY>N#Pt*۳g͠\]vډVȠA}EKس:~5xy辐oKoKH[\j FrI~ð8:aÇGnj_XzժU3N9PCVPfF?o)N/7ۻ^iJ^Q^{[Z*dwWQQY$;;/7nٳgM]z ð#]`v;1a8 ÒLfii wKP2${Ǎ[UU7\夝vj/۵{)7n^%—UTT|#/>}|ðCӟ֦.ayꓔC~χ<״qv B!ɓYenf0Ǐx_6"`]Q"۫W5k .a_ٳ׫W//^ 0abbzѣAMM% >~&ٰ!`q TTT\d/8{A_@²tIZ-ѣG~?Vɓ޵Ǐ>|ؾcSoG9ˈNp&/ΣX=p>'(QGjkkKKK6n Y=gnp𺢢B^nnf܋!0{܃?;9a%KU[ӳgOױ\G\/wvUUY8ðÝ!1~˗X /d߾ o}СD||~puܷR=vǎGϮAozI]}]bB;vk|9wV8*zGӚt+$Қt+$Қt+$Қt+&["]-fo.,/^8<ܽ{g KH~w4jkKw{N;xЕ9vHlhlX{ҕ eBHr~K^xG+[Y%yBtI?}更 ;l9ZD\]]/@k< ޽011/64(UGξfaaYoQ A4 Os8</A4Ŋd9TPPaSSC$$VQC Ȕĝοz̙5iYؾ=&3ܜ[mh2226nX__?q6[' J Yiӆ%n߾FN">'%uVXX-[%gdXϞ=_}35 ޽{۶m311 痔oիWS(ϗ-[fhh>yb- o>]XUUuMHHH~]޽=<<}.--Ȩа2eʠA}- $χ2̽{J#===00=zܹs&&&۷oǟM<nݺ%0f|:;;;;;233E;@jj X,VLL F JMMի'O_:uj߾}x۷'%%_z5<<ĉͽj cdɒHl~~~L&bbb`=zHMM#|ѣGT*u_<^(#>>>:::ZZZɓ|嗔8:}4x{{kiiikkL&F= Ȋ+(ʯ!)77|}}3f@II wñի~^$''$''@vv5o߾*7:"#*8&mIDATeʔ~~eΐEL?sPPжmll$#.]&-@vʔ)ϟu떻;.Qjjj999)))&Ln*...++4hlj(ҦCRt'88هB4{3ŝ2eʊ+8ƍ>|(*߿?4]p ^xq޽ :dEmMllluu7|SUUuY`nnN0~Haa!*Z9{ 6l"d!W ݶm۽{… h|>Çx9::6 m\~]WW믿<==TjxxxYYYEEEdd$J7og(֭{aUUNѣXXXH7= C*W ߱cG||<XZZ8pxڵ&M{ED 6LOOOˈ߿:srrP( ɉkhhw8vsxvf~w͙3gUΝxI&ݻw̘1r^IN|?~\SSDk{xzz"}t" JܻUSSzӻnݺSXbڴimtD[pEMMݻնqٳ,#ښ^&E$ H@A$ D"ٳ̴BBs|;wh)::ڞRߙ. Dvfb?~\uӟTl )ߊ´TV.\3ȼ}v:֭j_kk5?o/ٻvҤ^Bf- CW::gnjadի&~6r!11 ޿jk^Z[KmO3 tu5kUe ?|}C]XSCԬi39R#5[?>}[IIQvtX S +,i˗][E9kz-..=llxwVٔ-[PVV{irFS9o+$ĩS2ʩSB )66sSӦq._ϚIJa}9vqŅ{mJ6)2%bk{@ymRU^PS")ooWTa 傞;xy/\_N0aSӦqBBTjj( oo6x{#"le'O:{F/LJd%+܃U?dS%l350ܿP(l @C5 26/`de)M9YYJQC S"cp]]&􈋣UUQlʓ'^^j[J__il6R=<0 J}= ҥ 7 RW bLM 6{7s|6ʢ aNLIzhAuO`T33e˖ᇟ?O߼YRB0eG>0nFZ<;FNNesN3R60qPx"A$ H"D$ H@ H@tw%&(tM]P/D$ H@A@2ÃӧOd)mضسvZrIJJr4ܽ{}|Bt(Hj/ܺukҤImȎ>DyuNNN>}+WyPA6~6?uǏ{ٳ7oVVV㹔qՍ/o޼ٳϟ?WRR8pĞ9EZn:;wv t:]WWwԨQ=N'# D>K.7N/^C_ӧO7lPTTiӦ7o;v,(((77w߾}g?}t@@K<==SSSCBBC_I%]v]zSN #D|υDTرc`رT*ϸC_ĢETUU .\PUUuĈ E"_~%N:u*]rKL+{eoow/y&2tXd64YYY%%%={^zؤdgg8ȲRATQQ@tSSӼ@adddee&@ |㩩|0i6RLd g\(w0?~,/..H?<{*_;<==g̘.Ə Odѐ.r9CsfϚ5ݻ˖-fffمxuVs@mmmrrݻϚ2gx:aCQQ>y<t.ѣG>}>|H`0o >/_+Wp8b; Ld?;00}y{;+]"xE/g4#>ѣŋ}~ӧݻwܹ;Q`"̝;,V9.,ڣGW3.9MWܼM'F!ڂw*LL KD,,,/AA4 Os8<o h8s&H"I;8A/@A4bB6fssr^nʒHMUEP*|"[' J YiӆwPkaooaohР3DՍ]\4'_ D@IeM7hڸqܬʗ/oHN_brV9y:q"GNމ$y%&h"Ż^^l)S866o_=(((EA4"!!_Vhk F ݠє%" 1q}b\-F f}jݺ$D#NUW YlbU4M^.]Un ALӼ/Gg!D{"ϣo-74oE.WE5_.--}}m]E4BI:k7f}#*AE$ H@A S"vv)Q ЦA$ 7i,VgY|>﫯L=<8;%=ɓG,Vd^?`fA&$\w> $:u{ZY͛W++MM45mȚBW-ESyG=w.|qqG|Tjj +X11Wi4ZPd9O|/$d_:um߾n޼KOڰaGQQM߼)>v\Pܜ}]=A?|>o bb0&Ŋ>>ttziix{'OʛRKKG[*\ZhڰaN…KUUFpP(])R$JUw())&3۷/55.)j7EYp)F)??.>7Q>T*5<eTy$G={!DE(+/u.]54C8zԱk|ұ]hQv:y2sߵ~'{Spo֯>gD}s,zäK }"gϲ""yw"VUt`؉D+(  [49oWp¹sry!!PX> AV| Õ+$$&v-x,8׮)n{B/- Ǝ2ph AH$$@YY# HHkk40T04AV9I'Oe`|`JwZWEkHX[5895:9AN\^,n^^S 8;I9ii0o^Q|ֺ'm\D"㶜s `l T WOi țޯ`h0`pɄJ)薕XYxÇÚ5D'2>#w8"K@@ K 76Ǐ">yx{PW55$']6mǏ͆ZHJk E<<,bKY~ 8+׷}|`^HI !:#G֭c@66b5+0v(|G^!H@A$ IA$ H":V`"׻7ŐV'X@б7l6} 7@XMEG Ld0O{s=[>S舁"`z8yDj!~ Q;%{ CC07իV9HQM#&eYQx 66PXw#H 舁x`hFEjj=t8+p~(NyyCAaS޿m 1޽>dgH@G L'9,-QMuur ޾@(HS[ {U(C 0Qd0*ܿOr.(KxNW2鈁zO  3f ᯿UZBXTT@}=ܸTP;wY9s\XG3fH LoGUT@Oll`  lK0L8t 6oe& Eg[z;fcc rѸ8ujrCC4BWWTI77.<}8^Zڿ+&bd2ΜI*((0!BEA Dؾ=&3ܜ[PChķڝ-ؼs@c`Ź"00OO ȵkO>BIhe{D+yy@W=A|^Nx@vv mժćZ`D# {kwwakkVPP"EOAB|v$TWׅ5de }&튜޾-|קAþ<%׮u*$ H"D$Ȕ-ёA$ -}bE>{cئ-ڵ[Ϝ͛WzcNl'ѢZ$==50>wsML̷o_y޽}==%gG$q3::_U7n\9:I>>ttzJ?O6IꞈDR$JEw())eo~ ϟ?kC+]tGMMvEOܿ_|_03O;C",\FED?|x_4?}(//;zg={aKΎhZXZ9pS֮]ZSIKKv"Ǐf͒׺zmC}NA;Mwrv~D$8t^P- IA$ D()L6Z;m?OEQ-Ϩ]Z .AqqÔʈnMu;hoZ@his`(00ccX>|h?Ʀa9 8vv©Y > \G 11¼755<C9D E#? ;wBl,C|<8;ۡD U`i 62(ؠQͶOY{+1}¤5hGCgPA` >w/-U[̘1Ԁ?}Nmz.?(0V HAL[s"6>G9L`B$R1ix ޹D; @ "j Anz;/h)H"PCǏU߾@B:7{(@ B*G$DSNLav$$Ǐߜ8q6$hӧ&O&*\IENDB`code-001c16ac87ec/doc/images/index_logged_out.png0000644000000000000000000024356715046233326020005 0ustar 00000000000000PNG  IHDR? IDATxwXI  (x" ϓӳa/^iٱ`ATb(EigH@-1$ gl6o&$C14u)@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2@ 2PKHx񓦮E8rӧh DyY3"rP(BH4?0=0z&RC=fܥ!N"?);O[( ¦Q]S>}4uE~R} j'&&6aM%$$:u͛7eeeK$Ҵ3Dޠ%ha1۷WZԵ$&&^|955Jjjj,^+222~wє [m ;s6(rB0|yӦM RQ7 Pm۶ϋ&VVV#ZFU;ǧI*?-ȵiյ>C~lYYYݍŋx#GoM[n޼)xM$Pvܬm9^3<䩒ĭD7ꇘre2,V?DӚ .֭kݺ5BJN>=00j`㋋eVUU*..wqqiʚOFb*j9&'OE|`Xjjj۷ׯ߸q444j)"s 7NDEEEGG{`tejjj9CLnٲ`{EDDH$++3fK,<;Bhȑ?~ĖCCCw훛62}ܹ#={6{l,˗e6StҥKmۆC $3~0aϾLBHGGwðM|~pl6k௃nWSSGlܰ<WA;۴i2`j#~]f.۾m |ނKf>'Ï߷˗V;:lX 4SNvZnnnee%/**z=<<diiiw~eYY/++KNN޽{GZZZ69x=9iҤ۷?yׯ<<%%e׮]&Mz@@t&ϖ-[v˗/EEE~… <!{jj*O[+4 ز1 X8%9Cϕ+%&>aVݳ+5%&1[7cf9m'/?}aޱ㦍k>%eԵo;߼rFt$$ğ9{!E~ 6ݻfűK.ņrE_TTxB={IzFVҋW%ئ^Nvv 7hCŗ?~g#G9#$&>K\n@_MS䉼E5zh<  CC?}tXX#6r{!"DGEuM5՝4i.B(::Zt<ޢV1_9r<̠skQ<O;vuV6i_WdggxK9Fh9V-"1cmذӧeee۶n4 N:U>??{i3alZ={@ZX\Y>HTk׮^^^{޷o JwF Tggg2}WIJJȼR6~~~???<n J#3]pɵkQC jc1a貲!UfamZ,]6hukm:9uc/$%`YǑ#p70P8 P( .3gΫW޿]Zpa}744'1bش]ׯ+W~A$F'm @i$ٳWϞ+&$iY^s] oo2EE&W{媿E#&7PJ;vѣGr|Y6X`$snp4Mld @ߗi}wm6c#:Tt[[[l;h46ny޾ ňN#پ}{o.1'#T虑͍X u3ycǎ%'' u-|m5{-9–.`ڞ ВZl=`mm/:t$''۷O==='**QӧOCCC'NXת6ǏO<ҥKUUU\.7==}xQF)V={bOg0b.zoMMMl\T~ 4M37 Fl;ZOEHOO8RWW>|xhh(f͚5kS~VBBB|}} ͛'uAAA%t NΦӧO66mZXXXmuuu__|6~׳ϟ?jȑƍSX^^z^).Ot\啢2dJ@R ؍:4@I\,y:{233 y<ĉ3gTUUqFnnnEE<|\\\VVVyyZ;n8SMz{Ç~Z XXXxzzJB]t9{Kbcc333}F&[nݡC{{׵ k˖-_~f0006l<&$P׽sӅDo֭{jYZZZFs >y@ck7& @ q dA!>K;Uj*5ѦJ9|x:S %1E %ÎLi.\!Hc4]4uuQlwrb_,-F"5LLڮ^=v~PZzWiVɎ{2~6/3Ξ}}o?zVr5^x| (11OBS:|Bt|@Z8Aur4BhPg:24342OS׫zye+~~TTTBZZ{mUk IZyՙ'ٱ.Y⩴~Tel?lXߛ7ӳ>.40hgtܝwl## ~B$%_ oٲ?sÇ/Dt˃߽ҧO7lգGa;v,SF #vW2##o}MLڎ㊽hp%;Çu67o*A|!DRZqv6~J $ǏGfki>]5`KbB1X]V3gOu|0~k? ^L}.Bxvvu FMз|ӧo;"^bea֬qmm;Pd%@б9CKKK555u6bĈ]=eE,%%%ĉo޼۷8qb~d(m'PJ[e466!4`@OЀWcc'N}.篿vhM333[$WQ:efw y߽!믽r.g`wNݻ߿GöD@[~UjjG\ |9337A9q@9ԘoXillJ! _~;{KT*XyׯJyMI7PIɷ/h~dG}vSWg|k)BŪxDg[ӧo3ǵnJ2e$BY4Z5K3l$8>>iڽ7no8i;4:6lX?PBB&LJy!Aut4ްa7B=/ֶ^UǺÙ3B)#ut44cP(MP? Vnp.B?Ghjy͛hdGRuFefa#45ckBT*UWWU*Dx?~/XM6!//7o&'g\]^^q],҈/_f,L޿]vF32jcmm>zkÞՙ,V񧧱wP,$55m-`$Ձh_gCO33013v@P(7#OV<##cٲet:n„ [&^E,==!%'{J騴=$"ވ'&&{cǯ:ݿ,:Qb)rn;dH{M5ϡ9*O F00ر݆ ! :uĉC罹*Ə 0>>S""---{惿R#UǏSӳ "ahR hcJyLSzy^:,,˗߿}ZZݻW;1.]RSPbA#}M*2nܯ#v":vF,B?~ iƌ1T*4%י2fڼm99nLܶm Z[&%y(9-=F۶Y0IM}^w!dm !KlرT*!mbUTT6,ҥSBl6ٳW;vXFH0b˓'.޽-Q~033~CvǎMBٟBo(y> Vnꜛ!C^o|رo(FMEQ؝:6lKt1Q_?㗖?zv^ߏ ĉI$ұcWJK?E"<<)(y> Vn;v Bĉ%%eǎ]~+)vDJXyoL&SCC!dii)sUǎ322.]4jԨ;?\|yhh^틋_xq5,AB!3݇uVTf여};;w{dשٳwn=\^24ԛ8q0s!N]_hr?z:uQ(dl$ӣG6mt B%4sΝͶlY|k66'7EMAg`ѣׯUTp|C#;"IGCΟ:u3< v8!ZlM,tw3khRի;'dy:/sl/]*/3glB]UU\?ÇY% NsM{-Uu2 !K]/"_U1*SP@ZimզNvڅ >rM__fD-/7RSNN5 ]&IRS]WW7pd޽k VYɝ7oU*ܮefdlW;ឞC:346rd?P\\R= n3TzuEǎ5c 3GڶbBC3gV"fά KK8;KJMMXRB&~JRWIV3ջt_XH \_='{ K/AD @%Ry6];(ĉ/^d?ϖS͂1o??&|sg5a.]MMVVPzj*y*{Uj*A *>Z{ݻGޝ/1G(U t!B(!r raEG3dcמ_xAƆw=&ORQQtf!ۏA""6]ʕ PfAF} }@[l6e ul__fb"EϞQ|}sl5jT֭STR(!D)S*oW>\T?իU##i$>Μ^W!2`FI !ݼI;fĉqq E qW2\.JJ"/[DrXbӧJfbc)'VO^r25=&O ȑUKpfP32ҙ=[m:Lnfa4eϞsodx #\SS !wd~=N׻)`HN#"##>?dڣGўwܩ΂ex߾~}0v-Kv-ĉxXi8p >߮q'MM?!Vܹj7oȋ3ǎΟ\!hrb7\Ƨ&ge۶Gܹ%Dފ𨒝y?PmsƼPc:r~ -=ڶ8;LՋX)N !eFӀ(J?/S[[Jз NbZjv)և8̏UVVaV9&jݦyd̅ B!x6eLȈOedU.[X-,^^M\cf3gh> al.NL,D8scc>Vnn@ƹs4ȑUєP)ׯSh؟yy*y+s$m'LZu$M&aa?N?ɓ~'O;wăne;poԩիþ}XSV._>WgozCx3kk6:@m2"Aɥq(t6uq j:|իFCm7ndGGWW8 b;:h4 dGG tܼIE !޽xTww.$&|>to3L&Mx׿~jw&-[6ˆJPKK=}!'>>廸թq׬laaL,]: R6H9U t( -3 s?oUU;ݝrڵ̅ Ock;u ~lvusе3ի!FU]L?*6/=zL uE$޾{kժzBVB޽{T77n JC"h۷OkɞE$URcƬ(''!ьCϞ{#B|ZZjXf 9fK][Hgv#b7Sbrs tu5<<  K+ u.313&9{ UUSiTl՝;ϟ+*֦֨Qￆ֭Ki5fL7uc tt> ՌǏ)ΝU[ ҍTd}}ɓkҷne ˖q<=48{7#7WHlkrA `Jv 8eʹk::wi4 vB> eGZDB[+I/x;wVo%!F۵Ү`bΔ)u.U_rذiQA2z@ڱlƇ$ɓ4uu4bwӦ &n&8䬃~W0,&3X VΞlνH{իsrx.AOˈ|{ދEEeVy-N6g"YTzuEllMd&q|بQUwRX,Rh(}J̙2RZYr|v$L8'wwǀȌ<.# s3rwwש玮\ylCi:а_;vɮ'N,?xpW%n5kɓ+]d퓐G6xq-KLJz?&NbŊ?yڶšC++i%0 ]U=vvbc/]zo||%#"V.Y2qqOOܒ +է۷kVdg?_S{2oϏSڱq:UZv1`< `\JYիԠ ơC!! 4wMsNENNɳge%KKرysEVVijjYǎ#׬Q/NffiJJ[VI6n~6R|g[w/]t/ǎGHGS уUAkN gDĵv'Nn ٸ3aa7iI?>zܹ8qI%7P"jDhWy1yO'>ֹJ.գ㦦++Ah(=5W=SńJhh0c`yy8єjGsЋt\…{R):x{V8:Z2t*ܩѲervT*EWWѯ\yީV&W>3ge;*laa4gΰGrY+,srTݹB ?z҃+\\xt:Qp Kf6K]lvphXBYHH= ݣ/(/M]WWS*wWՖ3\6e<:|&NVҎ:IK+4N*D#K[WI\[i(y򈑿 -eiiLT~e$|{b<~0={2['bmğ]J , #ʪU}dD^ T= e)իkNdFUmެ|yB 2rvC$\Ξ .=wNgѣ+*maffvرM:xTT'ݸq'qk|id]JeCZǭ[O3pڻwNvЦJJXwޕh >|ٹ Ʀ=u3rY)3fThQգ_?KOI!'$Gp _dʔYHj*Yl+vMS\8Q5y! R$n%STdnENՖ?7gzh(!t D`c#biǒ H6޽KW.}pRb$qm#FN&[sCp67o+Lp"z55kۄhR[ߎ-_IZYONXffVæ6z{sƏ6jT֭JBSV8ProFD7mbN/&D ~k|gbq6mT ǟ0a<kl޼ã*6իU,H (/^Q")Q;3곡[uG3>V108@3G򩵮Rm3fu*76B.t#( H7s/[llϷ)\FL.yS=B.2mZiO >n[==AvaXɏۗ PHJPFN׮=| S۶U Ѩ,eB|D ocss?Y[B̬Y[З/ŋy~ߓwSjj}{ׯs3_ebխ[GWrڷ7sS*,-%aÄyogǷ#TһAnkˏ $ޞOoQ]]y_ŶR`udSY@8ֲ_FB" +CCi#FpssUF:$X-G($2Y^ݺxy!8dA I\[iTV"6Kz-eg\.z뫺paB,ķJL$ɿ:UE9D ҹseLGR6q㪢;w2MHK8CCA|<&kk~PnޤΝ`u x HJ;ɣV qݔSsso ηFzۚj4~~ʯK91hZӧx1aO:..vGR"v~G<ۻ̛7spvڌ\0e[Hů_ BllT'fd' ;v43 s 9;۰XEEezz#F89R"J ܷ/_s'חioYUE/^\9kV'WD *ݛwx5nnyS}_6,ކ 72=# {w;~",5K i/gHBF▕fP?ŜKuu*YO%%$mmEf5`S＼ICR6* Gʕ&aK9s0?}R %_p0חieEGu$XXMpԮ+Hp@V/JZްb[:!8-o :WXX=fL5TcV~-]Ap8t:! Ν;KJڍTr˓iǎ v͗3ѷI"<1DWWH< j:Z'OEW,[44Զ^f_ٳ5[qul+rEm[SSS ~0-suxȈسg y3u|+O(߱q:_;`FJ/$[W0`ƶm>#nߦ.[\"+ؚBBB۷K55w#> C I IDAT'#4\:oBAoS 7Nz`ݬaøt:ڕ k֚:5tҤ*:]h` g_ROٓGBP#(ݿ?NGК>ՋG6m764{P**twU>JM-,\V%%==uuuj~MV.dZ[kiӮvaa;lmyHI!] S'>-ħ3 衩ݭfDMb|j۶Z:iN>wֿ$Znzz=zhՔ cU j~vvUq}MHJ=>{ѶȑiihʰaFFZFFZ5Y֮A0ADK__E/ \Mի+bc[k1=9S]]]-//_"D## "mjٵq+/AV@Uj<h*ᠵk;99%Ϟih,.}*5(q+/vHCLl仸'nwRcqrrJY.]0f啄vbJ=ֶc}抬Բ#FY_Ҕ2==7a+ B4@_~,RS_ Tޥ!"-[$TX -)66G..W,V2Xuگ #22kggǷ#TһDj&l32=#.\(XYkk~PnޤΝK4 `A%^rb"GvCCA|}JDl6)6Q{׼y__fREIIe˘l%q u:ŅfjQEOPfάZ\bbb(5Mpp]#? *gRU12rFa/ʊInG{(nYi S11,^YT|9s0?}R %ކ 72IhU1;[ZJOULLsV^*s{,)!ik7̼:wN/^di_r֬ھHR{+UH@p8t:! Ν;KJy(ڍT2h}L5j}ȭW eR;K>l̙|^CdooT)Pȉ4OOE6&ϓSRSöC͑+o$TڶLR5o uyܿ_ar9 {L/զe8x(!7yxTyxp5Q䝜:sƬr mq.wp讄_ `|G!cP(? Hv;rh}=z2.6Ϳ5^};gfWNMƍq-K/^4%5/_$5 sR_F] }f,ݬQ];A7El:ΝؽFs8+VmܴU[[!4c]Bb^8 !fOω+Vտ N3ݩS߽{go?zpxڕRTUU?TPohhy?A""Ӈ7@-[r06J/DP{vh |ѣWccB11omfB2OMMێl/ZU^}Jgh_+VL <歧ek@ƒěut.kiic aEe"P 6lϞ'/j-c v?j{_^o$HDRƼ?<| KLzu+**߾˩k'!H$q7 ߀OjyȚM\@4sJʻUx{WDDl233ܶؽ{OE;woIgl4ipRRz``8WЄ8ƵngKYsmHw޽CfɥEKdZ*[&J[]VV.m[he+EHID soLcaAk8s|ygsΈY;C^4!+6w¹n0bZY "}f𪪪Mz{9jtlW@:2.vϨQn'²=+`<>`e /F:mڵ+\NAAeKZ y}XX !Կ>@RPPoe˦M[*/ӯ_c@C!*uhUpѿ|0ȨhK c(Є ^KcGrۼ)E 8;ؾeH7`+Ǻ{䥉iDo8+÷[rϞݽzZ0 I͙=⭹E i3o#qL&K(wԩjj idI\ y=f1bBO~TQQucVFF<->ZZ.N[,ĕVV)g+~&D"- X0`1~Dd2g9**4˗ɓ7עF=(ghkmu}tXffl[VVsR&S#I}CgDKgΜ@R5ǯz?̧{wuPiG׼kPh}R/'MuMHH8gίzz=&OW($"bS׬[_ߠacc:{'|O?/^ [3oŃ}}@5]is_77{77{lw>}z K];Or^xJ3oŃٲД)WVƦ"nQoXVqs߳'5F333\vy JKM5ʭ"_ϴʹuťM g΃PKWak3:PdTt td26qp V뀽 Ts_׼ASSSZZZm@:&tjOX }6odR4ͼ/_<ښfJ(R7o](7%rw$fo&ii=/;1k H5A"_09tU|>:t~ӧd&ԧՕ;{6{pnKCikkUWwĿ! k;mQ6ܧO [Jr䈈dI]ZʕN (/01ߦtdn/ښ5l{N{,YⓑqO!'Mr]~!J14]|wϛ嗘 ^@O{A EĀ |M@ D&+ЌG&i}}Ö-;{6!_WWJJz5BtboMMu$r7lIO(-R)vvyEZ-4:w?YZNGGlW_zuqu( 55Nv}UUVs~EӰ˗KIɪ{NK>}򃮮rr(Re.жneSzX1-,:vL%"QVFۗ˅ ;OP?̜>1*11W}.eΚո^[[z~>EEE0f 72BAܩC \]M6;ڂ ҎDnĉMv--*Eآ5I;d&)@!g!BhR HH_tSWUbC(qm i ?'"@]Ȏf!AEE͑#nj+3gǏ ~~L+ޯܧd/Zend[wg z Ʀ\]LM ۗjxQ[lwݧ|5{2""ICC!m /!!i4jqqHy>}y?~lHH8zr@'Bƍܴ!!{GE 7|2D|$CeH^DE5,Znisr⚛~PǍPQxzrBHF|| Cjv_P={ꝜI]vv܇橩ɓ'vFl2),L&N9B i9Bhk Bch[ܼq#cFDD~gP `:TO =0f&Ft⎟sK6%mXiqrr&'gL26]TT,m8Apv ߴ9'N8Ej)・M rT7Ѣa,Wĉ{.=v;w[?+[Ogƻ<4tFP9ӧIk{!qh--9s_B,v4˖;v+qtTShss+H l̘4UGG# Ev|2y{x8 ._]dRii|7U]h͚FuvwoaăggեB=XMְX.w*Lϟ޺;X&LƦ55u =X[ִ2.4Xq@sVUxzrZ^u'BQOϋw<~Lqv ;;K_#ʨQJKl77Qupv?Қ JZѺY HqFZⷢCu*ꭴ 8ApᶆsviR9qjI9Evpp @!2d`38ŋwμŘ'6#WfilA" $B@_?~|5ҼhG>xPիxMn#ҎƢE]$x߾@W=P@ 8ԫ"6ong_FoڵAA,ѻJdK\ڋZxL mDڰ3ouAZmzNlSubvwwG T/cEEҮ6w'37nCvmRQ56*$Il"njiLLN޹3 ))Kb'OJg߃F"?.~DfӲ^nnSͼc޲ۆ?r?ZQAnFߧHp ?4cmkʒPjeſqʾ:a;۷UU/iP˜|:]&z!``^p0С̏tu3v4g"@;iq^ ?H&+q6IJ\O3l////~￟݅qao'L`<<LB͗,]:yđVzՙ/줶l9p8/^GExx yGY,ýETT ))ڼyn>:m;M\[[K##SE=zh<~Rt=mۑ#p,cXQx1L&B==W(KN޹S{ia7ߌؿ篹\ ,wK8q8@;V%Z}="PS_)իzBkר7*VP_ ޥJEh(+$Du* ɁbBCޥ #,^̒0,`G߷p!KxHzM $]H[Xճ :Rf&_?Si;"wzժ*nߖjҜq{e J38ٳqqᶆsv ޴'y">Ev|rm9k ?dk֬ ޲ePNNֶm ٵ+^ lܸ?ډGW ?}ām;*Oz@ 8q-?!dhs!>pԵR̙ܿ\\$CLBBB( WĿ[Q~;.|``4W5*q=kGttJ[[ٳɉexdfAAJr݅Lڿy!fn^]]1#"j{Қ8qġC"77[kW*$??WOmקWY\l IDATB2!07okƙ܍KСɱ4zYȈt)srɓ?_T>m|5쭂˖1/67k{NI 7Aqs kPa3h˗ff[ ,tGێm,08_wv:ulNw˼); h?2y߽{/'mm@fش{pW va9n#` oM]\\-sqq7+W$%]y]Ϟӧ3rv#Jz.aM5&$\GwʔQQ@GӶOX._yb2cݺ fH$i[ݾsg&;v,[it@%e7ZZs~JJ̼jtCs|vH3odlGtŋWD*,|_hjj6"@'%zQ: yPBq!L&|6}|\t+CPIca3otЙkkj>>|!4e;!p*bbNnU;r$i` @<<^gΜ_+*އL$4tƐ!WGF&N4Vt+Gǁ3޼3իxx8"d8:4x {}XR}}@1nnnnB}lD@ANi˖CϞrTwߍSvRyI*.~M ׮d̼tJ΃+; h׼,K׼hpRSSZZZm@:&tjOX 5o̼h0ݸb3flHhR^^ITTʜ9;L`Xy8*_}-)IZ+A(X'lܦr#hgy:Zɧ>/Zf'2-N[f:!va;;5k)/{ӧD"˳m KK۠,|ݻ x7)aaQliPJ>Zp 5o[ǜ[w- 2*QY' jFtСfyJ'Mr]~!J14]|wFg[|]`,i >sjjww 4+k,s_ܽK6K6 s>ty;88!"+峵qZ11#ĤO|1]B![oزe~g攔T D4?OIIY/^Fٙ.^쭩D.Z-_>T*t"O:HKۀKw.a;w,-}?}իÇ/=yRpz؄O'O^r循*}s'/UUQWW)6p.=}fe]]M__D!UXݽ.X2nI-\#\((]˸ubx,??v~D"}l,S2Iڎ'O(zzfN {mVF~>wo3?g8PCϧƌFFؽ;*ݺ965IoaƫW}K2gjJ1FYo_~PSb8iV47D8/ &^yݻ=zt5vh2[%%l675u=6 t'~:svrS׫jEDĶ.a+YPVciʌ&_4]]͢rssᚢ7eeU+9:u;mJJE^L&;1uG{ppMllʕ5*0T}VM&=߽tPСf^UFD$ih9:Z"m;5<$d2F-..?}iCmhΛ7džG/x"nMK2ظwqqyTTṗ))!!LLwLb0TFQo~Hժ271C- }P=.xÐ8Fd+2`gǥ}>f-4TuϞz''ni)yv6cȠW?n2gӓ'oȆ!C>TI-!+3Fc:͵դ60""$sʮ]z;;ÇylPz:-2_gc{`Z6#p:HD7|ሏϧO\̷>EEoR#F 15CR36ӊa@CN䬐IƽʣzΉ.Q8G'U";5ݻ7>=bCet9n%2eԮ]֍y_xq:+[Ooߊ64tr߾!:sKwnkhشf([DiiϙՂZ^rr%bcn-۳,RM277Xb ˰ŋwc#ř39wssE<--",, NFd][KёpUG_]M"'GCC9RG|[":|Ν77.B̌(ƞ=جƆw@]pQ!97OСz BHWWiS݅EBނC5$μccQQ \72a66gGDE'_\4" ICdG#>>/Ziaa0\ĉYp!agm>ӁiglayoؔωrKΑIHN oM]\\-sqqrfc VUI$aMMAu5IWW|=Iڍ͟vsӘ8mo5kh'-Kv#==M @Brny--A}}{qjF}'OȮMru6V}YBq6#p:HD7|ᤍϢ):HZ[~45~Hagm>ӁCq[ns"8sdJ0rw|F yjaa Z!#Wfi48m"?H W37wѣm<(_q+jIN#@+Ґy (/r8&`\}"1g= AK#ȝ̼h቏XW&XiJJs6oۧNK#˳69zrmm=/LKinGX ÏaE=*f8L&B==;KN޹S{ia7ߌؿ篹\ ,wK8qyxpƎzzvzZ_O']J즩)5qs_ZUEpےWʢ64H~$ϱggS NCCY!!ׯSlTXH z5_TܡXt_]91p /2^SCb2I//'0v.AwRBBT/n<AA+",jbNIi b?Y{,.ܷ:K3l ͵b'x:svq6k ND?-ܩ/_;$$d4ssg{{saiBBB( 7MV[mqq9^߾~~QQY<޿(?zښ̞MNL(((ffɓeT*ʪʕw2iE" zΚ5.:qpuTWnjHKk]ŠlY,ή]\<^ٲ!5UeƣG:Bݝojvvl%oR…팻w4ɉV$*, Y :g_T>m|Xѣ763磡Cy,Luj`T)mwzR@>e˘}|8FFK˗\4" 4 D8@sTTw5={v2e8&`\+}18gggzfddreem^Z.p%miNd2t:BԩˢeGiOX""],qkj]--6ٵ+5&G mVu|?))IHQ#pK[uSa5~1Z!>Mh[i_Wxⷱƍ]]aڴn55]p [wжLl9Q^^GGcĉmY~3 'yжF=VY@G`PVin\)"[@!]]J׼hpo\oNbjtv'x J3o̼to͘7LٹҏIk_yfn5fƟ҈Gg-:򷷝{L"msnZ0%`۵+MSS}yND*$JIsƎ夦O*+I7n>a4…ʳ2lɧu=-HhxKSaS @ٳ?ʽ{#Gr +϶Vugo{ ]u ̼Ysi5?wo;Ǐg>U×<)pFF|}]\]b%-oزe~JJ*lnjzЕ+O^UU |:yڕ+UU#FX͝NϿz%=|@vu"ϞҌ ږ- Mkkkk8PCϧƌFF) -Bc#1Q[74q"gӦ55̰Ħ :ic*2r߾ ̰pK0+(]˸ubx,??6ҺZbźer5im]#/\x򄢧gljkk_Kdj$v~i B_߰'>}Jٙ.Z䩩y$eƊpF{eI DvlNIIB$KK󿮮kX!.]{.C۹E` oʔQY3˗1JCC޽w :իʈ$ 5GGKжm'LѨO:0-mC'B())+(S>T*!499+$dqdPO;o2uZ$&̚–gb;F߰q4th"w7Ab=2a0՟~RKH#117o&mذр l7=Ɉ=|H]@xK$=6cZ@Сz:]%&&vu/Zh=NNR l/2`gǥEZ RRLM ۗjwXظ?K^)pRocJJE^L&;1uG{ppMllʕ!23dL21/**߹3P9rr 1vK#qTvސ!, _pk8B(99{ɒo@Ql߱cWj5jjtbnnbiq },- !inn@Q,, - l̘4UGG# <;ф&JKDBUU555ͧC窨 ]]M WRo[;mN͏h8s&3EG#"y**)y&J {{ޑ#-*bZ-7NzTTNGfflwoanԪ.WN0/FR3_mA^⸍dJ~CC'[[hT 3?}j $޽KOmiE`ٳ9NxF'PdTt{%|6X&Mrϛ˖!nKX![O$_1a°NNV66uu5 25#ZT\ں𣵵p.!!޽55u|>_4; Gz88p\yxpBCvPZ![[޵kS<Ზ2}qjF"_ޥUǏ)M{qvH_a|ĉl{{ިQ\CC0wu2jT<яV*P.nTY,ظ38ऄ"34)\VWg >[#콒 4..>A[qQ fF:yut4oM8[/_`4dG>xPGfW0b)IʔX[[Ξdh(ի}D+9#lϾvߴkUX!!L5wuvoNBg vhV*hgϏ=I!6n 8v"kW8:x h$oϟw>a75⍴LLN޹3 ))KJl"X//c^^pɓٳѨǏetߓ23/_~+.p*qݝh~䘔 IDAT9msraaLSS>.@eg~UUM$c2# I'E]n, XH" 7JBkTVVٺ88<θ3+ NJ-:02-݅qoÂ3oVFt~aj(ӦMs;rW<|X~ + ?Q1a25^C㗢o 8ٳ2.WP*..]Xԯ^rr֧O l6ΝݻO_钒Tӽg"MM9ҥkרV?}"O_蓈ȋԐLŋŋ[󀣛wzժ*nq@}}~v6gZB){+NVWf>2#geQHuuLj~|[խ9 Q~fBr`E8Am6xѣkk\^~~iddJ 86h,8)D{x\]t?҂]sGr 0NZ@&utz͟*{ ڎ[SRd{?g^[{HQ(q?N[ Nbjtv'Z7ttl6wdC~!!Z "o袪V~?G(K^^ɹs~iΞ?:< G"'Hgn޼~hlIIQ3f,?lêUiiNj^H$+AԼOL̙^2H.dzڂr-v%RNN߳gO ,,={jk;EASTУGE >;j{ཷE]wq<`˳f-ڿl6lkJ}58EAlr11g*|dHDSP['^dBC:R(Ki.0`)3[PqB'زe-V3U.ێ@ |I Kֲ'uum;BFj5|t}Ri[G'eg@<?0pBho։3&+ͨYY42gރ"76^ ݲ!@~L{!CteyyPU?߿_P]]5V71ٍ9@y?|t{-t:-fY:UM|~>>U|7߄%,ᢸ} KA>@NFG^H,-(xeY?oOM@kޑ;}6u.5?}W\!pƍI5^z:~bv#7BSRTz~NϞ=z4l}3kns Mۊ,lڴ^UU sQ5JCþz##Jl]>زMM-l`x\]5֩QxL--6 oNbjtv'w=KKK咗/{)\_V [.--E"zшB3oO/[«*++7 k-WUUUm` $μ--E?3}ǸQz/]U^thgoPTyfVAEq#wŊgTQ!/JUUѾaDE̙sʔM{ϟ/K-JK֚1C£ZWJC2h>)uM At6m&!Dg0vDD!*,|q lb 8k ĉ̀!rs֬wnT#]{t͚&&}ƞraiih4Vv"hY׼e]n[?||cW_}:kKJZ|Сft:N j>kGz-:ُ9E4uT*PwIQH]`,;mcTVFu5}Jٙ.Z)VGtii? (&sN㙥tt4GֿzUy'OJ9Q/__WׁPSkWWUa5wWt: +|>>Nt7++?jxx %ؽj5/7_#c#1Q[74q"gӦ55 ﯏?}Jf2IUU5°knQY,/8]D& gXFGZ+W:uBqgnk8giMS9-iEBr";vyO6}[ f YTTnnn \STJKzzr̙WA8RR-27g2ىW׭;ڳg =kbcWV^uūK_J(l-6޻|AA>CzUhڶ턗4ͼCCL>v޼wG/x"nMK2ظwqqyTTṗ))!!LLwLb0TF%Q}NN9C_i3Fc:͵դ60""$֌4qiϘ>tN5L]s [ ЗFhiϙȔdɷÇѨ^رXQEEFX1EZec Ѩ::7oaϜ 477",Z)$=V`e_baaulN2ߵ!,L{y9ͭ6M zGD49CVsaħ'GCCyGH/&Oڰ3e P E'8s"8KSdծ׼cf3XU~roj?u.2J{jSaO2V5,+=ݺJ#篷n=!DjN0,$dM]]Mjj2{^SSE#'iee$\.)y;h'[!X+W8Pߢ E{GڸQ5#ZQAB̓~|ĉl{{ިQ\CCb@'mXiqߊMC46iHD"p9%aɘy.oĈ#F ~yjaxU?+Zqĉaadޯ"/S"[I=M ?Pi^4wѣm<(_q}2aY*\]^uQCBTq68I23?WY%KX<>efRD&H֛XHS 735u@8Q)q} &]_;$$d4ssg{{sDNH@ʕw{+?xŝ px}FE`EfyDGQ `mmMf&'&f 33__gɓeT*ʪʕw2iE" zΚ5NCIUUziM8СKX-ٵ+{ek byxh?[}h]w6di[pm U027+sb `oθ{J ^'3i$ٺ\YY۫qᶆsv ޴'y" @1=._p4kj)QKK"w=ovJ`}[@yGuU՞>^occύ7D6aqȸDPB#u~IG/W:;;-[N:q"ܾ aq~6KPQڰ-_6'dhѣm|`7Q( ލ'U/P.\@۶|Ի7ZMT(* ~EAAh9vAZݺX,de,A~~rNӥHGšXLTf m"2tL0:UۥDg<*.Fף1cV^~ĠqPA;ik#OOcÚ! 2A@pV(غJ"B[w-* Z.2TB]U"pTE%d#iBr3syϽ7nN΅xض | T۶a۷ Fa8;@!BIUд903;fΔ , rr<=a"pw:syw ׯ|Lu{BVVicpV-BeIN[!m^MIuaY] g90yxU^LT+岯%~<<\\`PVAA5B!ZRRN\\O_;o.KI9!Z{̭ׯٷo…?ݱCq-Jyfoc?Oph3tù/5Ɔ{_4cq{8vLz0XV=gOX~A~ O++ `Օ*0֮] BCcG; B5ފJPpw:thO&XZv={\VV9-^<ޚB![[ED?~AbX v{Nƙ6wo{?if {6ܓm ^p:*~aY7VVp)v46MmU>ϑ#aHBesyJH*H$]]gL!)\UפI#jop%Y{ȥW$3z9=gc DE ҈o(s1ridX"_"k"Isjd655:bx7))' J\M'!nn}VgOG8q/i4'o甗7337nPB1I'N\̼MOO5wJ77{@ cI#5Uw:g:]ݐz IDATfbEDVɦիWk{k+j4II-[h:$_+Rt4M2xx֯gvb| %EwFzYN.9sXSp$%%1hX /UB *5iGRU۱j=&*esD$/ȋ/_$GG~XחSXMR++ATt7nuu">|{Xے\]_ZաPvgzDHpQv'uZzA\Ϭ9GACPʮ]ELMoCzps%%LL1Y<''_as JϺ͵\+ÍpΕWl&!!^y>YVj,4签Pxx<χp(3uq<.WXXv/ }yQgt%7 sOgϼ[ZZv嗝;w8q?''56npTVcyl}}-[%j22=ܰ!3 `Xjs\)Zz_[. x񞲜d{{={s8ܝ;rΟq>2r|jp̋MoΝMjꂹs}22}'C|u똮|]]ߟSN)pnwqh4`ݺAx4 ,yuk%O(?![}W',j<ɗ:>MT\|Ҏ|6'.Kwo~ϞL 8矺={ *PVG;wCjy( ^!?>ܹ3ht+נ'O^~I75A76+U޵jk:XF-ߙ36nĤaae{CMhzYY7;tssu?Z|@Oh( cwӧ6߭[oxrbܸQ7YllŠT ǟ0a:ig^Ç ')yOv?͘aл7ȑBMBN*xMF /@YYCL4D\Y9{ru"Yؑ,);^E8e MR_z(h}+ LáQ5 ~.ֵkkb5b5h B;vee˦ZZvPAR}gϤ^"HrUѣʲ޽c|tt9 N:ҲJbɪ]- JdRJ_ؘ߽+My^I׮*-);idwŕgP޾Uܐ˿pApAz􄕕ҭ.],]C@  7J'Qp|Qz[ٙ/]F>4vrsr⇅o~t\)}*{=e}t Jy9i(ѯ?'GA,o_KXCcݭlns]w:Fxu0w{MUK\v5o[5yݝ֮=PX(eQѳk OݻrGƦ{z~fǎ]^rzΦS74';wbxҘtɪ ʶ}c?fso~|yhw\scss7lmr>|pxWmؐ)Y?|?|<9/ɪc$&/*zz{TYu۾}kp(e͚Ŏҿ~µkH=*wwz$.\t4B>ZE"754T/&5BHпv" 84, Xw*&t,@*KKAn.E N0vr7ɡԐI[[HJ~`͞t7Jht5ZE&Ï?lmB dKHwÁǏuBBso J9`呹\#GE mϵЄcwx,17 n[5mQQ7mw`aa$lپ}g Kں៎9ٓAAk/G<ڻ̜961xHH<-6V23>>BP~OwoVQ3Pسxxy}vQ3 Evl܂8kЯ]PAxv)Y@Ѭ UGkY֔)hKJH:<=kݿ/P\@<R|}i ?ױ-#LE .0p'iU AYDpc#LVLLڛ7U: IH8FY BP/Y =uEǎ'L:hPʹU#X,Objf'̮g`fzdpw5ksgKԈɓ &⩨hGH7Rm/mi3JN=xvm&-Zc<ͥYΥ۷Ɂ/o[o˯i;ֻCi]hDӍ61mA,!~ -3; 3?/&$9R;)ޭ+dRHG:<'OX)lQˁMC`Ӧ \=~}˗oMM ==]5sf!jۚ\>wmRHJkӧpo_kMIB!4e;1bbAWhiƌCCرC G&n`v RQ͛πɸo"Ktm@W`r8sO8{2!BYZ M RSL ?.lJ8plm):bbpXw^HLֈdmǵrо}EB!Z,-{ގp [f~t''=o3g 6VPÄI$5 !/JKaXeAetUQQץO|YJ訹4B!Ĵy׮ ׯU55P] gςx%|3~=L&<$(/rr l0\.AT6 {!P3R=wݎ۷L&CYt0~xm` ] ׮ ]JoS(0i,\X뷌e_ |)p8aaڌQ!*+atxll $~EjX8[B!Jxz|Ӌ՝ݾ AApRsǡ|z|۠pJ ^%EEE/Sl#?,ˑ-6%EwFzYN.9sXSB*`/ZlOWŋ5w2BC# ?a!5L?jݪҊT](qqfYYEb"3:ۜ#BmW zz)XXM`mܡﾃb&OG%+)3kh(WWR&$bck>bbjVBׂz-so ЌwwCoo+P@Yʂ77䭛ݖUB!f%6Bv⠕+k`k+8u11 !Bb-7BH#zzJ]TTQNN|''>SA ##Yߴ~rt?O1B|J>Jo#B>7B;obr WP~Q_ 'RSC&egSlmŝiKKAn.ExHпvµkHPd-B5Z=+֯g29v`Y~J۵K ˥KY!!/^N8L&)(H_4`x8 ^B5|cy.u-;z{!ԜVwH[WS[zox) Z<@!6j6i ϰD IƶxfsB!m&o}!P+s B!EnEL:i;֫Y=oB!{ޞkj.W?,;BAx!B=oB!BΝݻy]:tȺD#O~y;?/533<9h1 B6fp8z4A!Pk{޷n] y۶LK;սO<,׮ݜzS'5k_[B!jԺ-W̮]|>֬ (hw6OO/瘚v 5kʾ}; p%^p+##ѣ2Gn~fSCRm`ЮrC!V8?~I>0 I$ٮݻE nf΢_{;w:.ꯋhnnz𹔔#{bcÛV!ݫW}鋋^T oSd]zoݺOѬӧ{7m!T_$Ej'O*8M B!G[mB!PS7B!BM{!B5y#B!Tmbj*~A&9xyC)}ۊoi!B!Yy} o˗ eer B!QA466n[P˄CjhJh<[ vpussv. S:w[[:޼&KMq;vп? ů,_й38;޽EE`apQ!B#nϛχG , << 8زJK!!!-Max]!<\Q[ǫ[!1JK!9Q'?@T,YŐgϊO _~ PR11p"BgXi67sLvpXF=yV,r\,15K^2/ ,0AA鵶ZGAm '˨QFֹ3\ jvʞaY ff^x.ɩԩ:IY*>#c_EݻWWo~R]㳴n m}kb">@zzBss #F!>ULL߽;Jm-BAAMy.ƮR':uF-VWÙ30g7L,^UPnnҔnnpZALu~> $]5xZo8AusU?x{  Frdgڷ/;(ȫO[{8>>c 4}<-Jqvpݻw~mB±j5XjxQ̟͆ͥX Uk8B=610ca&ذAbZoS.fr%8p  11̉sqIQi4ݔ)G^~~nOPf~Ǐ__m66dgtɫO;!G IDAT^[u6=-[ .\k/\޽ůoʿo_xQ:* W ү_*I+>!2Ru[W*w,{[Pߛӓ&}K&p8\e}|9rjƌ޽p`ΣGٹGhX##i4"/3|i #8x\"22HH\Z٥MM !MJʉR.gcg[Uӧot>K*ZuffF JH8&)ĉk߼433>20Οھ-IIݸ^Vӥ`֔)&&̍id]]/&ٱٿZE/,$[XX&q$EuZzA\Ϭ9r1HFˆ͒*˭TuϞt"5%[\]e D5em/j}\R:7@ޞ>}sUj65%EHן^|CCwWʜ[;6 ~18 v \~  rwŋ\r|,7Jg( ٳ5Ο.`s55P] gςZulQ̌ ""|8w}uBU'VM pu@̞ `m NjW_Х DEAXZ5̝ 3fÜ9U̘quիab__p@XwGG8v vR-ʄ Cݼq87?a}l<{ذ~iWdPNNN$H`ۆJO<ÇH?%yynիW*lll0mڗ7o*HRZZ ЋJtfzFի?wקQd;; 2ٺ5ÉJ4JCp&G^ ЅJ%[x9rIELLUUQ\ ؚ?B-[h۷3 ꂙpŊ3g=Xh'qi5< z$'k3\Y*3[tuKSB͂ `Mo4ˠȕVcvhm3^Y/YcTupWFF:sRTVViLӧ+ vDґI`$iTgHF]'d3F~ȑҹPZ)'==g?~) z[m$X[ *2xpov73ͽ{˧j.k뎒עVV XYunNOa>|j>%9XF,22i G;;O>fff(޳'+/aEE@ ɓ{K qt.)o߮}t-.ޯE"ޑă7 tܤSޕmgǗ662P'^R翍!Z߹S2|mV7e%"AݣGq2A{[\l{ۻ 47mk:%K U͜[5 8$o/]ooo,qϞV/_IYt qʺ-u>lj~ ? NWG ֭7nNU4֏l_r#C%hutj}O,V}ZGۨQPj:x j|AFy/::i JNiiفJ@~~dU׮%2)mlޕwkW uS$YCŹu뱹|I`kkC ûzhÆLɪt<IV; 1xQ3_TTx{FpTg>]wv}}=6˅kȑzl-XWW)l60g)' ;2R9 넄+RKѴS2YQQׯ%Ցrw-^W^Nrʏ?*L8% FjY&hoǍtiU%KR%&OiQ3V G|Ծ=YѨvvV vuM0ztH:ݺOKxYm&&MS&+cvl=#ټ֥u]/QxZZM {?8SPP޳%>|Q`;wvѢg ~۽{/&$XC 9jZB_%ĀBuav棛7t2Y<ٹsOj6qpMnkky~3j^!k$ce@M?jǏ_"vxMEE'tS3IFȾ%u8>>K}TR `5cW}8x0ѣ#4tܴYᗙy BvvK*ZuffF JH8&)ĉk߼433U}>ɒ"E˗)l6ёuZzA\ϬW-,QQI8 enD/-ձDE^ TuϞt"5%E411NNfnH+,$ =Y6''_Y*sng<”ϟҥ S>}kO}%7 sOgϼ[ZZv嗝;w8q?''56npTVcyl}}-[%j22=ܰ!3 `Xjs\)Zz_[. x񞲜d{{={s8ܝ;O?7#|dᾙ%dgNOϝ;sHO-k<+2sy={Ǐ+m6n'&VU$'W[G?z2G11[*tInMrzڵ5%%ׯW կC\mʚ=/ǕwTu$ WBʊۿ_7.4:Q [ {ZOU۹͕vsIDq|BOY<< ]]U99Y,XDz_;e'1"8!UvR'❬fl- A}`Ό_3O&hAy{{H?Qq+v651%+3ܹ> ""|8' U[5y޿3kϻvEMI9}K.@ 8w_ɿ|ԩi{PCCɓG|P'$/­zB MMiTJK˝=zQn,}SSψVzU4*lgg5AY&[{x8QSSà1>×Yr#!!cPd{{#G.?u6))3kh(WWբѴww={ 山ťOտߟ ki*3[tumŋ~)og335g(ovA< LMKԼ{Gں֒ӧbPYq ؚ?Ije MV*R?l5e2InE[xmnPn%ܽ[wMha!XFg~4:K*;eF;  `MO?f*8xlSNmkb=%+8x5JU'TurnpGFΙ󍽽譋]D߆ NufajjEww>|T+uGkQJ+ZKlU:H^k0J>_jɭѣ?L4O)̡zϞ@6'O^m+Ih#y]Ro߾]%oZ\_͘B:cۛ:gm--s>CA(LSPP:uHKT*%v(((I)}mcc~4{%]Z!==ae9+*"ˮur⇅o~#_?~NkF)A&}Ңhl.kմO7e#!`lvRn^T[ 3l>¥KKY=zh4!jyP8Ze':ii=P^4˄{O%o+yk]Ѫ^*صyCܪa6v쀝;O=pxƍ11i~~niΝ}u4 3==ر+WNٴACVS;OVU1y<~aaiLLdUOe;}c?e\.޾xTѪS)f,֭o&ښ|P^-ڰ!S&%9yr_UcHL<.kQQYbQo;obr WP~QANT]MΦڊ; ;2R9 넄7YzWRl`2IgRF>*Ju2 ׯ ٳ*35-5rd$7(SsH6ERPeF9s~=}tEI/Nٹ$ai)ͥt|**H,￩Z֎P$8!UvFش;c냠ALގ78)FT?+ZKrbW#2A{;xpo&MUN>>C5TմӺUAd786;0aA*Vbh4տFmCEE?ظrn{?~whƟL*Gdڃ:k֨N#(G Ը{/ߚzzx{Ǫ!M;Cht&&MZL} GPV_Z mq& [P˄Cj6A!B`!B=oB!B!j F!x.]?Na? !j{@wӏl jpFbԇB"FIIuumߩ񧟶OMU+׹QD>I-711NK6hT7oHRSu?}NƮSR9nKS_Q5477vrjgOvuv/­,QÇvldii%9Cjgeedee4iR*_n$K&: agFzbbuYYErruGuxx򋋫rr޳Xd ]jzڵ5%%ח IDATW -?zCߺ"1OStݻ ?eeQfԟ7URRgOu\qqxxmeeII7UnNuV).ϯSnb_~a=~\yNUNp-w$QxwVV0VpDB!|aٺ(ܷ&&feQWB `'*Ju2 ׯ ٳr **H,￩Q5-5rd^4\ AWx֯]Ja$=K9`呹\#GE髳jmuw-^W^Nrʏ?J7ɡԐI[[h!6A5hPZce%`0X_͕Km[5߫ R=n4cg:669sX[-] BG(T9<\dޭ;i6"B G kN΂)S83gʏPWǹs&G!Zy#?oW#HhB!!BB!j 8コ .oB-NrijJ8 B!B{!B5mY*$#c/N_]͒]ҽ{%}'լΝMџH XHc//='711V8wj3%@N<--&=o!CzZCXf\(ٹ…v˷ >|V`m|T8tH׷mNB j獈l8S &N.mmm =6ok^^Cr;v6w,! ^[yF1iٷdUgix#JJ^fݻ>K#"23ϗP=ȥ-"#chhd$ի]ZII9QPPll: qs룰 ?{M==ӧIQENS^hܸA $8q-37ffF>>C<=]ܽffHVT~JWHkm+V 8)e @DVռzE߼ILeZE/,$[XX&IoڥK\KY}}ke[-_LaI0/X($e5RFIB}T^^))7tt̙Ú2(fBfīNy*QJP:A&pc#:(Z_^Zxׯ+;th?tpgڜ|e̹Þ7iӢ߿14spuspn"֗ Azznp%ٻ/ر}`ɒ*$īGj֞=l9:|Yη\pÆYƹ,+{nACC?wիyy OR_ff^Pf0'N޿ٳ'kΓAAc##wjQ\26d鹑~ݻ[>y2: D{IV@'-z0Ia/+޽#-[F_n]hU\-&ŅW]MZBۻ`Zpݻt賲(3go9<.g}E"Qp.{KdߢPrNk_Dn EJ%JhojiiT̳9s:s3fhA8:yvPʁE66X9tj͝[v`1C2wV?۷\MdHj#<sv.'O*_lk?֬Yjjj0aB!lɺ,S\i)?~}tOffSR>_F( ӁzhLq;>rq| 8ҧOG]r6izZr{ݻh;w~4nwze/й)T:uhaaO)/^$Kձc6>cƈ/EݑfkzǏ%s{RSL +&jdwcY-ZhΝ@_x\G cy*./Gyxjf3--=ɚ٭+W^XXRV4ϋ^}6}o5Q֘1CB&%}II!!`3JWRX[ 9 .jlUܵkU>eBq1}k ˗x jtjJJEE{XmۖGFFˆxM1"Y|U˗EGx\;o]ܨjn(`(kg0u~*ݾCܠy'0wʉ^ԫʂcBBzxx6mZ? <6mxPй_  ҵkӕvR :t070zt'%%}`:uj*uw?^5[N6,(bѿ"|qrsu2kР]ǏO&.,>\S:vpn7m*ټY3P=z/.GǏ1fPT25Ο_zZsDGlh7nzx}DwFwIʊs窑w\K؄B(Y}v..7_pOqo8g?mRkFr9is[ѩw>ݽ?9jQQ P}iW'u{@x\Mu<"t.3@ LM 2lXwu!d%>KMwF}/u5 ekkuߟ>}mBsNNT`k Odh(6lk9BHu5 ڤy& [ NiR$\mB!P9oB!B!Re<^$4TǥH!B7B!B7%#HxRBBZ@3vNeW>!fKM͐ĿQP@4[ሪ7R] ~Ŧ@MBGY0F!!W&O$zU&8o=J8ukS^5or5tw{5> PUy#uHliib1MLZ-[իOiYΝ[_'f W'x`@ۤ+(( q㴪YnnC_2JeeE)IIիUXN_Fv}ʫWLoq"}6Df+nnevPgJzp WQǕwPAM…\6iξ}Żws|- cZ矜W lVعSK& ߵ#/kwp*Jm,NVNݦ_x( KG9aoyn# \"{HN6eٌUKYCx[U'>H8!)z+R[F"l(w_W<,YW<9Ⱦ>WiɓҲuu5\]j+ ?i2VK ŧcU矉b\QxxuxduUnˍy7w]wte`+ŋRȭ{L̙#¼Ȩ5GCm߾_ut4/K5g_ܻwJ)#<;G&xO4+WN:s&ɓD2o{{?1:22AV˗ﳴ4 WV;r&as=='?t#EU̙_{?uAxxukMmH~||~zzŋ7˗__}36~6k5//nZZnXXQ`ի2}wedWcl\Wٿ(##7$8(HE]Sܵ}{IZZgįUm!0SߡIc:5kKJ%ݝ<\LtNӧZvfKT#G8NN<dK$2pj`M;;Ajj~xx WG'q'$uoe蔑@}iM?~}tOeܹ,+9Y³goBBN:֯wIe?^l?c\(/EWܨaݬ|3fLo%㢢^O>{Sw ;,MMSxz$EZ;a::3fxRJNXhllVv.]2+;;W/+55ʹ0^bF_:xp76բܹs:ZX-̛(rr+6l6cKi߰LKSrtij`g'8|L߹P2hÁ*Qflڤz6+;[I pRj'$uoe蔑@ SMRSįx;ӽɺS\ſ.O66JKYtŧűLb\(lQȻY)L|/ƍH@n-:?l4 ohH'UTf͜9r11?{u&PX@iSS͛jf|ĉ[tǧյ}֭[իU.,ʮ B!dd䩫jh_$j_kVf-SZݦ_ɉ}ʧOJ[ CB8R&RUgw,tĄp+tCurE:TXɺS\7 kPWO=Y]n?O6iD+E@+ONit##=HW.*!G`0$qss䏲jpܸ~˗OعsSR˼z>}0##=6qq,3֯^655(ffZ(yy$xnnŋK,w߿] ånk+ FǣGLmh.]jjut$|HOSEJCC_`+99ɜ0z.C}ǏY7rͅ58A I[Y'?25PWG$$LH,]^q]233U'(?dŸlQtLĕ+Q>>3 [(nuȑ| 11(KOO3.x=eʠÇo$&fxRۼ8yR[@dR۶O>M,g>W߾ofwM5fLII|ARRFHe'>AuT|ax ݽڮᬒFQ=V۶奞;%*ܵkU>eBq1}ȯXǃgϘ˗3 IDAT.ZT* KEZ"ãtrhhKKGV֫~*{k̙e,QsIH|\_5  I[Y'?25@7ťoh7o*.k](\]_M?~ :'u͛!!WƎK'NP|:PŸlQ&H0wʉ^tV{צn-X0&$䪇G'hӦʃiӆ rvkӧ+At`òygX6.RΙ3Cɗo}}97oYRĢ"FdKK˰!抷flڤz6+;[I PEEuB%.)r SDUrph_|V l&@"r]wA4ML0G!$F5Agw,tĄp+~f0(֖PyjRu\b||J\]gݺ^ZuROOn D!Դ:oGb۬.]?fm57r8DDKDU0"Ϊlm/_2fu"|"K|=FJUII*v&X{ q B!)0FYB3&Ϟ1/W]Tߟr˞?_r9T ZfzzV-cd$`QܵkU>eBq1}kr ˗x jtjIc]lZ4n/ clLMKp-q#CG%~6lެS(=b0~=|ˌOpl`cbc0ХŬYc Ə_*=z _!g&Byپbzjh͚=߾{oyk),,gsrrwMVޔjpy#P^&ئMzjʕ߾幺hBE F|{JxwWrs h4"6A!T}{%YI#IdIFvfEfU]L"BnK-VPE5s8B.}455ȗgcb7m a2sMHZ6iSHLL#Q|l EM>Uk!7BUd2Lj'1mԩA QțRBy#K** ȗ8e߽m ɗ2Nw,BaB.Benn!W u5P"BU?~{Ruw>/3DU_I|>|G07oCTRR <|~7_{,BaB.=@GGԩ_}wM]]mGR O4`9r۷G/1 Wd.7_33=)Q]KK22duګ`Br9NCw)ȷo w7df~>|B\[0cXCÖ:Cq׿y* m7dǎv-ĉ%U{H}YPE57^bݼ`B!076A!BH0F!BH0F!BH0F!BH0F!BH0F!BHX PA!B s!B)F!B)F!B)F QO]ad~]{p:Z [p&P}`f3fÇC~AOrr!a| oÏ?}.[Wp200bp&deAQ\vv&ceK!Bp8 DBppU`ʔ֠ȍo }}aJPW,АRGxT2kWس "BQ9NC6l*RBBCPV ؿz<!Ps7~/˷mQ(,c`8~`y ʋ9_#/ ;z*wC~>yZZ0wedozׯ%pU~%ahHOO8sFzǏ?778֬c 9R̙\)%8ͣ-B!\mҼH]烪*xy3Uu*lO Kְa_ `={"!:u*o۷q)",,Gظ|5/Ekx# ȩfCI d?inބ/k{lmQ00˟[۷Т"B 9o_Nv|< T5hƖoONܺ[+n]~ `؊Z;VlVZ."w/0{6 hjBvvyVL CE-9iF;;X4-@n\PSذ22S'=<Ʉ * p0a7B!0F`k+ĉp:/wC^%ksɓACޅB (+. kנ];v lmGz {ÃtwfÖ-pvE̙ZKMB!7**+k+EMvvй3 110v,=0|8)^"",,@E޽bݺAxxZP4=zp$<{[JoaBؼ\trqEWJʪ4ݱ#hkp0Я̮"BȻ*+Q}a%K`xx< oSM8֭9s@X0glUo{noߠ.]+jyz/'dhdh{n݂vի\.~$JӪY 1|8BݺGT?Ѯb:R%W $ׯ *zнhկCC!j0FMv{̛i0! |#B #o=z2wΜⲆHPw;y#B #o$PH>wrJKvvuͤF   8# QޏPQa[[:988~!{{h/:wx266##j0Fry++kx-O>ztzu* BbE4Q6 rr =K۱㖽U#뼫Hll7B! xo$ŋ7ԩ5bMdW[L(ʘWVfi;9لMɸ~=AaMv'J)+kBчsHmm Ξ}yhԧOӧ;noy'䔖BV2Ȋ(Z۲ر'))9l6wv#tuD u7D?=#f BX> t-JQSS7/FL֭E_f/}ӿ_GB58#׮Ծ}K[[33]MLtDW:ܩSׯVСkع!4VPv+GtlXPPg=w/)r6fC6mc%zEє(WV"ΛFnk:aÕum뼶b9W۶9++"#d_68ڶ)/4!yS4wܺRի/Jn>r$j6KKlYե"m~;!'\m?ܓRH5…|ZD8=kWc6iccrǣEu7lp՘ nmVnLlfj:$**UU5@a!ΛfoJaa)}PY(+3--}|ɬ̼A,9l6o,~`^̔-lq;~hpkkCy"ϲ=]rYP:/3fpww'3f`BH.F򩨰 g"|aPM5sLE%L߾=/zٱcj툺53m--ES3ii7mZԪ>gϝ/uw@Jj&33z2aȐw>&6t;:fJru7u ''Ǐc]Fߺ}_SSZfy*OX^WSCn'$|<+ 7&Lvx+kkÞ=۶n]>Ĭ=M @;ݽ{QV(VܙG|[.P8m4vO6~;!'QXJ0ln:ţc0њ:o7lx]vnڴ>( KUSS  2ۛ$X'㏎3w>_G]jjj$j-XgQ h5Umb^JpI6y2Ҁ )W-lGG'OR=zxͭ׬YT h yuBaXX(p!\ɱ}MRdk mntQ:!gzZQ#J7}8Èp27lnPKKkڍybgAO͜.ZT^| ԔM6FjOMN8>o%S()ᅆ>;:~-sE{ǎӦ޶%,ldAttZMbiEZ-,Zd^|_W<_v7B!0FrS'/_fx{_8;eL>_{Քgq^Z'eD$ųɓbMod٦Vɗ۵3y_ ^ܽ!#&bEw ]PQQa]}*!ۊ۴?]7uꑮ]Ew)7]߇2AI ɓK",9ˢR̞{< =ۺu6EͭI"=}}o$$| *Uz.'O,|cBH.\m8xo][Nť|ѺlK}gt݊ŋ[w=jFd^+W@ ݭV߿of&yDe!g1|ďذGT <40`g۶P"`BƓtR,R%ҫ6!OޥPJvɒ{>(ֆS&&M dݻ1L|Ŋav}.{ܦ( jUXX}!+H{ƌ>[^|FTXXry)wh%m* ]]]L!\ .p%)SWPP$JӻV~)kW^']1>> zɺڑ 3znnݼ~PDD-z򲥋N0IQC(,,w[sْ)11k͚KNSi u3g/4ÈBFMV?_-7445kεkW رyA ~YD&v;'WSnnӷlr@qYm\\+esW&fݺs||C rQB5M8獚 I 2wh'﷨{&MΧw 7ګWx1vl3><!T8A IDAT獚&3A(=s*#=}QF?=qtvtiB7jȻv4޻uhdd?`(}N3\mB5Q԰s/c^ ҇$BFިij9ET8!oy|cCa`B}0FMP޽Ν=ݻCCw!}@QQ}z B𮂨z0qԓEЧw~o)!b`B!"(5tB!jp7jp }!R QD6tGLpH(!P}5A̝3;0@ r|:]Ǝp,F!P}5M$ޏPQa[[:988~!{{h/:wx266##j0FMS>=adZV&)|,mǎ[V6"˖..;F!(`䍚&yGFPF1eeСV3g~=auzPO" j0FM"缥~zFb: AX>M&)ϛ))_ZpwܕLOIx'&&L`nrڴ#FtUٷar-59;P7eoeӱcORRrlfGꪑ.(++P{Ԋp/;~|d[Bv*T PFB#o4ߜi,}U-P ͫΛFnk:aÕum뼶b9W۶9++"#d_68ڶ)/4!yS4G<^rDΆ{wpn[:[Z~zE}U֭GDmbi-Ty# |j!@{ ΛfS[[>t(rzA,>>NdVffޠA6imm7L?x0{d^fLS[8m nǘfhCRG[[L+GHaaOWAV6N^(bBH.FMvfF[||ܻ'++jPǎtW._g7lVVVngffm  %5l!,ȞrV+s۶mڎjjr턄OgsƄ bemmسg֭Ĭ=M6KmkiۈzGQD%-P7EB!D5MZ0"S紴mٹW`߬O 's^^e7I~br +(( +C݅nUmb^JpI6y2Ҁ )W-lGG'OR=zxͭ׬YT h  tjY]*BɅMPD哾r- ZvO_t~ -Z\~ӅgETYg.]z:-VY/l-ImrDy %%ЇcǖS'ׯd`ڴ۶8x0L2NZ)Y,-_璣fa*&&C2&!Pm`䍚&Hy U[[VQQ򦦦999bA yK-Ј666gnSV$AoVoަU-_'1ʕStj,Kɼy?u> JJxO_dɩ4.W\\jdMϞ{< =ۺu6Eͭ|0..F΍{#!/LHWABRaB6p jʫMR $ɗzz-޷mk߿oٲU_Rkަ)Iue!6fei*^u }r8,==.]<=?òWK ޻A|G6:75i]hhD\\&dǎqdz~+V ۵w96EaPRo YYFF3fٺ:3bDҕ+ϓէL C.6A!TyI4Lp՗cm㳝 -7Dkii''mޜ G;n۲y/A۶mZ(a:1jD ٙId߾m/ij7S\\t?V umEULLt(+{YY!yIXoXJ^dٖ-FYh)>}^%ST!r_׭[=xP_uuf?_߰F箂M̺uk''\e>s2uABMr8Bu? u†])={00F!Oy&O^Ξۡ;Ґ>|P>{kgB!xWAT=|8ICqӻW~BH10F!BH!B5 5Mڄ>\mB)Fި "nys# &8$CBoBa䍚QOΙST\iyy  \>.c_8#oBaݬzĉ/3rr [k;;w5i>I#7TTzzֆNN6꼟u/:K|ݸy+66c!ǣϞ}9k…ԋʞ>}cw)vQFzRǓ'@Y 'ٳ;nۛZ5λڈ/[L@y#w3y1GLUW/СV[saV'P9BŔFFFF6CZ͜y#;eGA}H OkmB #f꯿ΙOv()1/Dnm<ĉg))9'O~g_=Sǎ&*,/XjcO>~30rwd#cotؓ6ٻw;oj^96&W^1sTa8yO~!˪~#GmsOJʖU]*B>IjiH$D)68vjLpDȮ]lʕ#+Gtbf3t1~hboҭ lB_DENR B@Q_MwP[[>t(rzA,>>NdVffޠA6imm7L?x0{d^fLS[8m?z4kK(%5JKKׯ_}%pv~f̌!f:u 3ǺucU{]MX^WS|mRB'OϳJJ rc„nn 6ٳmCNLh dIIg>ST{O#=MB0nll>M90Zۍ F5:SuwTTobҀL/&뺺-?u ;wf}tn8A˖oY>]y{w l5j1c"61o/%$; V|nii@n ăKԔ[l' k,ۄS4|뼺To"y# W4S'ۅDsUܼ颗ϟwЊVQaRRW|R-KK_]Q>+]nczzz-׮x9Q::K׬@_~Ӆgˋ6j/_$"55{S KMN8>o%S()ᅆ>;:~-sQ{ǎӦ޶%,ldAttZMbi/qFUE ˘jBw3ի٘16nnϞ} x{Oߓٺu6Eͭ":'?&$|T$#oBMYlmMN|۷b6ihս{Çʪh]RRv%3g:n%&fYs)wbA?w.sf{BсsިiV9f̈Qz{e[l>l5fѢgϝsqqq«d2]heoy!k[:wlb֭X;99纋KWUllϜ Lu!Pӄsި5Ȝ*2wh'ETTTI& dի<;̙5B!DyzఛTuWasBS#Fj{<GGkGGF!hykDbvݭkG##A A>I6A!Fިi~Ja/c^ P$BFިi?o4NDYjD`PbK[E,7e *m[ŪUi"m TP0t*%q4 !l7<<}N=My@߄ zȗ9~(;Qׅھ/( >iTҔͶ 8qDك||Ү]QluXvquHޠw"~I3{ȭ[Qo+<^/S;/<55;!!ӓUS833JNE9tJll16|19s !.7ͺj!y@wM:2wB4| yk9ܸjAS44f.uS45520fۤRl4q24`!))sƏ70`aaaC_E%?&fmc`0666PmM?|jll 5ͶQyo:5oOگpMJNtǵ;v5j4!9>~S' !!! #l !N6ʪ>:}-5͛?{洩Yx*/I~{'yk3cK/Q풒cGG5zk6&8>/-0ANEqr6~jyy^yy[鞞CI_p Sr9r|`/>?~ӄ驵55/dȝ;l.l_^q($-;sGZcccn_*\tS}pInɍB7aT[*gbb:,** (]XXurEFŋ9Ｃ1NEׯ~-usZa:&d?};DIL 6|РA+VSߞں-*.Y㵙NV8yĖ-qClaaekiI[.T~ kYkff~h8z۷k= ew_QOTLԼiӉF[[e|SRinjj͢/\蓑q^˹m݁ Iެ`ՏAAy2,)1a``.m(~5+8*xDa]/,oVv*h2oooo51v# Te(̙3nΜqsz*<}\OZ{!+W]]!m y~v/,ծIJJJ15B_2;"=Eʷ yiɯm(~X!.n)~fK.͹{a6O3qqEC|{<<9v1=T ~bHe̛Iׅh|/ٞobf !y3VLB7 ɛ V7=}Bt&7PL~ @ [% y3KAf(ڒ#kxFWۃ Cf(铺Ma,$o7Ci=іjzyz4r[gE~е ɛ:ۤ>!?nX;{Ns;iϟ@#=dZ633 _Ν2c[[WƍnMSS#ܼGr|<3Owv/8q?__'dzG1YƎq6%d:YRɛdrufy_S7a6&f7n>w "m /[ZZXmݖB066=zdkc]~t[VVV۶}p"Ҭ3g362~<"#&M6drI"#UU9..]\B!y3Tּݩ|㈒"ffTW ˗U__OD쩶Zǟ͙4UnvYQ,#Yׯ`c]]Xc~T{fH$ݻw\mll} ɛ:X;w۶Hmmm/SMUQ㭬 - J뉉Y`СJ"֭Yhi^~aiY%hk`Nɛbm=ۇCQゅnjkk--uCԘP^Joק$HTwtT&MI^$%'}4K, ͛W<5طvmBf%oL6 9oL1*:*rFԀ CL7{v$ɓZqSwdȏzL=kF@E*SS<Ǐ^"XUBx7 't]j=-x䩮 yn(_oWtm5fُ̚?~ٵ+tޤPt=^K]G*=P(xNMkLP}Gigg+~!y@P}-yB=EwFg{@fi{]Af($o] kL?vצɹ `$o&HɹBtƗˡM:t>o: yHt@7 @$o: yHtQ-IENDB`code-001c16ac87ec/doc/images/my_details.png0000644000000000000000000013167515046233326016614 0ustar 00000000000000PNG  IHDRlJ IDATxy\?봪$[i!$S4 g&J l-02>"uJIhWN{;i;1뾮}c}  &%|$tW@!_I|$tW@Ɉ;p#"QG"E%+K\ hOyhE,s++Z(K** gTbb;,<Io0DXYY;?a2$э7{@]+)%w4--111YYY]vׯѣ%hO:Yf/GFFAAAjjjM0JDGHW&Nd2#%%sLBț7o4 RҒ={];Ν|ԩSÆ ۾}3)G dN^5˵ܟZ[3_III9{/9N׮] fccӯ_?>} yaZZZIIINtuuǎ;}t%%%&M\rʆ~7Ԋ;H=zhbb"ן9s7|P>u/wnH xT4F*sΣG_Z͆jhFOUknh7nӧrUUUDHaa!#b߿O{IeddVZ|򤤤􌌌p&UVB455+]oYb``@ [wpuu7oP|MMM׺j-_wFϯ >9?ciDDӧO^kEYYYSSiӦmذ>۲20j(m6;u[}փ>'O%--MZ.gvaaamEFr ǫ?_;w.=׳o߾O>UVV>zhTܹsU̙s/^s;wЭ ]v{ )++y?s3g g>qċ/JJJ\nIIɽ{mf5k=YvС jPܹs5ɉ(|922ȑ#m9a4)Yxxzz}SL:w/5))))))ֹsgzݻݻwÆ ??MMMMMMmuڴi}W3};x<^qq+zgg3g4iC&M:|0UVѧO-[Pϋ˩9sGXA4xѣ/]tȬRB.rtth .={,##())|̙W]pʕ+={2dȘ1c?xALLLfffII PRR255744~(9::jii'$$xϘ1ή­[޾}[YYR544;F?ƌcƌ󕆞F0ڍyQe##Zh7-XLq=% !~׹֪:mzyYB? $ms8EEE렠+WPڞOhOx\^$`kkqy՛#4^AL111n} dG5ڀʲn}S?+˗/oݺ]YY٩S'UUU##Ǐ5ѧt5H:+ 鐯C H:+ 鐯C H:+ 鐯C H:+ 鐯C H:+ 鐯C H:+ Ǐw 0xܹBab~cǞ|Kat6oM',,-(qf{U..#&O,}v W: {{㊊Rmuv>ilٳ 9=N\57nl+Vݻ+y{ߡzFDdnvcґkwvxdh+{W:Mٷ/n͛+'M2QU6/iΝCVQQXjlIɧ;k"#3ǏGlj?vl99i5// `0 СC Z}`0BVa>QW2{]__TThddfaa#HI}ATV~IIύH!)))'N2dHxxNs-_XOW_iUEE٠ 'OEGoZ(uO94t充Hrk4$%%aÆݻ姟~*kjj<<<g͚UZZJo~ׯIXXةS  //?txۧO,Y|*n2119|pQGJ ڱ0~_R򉮌^zv799BHL̛ >p`fr=qF۽{BCC?|^~޽{>|6mڒ%K>[lyUjjjFFgS7o?\ZZ?4Uttgϸ\nwA{gfSȭ['~-ӧϡf?Tw]5lvܹ'?ϮTTTYWIwzwZVV*˗T977W^ZT֢ ULMMZZZuK_~O>{}5rrr. wJGlQH/z{Oϱ;`mxժ1ܼaӇ wzʘw5t7bECG9#%%USS_SSSCO\t633־rJQihhT x/Q陑qBvDDVAjТVhh>!$55&;;P}v횩)]7uLnnZhѻw}\UQ@+ fG_˗/]4==Ϛ5IcΜ9sݺuNNNuXbőUUUUUUl6eT9sRRR\.}ڦQ@!_ҫWEѓ8#G7n9sM֤TUU{}}6n8KR-Ydnn:88())mܸ::ylZA|ίC H:+ 鐯X#Z?Ђe.(#A :(qGg2w!_I t2:}0|DJV,XLqGHY@P UD|0荒32^_(##U-Bh;޶=KO/<}-(Z W$Z Oѧ& ݻkk zWD:r$\Ba%K,,t[z[}|֭7e*7T_9Orr4Դmn mm_wYow_nt"''2a#䤩Vj7?QPP$$䄄Pa`eD5zg94!!éS?5~AjsV)--u겐岲ҫW_̤Z?N몪__qKv$sGk,ml ll nLCzz޽?~}Ӈ;4 A>ѯϝ[cCzzu?^59))w۶t7˗\޽jWoHh4J;r$幺Zٹ{wի\ѣO'"!kYU5ւGۼNG#Plps,gσOu[W5bD?YY{kYrȑz*JJ IK+:6W.rքc" 1!d|0mڴ%KP}lْիԌ OOϖH+mn+))F@²{II1\\FP XB -*(,, |1mR7o+ !.&&sܹ55^z۷ "~PwCݻG::"ڻ{~Qot{ZZ]ge7cҧQw&5;w:uС'XxĖ-6lȐǎ9?]⏲̴WP\]] |Se=z 9UׯUC/$˛7EӦ۷KKK+P޽=zOIKK߿?U֎Ҫz4J jcc{ֱ_*(|_II7'x׮{E̙nݺ‚k˗/_tizz:É5kV9su ]]]Z;p+7qΝwFsr ٽ{ڷߚ;6?C[[{РAG6rww9rq̙3mڴ& 奪߻w۷v 5_)X H:+ 鐯C <-(E-X:"Ɏw|,s+p @W@a>$w@\PɊ)@t) *YjVVV~W@pJmLxGc2}?,.GC\zMtLp~EEGo$pns85KwPb+mkSʕ*s{{ߡ2&ӗ.ptTff4aۭbׯgaa9XTT~Hkrk((B23=lm6T;..;j̊ӏ^袨(G̞}|ӦoLL45}sb23 8QQnGPǡ:ݼxxՓ6mک!޽';w:o|Ntw52(-ڿݻ5݌ž=Eg+W^֦Ӂ=rs@ǿfsd99STRoAAO**fF-XC^BܲHCFFajppd伆@Sa>HXE{x|3xAg63gqw56֐66pwwooGS޲ݻ+Ycfg bM 7)ݶm7ѕ7o4DNNFUۄSc+)S1NP3,,.\ݶ?v6fL!x !۶E%+S7Nչ^8"B33mzL;- UNM27_槣ӝ.wҩsCۢnbwqphUYXXF4$%ŠO|f}ջ?޽d;;=z(M`x36;BѣW7ׄCCuSSC/և+CFCWntU__5(I]]YNNZX좚֭7z4cϞTP=>>1c1&&^3}Ζa}kiK-ƾW>mnC->owrr}j11o[ {"Ϙq>+SoJ~=ϟIM3?!d3ҡxu]jϞҹv:4\",''sw-?gpII7))nпZppDIɧ*NXX֭7&W o>}\QQfgij'? (ԩRiiS:@wt?!J=>5:zqeeO?Pw.\hI&ck;J^^sϞmdvv!::WC,3g>$!!GFFz޻vM\O:]S>ͦϦBu] (+J ,A(%%o˖ \d?\t8j߼PSMM8Xjk^yo IDATٳ;"J밷77w@!_I|$tW@D,X`; 8Hv`[YY; 舐|H:kSݱBYYiKö[7E'T`2}ot\LffaU'*j  ㋊ʏ{e.!ټَV~zӋEEG_(gmmv,!$3=?Ϯ9ov`CNƬ>ŋ.rT7mDSׄGhh̝@+S7zF¤I?ϮxIoJ|f:}?XOݲ}<fƌo8?Vxyݶpr ٰro㥤'N<_U9?t뾾w;r|LY٧jNBB_*1#F>>Z|n?m@RL9Cuvp_vf;T7^/Xp*""^ OG _hAU]*ۚ^hfM/i]ut.]:UV~ntsjtu{SFēC]àE}b2.GO|f}ջ?޽d;;=z(M`x36;BѣW sjujjС}anط66Xhu7;6t%MWUՕd8.i:{{㨨O3ylNe9 ՏoxГcfF1c1&&^3}m4cưGë9O$}KWƾWi|zXmnrr27cx̂*<>&55̘cg,##I@ٳ Ў#xeeU՜wW %891}|p8܄gω_-88SU',,mt7>}f45UBƏdTSii)BԩCzbmT߉έCjA+G?b<=o|ۃgB++)MwBK;;#q8o>>wBttZ5NYf4;|IBBСw*2~!5S>ͶԥktƍPVVq5/TSSe o;{cbx$]{~!H}0|DJV,XLqGHY@P UD|c2}zG XHI1b@(W?*)&'yypj.)uR۶}{ q48ұ׳^};BYYiKö[7ESع%*糦L1L;Z+,,-(qf{U..#&O,v JǒQسxdFiin=rf^^TON۴jNvvF׊ܶ톧oxEEEa̘bShO0Qpmva]hj[VV{w5kl,ܹho֒4HF:~ꡧ36-V__ѵ앜זq@|pr||Ξs-ŋk*+?GEvu h|޸B.oܼa\ܹ,D ;v?p:WqG@!_I|$tW@!_I|$ y$;~ -X:"$w@\PɊ)@t) *YjVVV~W@pJ[~=aӣFp7D+4 ί;Z5vȐބ}%&ss ЄdFGowABC_ļ=ujUcikj5oީǏGMp }1B.][ԊNV(rKx1WL';YXUʼnr#\<88"?TCCe\so;tPTT~Hkrk((RptTff4aۭ";G~ϞϟgWW7ek;P=D Sع%*糦L1~%&c23}ыǏGn05Tr^ɓ;?^céSluOk>|zjξ}覓'#Ƈe;yyݮkH7WRyItFOnL<~<_&=~_&;$h+B]JKm֒#8sww[cc YYicc ww[uo\9ijg7 9ioYY׬ajm7'xJJȾS!E{x|3xAg~y+P4ZrOݻמ).TV [SSs)墢C##3 ˸\!DJAt]t\kӧuv>ac3Xc]!ff_i]>f@ԣ_׈ТkЋ$M9+p8\ ]t+8GEe=}gggE,y 0MrOBeGN>W}<^|_zXmnrr27M а׼y;ϜY iEzz=ccҋoU@ _i}k-YrΪ\YZw&S[s 񹛔pr}}MG|℅mzI^~犊j6;KSSaԔcb֛891}|p8܄gж0&lv-BBoMbk;J^^sϞTdvv!::WӤeLÇ$$H{׮zXO<^'WVVSu?…vvF Nxmrႋi5~xP;~A7jj^^w;" bavjjL1={#W$8I|$tW@!_`G?Ђe.(#@t#"Qςenee)(#BA 8}0|DJV,XLqGHY@P UD|E0 5EGod2}72I|E#N(?k:&_g\L';^`0LL4֯_TT~ӗ/s !,vݺ)R+=|eɃkmN._;u[2>kSz;N,ft=rr** V-)cMdd&[ǎ/''m`hlvօ T~C9w.de tw={˫MM{Jw﮸f %;{kCLf hj_ܽ{֖dRZ6ڮö|_9T=atψ5k֌?bl6zg6)JW]VV[SY*'%_]))W~~(Gդi̴ҮЋ::r.c555gΜ Lft4^oC w/a ww[n:(((<<|ٲe򋢢bjjɓ'~aڵ3gΔnaWV FTn 充sZK7o㨪ڹٛfCоEFFӧL5#Ԧ=-((055mhvqyyyĉhjjFEEYZMj앜WoSyyՆ 7nЯ_Oz=oط-{=ʵ!}n߾=gΜ#F3Ç !W3fݻwVSB|}}&L]YYȍY7 &y֭yYYY9r^bK.5jԨQ6l@C ={ɓ]? 5ΨQkm4,,lܹ#FV- O|)S,,,Nzʗ3R]xÇ>zOC_4KvHsRY˿豈CCь#vy:Y-X*?>44IefP5lvܹ'?ϮTTTYWI5\ۉu7}FA/^sM|ݺؒ x~O<bA )))^433l֬Yqqq߿ׯ__w}wꄄ77z<oĉ!!!UUU[nmhFٌ3bcc>~emm_aӧO>|XUU2eʔG|ϟ?sM<~xĉl6כ7onj7nܘ4iϫ_x1iҤ[n kBEuG_l||ꍡ!M n-<2eJBBR+?!EN5Z_fܸqEEEINN3g|ErV_/[vvH#v/Y{XXݧzcX_L9tr\ 7C^4;^sbqqȑ#kuk4ֶ nffft}IIIz%K%&&Κ5'1@ob…aaa'O̝;W]R-;2bC# %Z,XA/<4Tuk9ʬQ~Er}:]#33mgE}7IQ {JJJ.]ԝ>}(dGFFr\BTSY/]]]\'))ichhX)))Ç&OOO733҄Z8lCr ᷛ:t76. ?H-ԿS͠\ZZڵk׆:(((|CW())wE@Ԧ[>**ӧ{qvv^hQoڴI__?((H]]]NNXXX4;H V×smm PkwNi}.B~ΐ>bIII싉Ill,}Z]cFZfvv6`0YCCyܹ̙3?..nrrrf֩SRz133BԵ ;>bccX}}}ܒ]0l~_ٳg" ?0GvM#Ƒ*#""ƌGUI[---! cc/^Ћjjj111MMY\]]?}TQQf555[KJJ¶nڤ(恁?~p8/^زeK3!,[, ŋՕQQQG[x?ozzz6uNNN>>>'!!gTSKvM5 8>~+Ԥ/🋳obb"DwRC]ҥKo޼.Ǜ7o/]M1bȑ/.MLLطoٳg&&&(@+;v'f͚E-^ӳ b`̙NHH:t]Z!DGGgժUHYl3yϟ?Λ7y)\ܹs] PUUuqqiv+++\ Rl +XCSKUw _.ƍ+++\`wS~ׄ;B5?~ϯTYYy~~~ 08mʕC ?<==TTTLMMpʕ+9x9sZm@={.z{P8"b2d/C?@ VehS~D'<<"%(,XVV-}i@3 _I tDA_; _ VGHY@P UD&ӷ":-r+V  ~$qB +MFͧllwxDAAv~Cږ- wܴ!DNNZ]]eŋGILrVCOrsKϟϪV*OzvRqqeT!ٳG<[p@K _!nUIYrȑz䭭  V֊YL%75_0ȉիwW"Zϛw,bnWGxГۄ^P\ر*_II#(*JΈZQ@@K _!YבhhB;ZZ] !RR ⠠06;.UCE%xuj&Vb;BȂ,eeyBHBBNbh؋/PfX޽z{O{wUh;!^4Wږ:!…gUUW o,X`IٻaQQ{>^+Vx_S/y3w·Wv҉_~# %0DH۶Νv;tɁ::=/eKH2jzboPK…olא!s~beeUݻ+i\9j]xğn~kWʼnVh@K0xx@v?p:WqG@!_I|$tW@!_I|$ y$;ZQ@ZtDx^NxxD$;JQ@Y̭,tDW@a>$w hSlǐPɊ)@ݢE]B"B%+x?3Ǐiiio޼i v|!\IIg2}7ahm[٦BV9hz?deܸq>!v|Ν<{7yTӺG@y֖PH@Ҏ5~PHHiCM/%G-%%̴ !?V~]Էow =B0=|eɃ۷O:w.&3dptTff4aۭ"տȑk嬭 ֮QPmFNO/d0&&׏/**?v˗Kgf;5.!$$$ѧyy%*sEj{{nzn36ZKubf3c7UU+n[[89lpYhlu}wO՜77c(/ɓ'Bywҥ>yyyyyy999.]x5 AJM **~R~,?WHL̙5911OFF!X\\9r_WkFk13bIɧ5MVT NEDdM grw^^I0oP<+t++O3LL4vUvU01ьȰ|&))w5RR lh^Η9.]:UV~EEFFfqZ4iV]t|ݚE[uSSC6KY@sӇ:;`l1|x_u.1@ѣ!DUU@ܱH W] ݗ55F.VQQֺ F6]W rRWWpQ!c*Ѷ uul퍣>س灳E1@Q EUU5??_5WFEe=zs/\)-rpREEd08Wrr^7C\\޽dL̗GFM@-Y@ٳbl[a|| {"ϘqN2oP-ѽ{Z5jjjHY:gu+ih}d,?jIjj11oy|y^lT@/B3_-88SU',,m"h %:;&$.BtO>WTTY*1@ {iʵk/֭瑂g4kVyo>ܼa\ܹf=箝BNU?-hGܶ)mɺ (+𸚗W`Fp|f4;|IBBСw*C@I._,mkjj"""M~X6m gUZZ*@" _ !|6  A p~$ԛ7oƍNzݿdi< FW@rIKK yXÄ6 t_Mrz‚G57n$7OCK{)|A;wމYj! !qq=JL|6Aܡ@ W11oOGRTk޼SˢU}+.-]jE'+EE%KF\K+LOGefJXݺ)R҂gfWU2b mȑk嬭 ֮QPBB}W2w9Z 51۷O:w.&3& {|hc΢O#暤]=$Cu<] "_:OFF^A22 ]53AMkŊSֽڧa.jk|̩dN8,-_??ٳէhEKw5@_lP"yVys7ѥK>ly.]:Qff>wՠA/ŋsUK2dƌaaf~&1hPouvچ4#xٴ~wܹGDT"yw=bkkΗwٱW}ɓ'O8::k;_xЯߡ_C|~ړ={j;+nуzD@Я@6+,,/+kM"{J&8h>|0 1 hWЯߡ_+_=v W/\ h> T~~qԜhkkB-BꫯJ_a_WW4AwWЯhJJJ4 hWxa hjw nyNZ`"x(fА|:qUx<}wvP/+9 E@K_4~x h +W@s4&gѯO_E#&ЯO_a.<{on}m+/@K_y?z$߾5!E vup5c,GG';m70WhZnn/>p!6C>[_0e#X~*%叅lmG+9ٯ,őf.|aʝzl'?/o.ǢM\/m⤶ݻִܻDѣC , l|&ƽyx~4y>.,t{Wwmc1U.ވv·X/]\SSM:|hߛ￧}̸w]?iℛ7ong@3"߬^X_Ν7nݺu޳\Fލx~^OgACY~2}ZII ;%φXܷK-m~s,\#6~.MxwQy&tu<۷[ u2v hN/9B[K22*++zlr~O=sBү+))r豘<߹uq?Ζ.rV˗/w*Ԋ 3tV$,wBACmwzeeU,_{{'7z:ς ڪߟ9q3V{¢?ݹ;oJoil<#Jn݉H"d/k;M#}YY^qW|d/feI$w\3.+43'ƺɌ~o[YYH$>>?yySSV%|vq"٠ʇڪ7mbrďzKV4Yc2shp hs0(hIParrܿ…0:bxW_Wmظ?>`o?d:$c:֣…* ̙AgenС$m;ov͊\'*lXؗi[63?m=jҤ Çԩ;_(dƴ78x l|wϛ֛C/+WS}fzvSNkiŠ&+y,)o mW<}/ؕWюP<=h)+9܇RWWKƍ?,:sfߟ^orӚ'[2l"z3◸ȋ+++^}_ݚ1c͈ҭ]roטX@Kvm>:thK||lsHaϞ\$۬۷W^]ѯy߾nen…3NN6}'QZܵ D$oϔ{HWWW;xqo=N_~90Q"}|w  vxĈNEdggTT{J$_OB/eJ#Tu0ffV{wp.:zzk)=mo^dgC>},q:nΝرS._#:໦G_^+y(Wy;+wWeakkkk:z IDAT 6nc"5#/a9;88:t0sYf9;;;99-\… l\_x www{{{\ƌ3f̘w獵^{iӦ5jĉO&Eocȑ|M}}3gxyy988x{{gffj@]'q1?읦/EO8pSN}DE1 Ν]GGϏp]\\m+wKޙݻw޽{ppLEO? P_))).^8wѣGٱn[\\LD'O}w_ i'||سgPCґߤo߾+**b^*W>}uÇ;::Ν;I׮]C|~]v ~/Zpr+/F1Фm-ÇzzzNNNٵkɓ'W@@{DEq"޵kץK ,X!wPӒ)ssEUjEEmvJJw}w5]]]@\ ڋQ&i ܫBC)2?6on&w~7I%'}%**711166pŊlɓ.]9~xffSCBB *ёϚ5+--͞=[y|ŊgΜQ P(lQ\iUjiEr~rgVWWMQбݻw/((1 @$񚚚u999?СCsI(xxx888x{{gff}SN}67N4iȑӦM|-%<7[7!++-::Z ,3lӹ3caۧ,mX[˄2z1zz#+ёIL''e0L׮3as~뫨bOg/DLDcať\jf̦!j%0s0FF3>S]Fh)ǯ8''gС&77Wy<==944T,q6*d6'H_(g؂Moiim66w޲3g;v,33S&iiiOJJruu <|DDDRRرc7m|iiiHJJ3fƍ5Q )Sh+=1֯G(9ӕټ23E*.&==ZL,7 )+zzRPPq1PPPXbˣ+W(9)%ieYCt.]BI*rѪUTXHoSv6Қ5-TPܺukyyyE;;:v\WWggg2nݺ򊊊իW/_\^J*dM[( 竟3<$ɸqر<˓]i(//7hooM;grWvuCk|~ΝLWAE+̍qQcbp_W^a^D:WUWٳU199Ϭ4]2LNұ2̘J&;25e%˛733ju([_xbHHHXX9ӓH$츪@e<((($$$%%6h]բ7BVK+j[>>>6lP?gخ^:w\[[[gg犊 6.17`]]&BvAQQQQ666ZʋH($ssN"7HAؐ@@C%%*wJKǏa MMwޡ]I zUtܿ3W!Sm2R:Ӏұ]3__jՖ-[d쭬_Ύoܸ1aQ8p܍g4h]\nZZQ˒Y*U3tl˖-駟ӓ={B%wgϞ=r䈶;;:}JKi>Z@YS'F{}0 ׫aĽHgfҰa-ۛI,nE*8&&'߽z׊ӇQidbz&ʑ#Gvܹ{&o"tϞ=ܗ===w!bqxx -F*d"z_nzܺ:Hg8urFGGK.em߾]򜩩ccc:\xחnݢ'Oq-AnppںOQNիР3h* iJ9J$KtN%-3e -^L"Rp]+*חᎧ!Ƌ>>LTRBԩ-+DE ظɓk===߿U]]۹9;Nչ*doҊ*ѣG\277xԨQaaal\c[vۗ.]jbb2cƌ6n``wyg&&&O>#vsw's(eHSڸe(6V -[h8*,!Chժƍ7av9d|%{ ӧ/o)(>%KĉWٸ#ss22EUQ\,ngbƗ.%;;zXZ?I g͛4q"{‹,(ʨ,?v6ZW#!Cښuu봝 > ;+wWЯߡ_hžTw hSuW^ ㍼cTIJMM=|ܭ[7"bf׮]'O^^^@Iwu%CC Ȟ8P2T;\QZQQw]vMWW!00wj >:t*4I?U^NGzzD"1BzAc &hn_ (__XCCC<'OtRLL333O:<啐p˗/+###C+:U!UG󋏏 U?gIO-ͥo}uh|-e D"qttddzfJKKciiigV_bř3gT# [WlZZܽܙrsS3tl rqqqtt DlfݺuNNNǏ?t\ 111ޙqqq|ԩSo߾M&M9riӲ5_cK& VMrss|½Ɵ= tXX0) 6y[.2L^Èx׮Çsmo`gnxx0]2::̄ ϶>gLL/h1ӹ33bsr3n?D̙1FFLu >~%557`999Cٳ6RQ<==944T,q6*d6'H_(g؂Moiim66w޲3g;v,33S&iiiOJJruu <|DDDRRرc7m|iiiHJJ3fv{{%U$''N2E[͌~==zDɔ,͔I/Rq1ѲexOI]kкupD%%T\L66lW&JN~DJI2z}3GE9kPi)ݽKWйs0ŮZEt6egSn.YFh3ۙ[nM<9//hggWWWǎT׭[W^^^QQz˗+ Z_iRVԶi BP8~|sD"7n;vss'yyy+ &irsL2ܮ_b>yy5IuT|ٳٚ199Ϭ4Q2)*̌iXdَ,SS[y13S] <'e+/^ 377g#zzzWUUqZtUjiEm+###99gÆ իWΝbkk\QQE";,cccvb]]]].("**FKySB dnN?,HAؐ@@C%%xD=|HffdcCSϞŴu+t?5yv% g[TDq\գtO*)*"KK4W\LHVVT\Lh JVڲe쟽74<\KZ˭BVK+js~~~YYY ۲e˼dagϞ츰P{ ]ddٳg9DΎNRڷ,Pԉc }_a{~***~w˗o6@T_Obq-g11<]wr;wToĤqZn.#<'ʑ#Gvܹ{&o"tϞ=ܗ===w!bqxx -F*d"z_nzܺ:Hg8urFGGK.em߾]򜩩ccc:\xחnݢ'OqAnppںOQNի4kDB?H5I$KtN%-ʖ3e -^L"Rp;DQ9,w< uN7o6^`*-ZNUGxN%<%Kĉgٸ#ss22EUZQ9ӂ,^LqqҥdgGK.$++""j'͛4q"uv# 2*.%K 5+X[Ӑ!dmMݺ5=-t<+wWЯߡ_C|~]zB;R-rO{Z~1;Fn;|ÇzzzNNNݺu#"avuI@ ĉ(;;{׮].]244\`eq/CMN(U!I)))}ݵktuu{fӡJǨB4[OqqG?0J$y -4 br__MLL544SxK.?~<33ԩS!!!^^^ |<222)3MQZZQ[}Q??8KKPs(?nݢ\[i<2Ο5:wj0H$GGGv>X,w<|(?x8;KǎLbt89I/'`vett [mU3}:Ϙ0_|'b"" sgfeTW33g6Q,312bjy>)ǯ8''gС&饥Ρb-V!9Dmoo*E9C4mڴxKKm۶{9sرc7IKKۿRRk``#""ƎiӦHKK;p@RRҘ1c6nܨ^%U$''N2E[͌~==zDɔ,͔I/Rq1ѲexOI];H(,9 *)bgz5ŔGWPr3W%&RJ Ӝ9*YJK]rΝ{Fi,v**,۷);rsi ̭[&O^cuuuvvv*֭+//Xz˕4BVK+j۴BP(?~|~~9C"7qϓ<ٕrn~4 |&w}EQnnnׯ_|<Ľ4yETbaܸ!1&&G1~<|<|̚t$ "1"JggkfHǷo?ҰFTV633aQ~f;LMniMLEu\x1$$$,,ܜI$v\UUe``2dlllddmj͛W!d 63tlW^;wsEEDfffفnuuuwrB(OOO-SO $9"dcC ԧH! O={J]Gdh(g;Ե+ d`@>ۢ"=}}UQNQYZJܠb0@:b3(WWZe?{++ׯ7n hx(w Z7[VdJU ۲e˼dagϞ츰P{ ]ddٳg9DΎNRڷ,Pԉc }=gMh IDAT" CxϞTUEEEԯ4>lq/ҙ4l) O[ϖcbByyݻECwގI\21QGxN#GܹsM2#""D"Qii={/'+{zzرC,pZUjiE|vչuuu"hϞ=q* [MMN.] epuu ////++۾}39SS:tH۹/ݺEOP}}u+UUQA7nߟͣW;4h,'~֭k}:Gm%Nt LQQʂ駴q#K˖Ql4J[иqTXHCЪUQ@4j# "ϟO~oa|S9Y}-GQ~d 8l97ҼydnNFFh;DQ9ӂ,^LqqҥdgGKOZ||ޞt 7oĉ¾ ځ (ʨ,?v6Я@G`mMC5uxZ0yWЯߡ_C|~ @͙5kޥ+W9i$a?Z mΦ\ZFŽm@y;s֭ɓ'q]]u+**V^|r{A+MҊ6mP( Ǐ~H$ƍcnnn$//Ov䢽=7M|n]_QTftt5'q1;w2M^QXX07nHEEt|ca!]{` Tdzl}ffLNt|3+ kLe%өr̘EI&;25eɛ733SrŐ0sss6'HqUUxPPQHHHJJ mкE7o^VԶ222}||6lؠ~б]zuܹ...l\$cn266fM.5߅ 킢*<==mllO}=%$PHʂ $P>TR"ϚE3fPY=|HӧӬY*RSwkWӊ v\QQ⢼{jUj+mvWT /ѣJY$|AE5U‚(Mf[_ϞeQԉEgVhݓ.]9NEGGE\3ǎ1L}=#&[& Wd,Gv}EvLMݺMrȑ;w޽ɿQ#""D"Qii={/'+{zzرC,p{YVD mW^[WW'NбtҥP WW򲲲۷k1C355ݿllC ҭ[ 71 N[RUi<ɡZz>CRX8?eI$KtN%-ʖ3e -^L"Rp;DQ9,w< uN7o6^`*-ZNUGx^ra3 Wcƌ3fΝ; ݻwܸqNNN˖-ZTQe\+BV+*R'=%qv0e{{ǯ] ۯ:yd{{{9~?hԨQͿ${s//k*G^ad:ub c~YYEfS'_?PWl,o0ǏKYY̻2zz.3f ".iʊԉdiMM*+__FO11a6of:wn:EEH$̙~(,#͞2̜9DA!` 8ЁܼI' Z'h~: *+bZ>P@[C5 Bԭ ;ߡ_C|~ vy _Ku_x)t7Q&u_ p+F7nܚ5k80;w|wǎ_sݢ(ND?\\\&NxEy6P34EUjEEmvJJʼyF5v+V4\Z!##C)Q&ii20 0|\]kW׏|!{/1:JTTobbbll+ɓ'/]sSN)燄xyy%$$۪*ftF_yyG`._VQNu53sf5U:gcd17>~%557`999Ce666 TOOO/--uuuuvv mmM Y-I$h{{W):iӦ%$$[ZZn۶ݻ̙3ǎ̔IZZ\]]ϟ?4vM65EZZځƌqFMT("99900044t ތ~==zDɔ,͔I/Rq1ѲeҸ+}UTPy9mBKdjJTV&gD%%T\L66lW&JN~DJI2z}3GE9kPi)ݽKWйs 4~j۔Mf{ڀv֭['Oc/ձ㺺:;;;u֕WTT^zwWT!mBP(?>??_!HƍǎܸI^^JCyy97E{{{n>h77ׯk>O^cvd *Z_`nܐ=B`aH㯾̜ɈD̃錏T++=[#߾J%SYtꤢ33aQ~f;LMniMLEu\x1$$$,,ܜI$v\UUe``2dlllddf͒ hvу^{v[6SSwkWZ@YS'{0 KJ+WRnԽ;\I*3 ~7PAדXirLL(/O:{W>}11iK&&I~rȑ;w޽[{DDH$*--ݳg򸧧;bX,wqqyŨYVD mW^[WW'NбtҥP WW򲲲۷k1C355ݿllC ҭ[ 71 N[RUi<ɡZz{@CRX?h, 2*+ŋi$9YI$KtN%-ʖ3e -^L"Rp;DQ9,w< uN7o6^`*-ZNUGxNFÉۛ$''{yyq//ɓ'*{zz޿˫Yɷs7rv(ssEUްUڣG^rennQظ:9CǶv۷/]dƌ l?,,͓LLL"##>}:Gm%Nt LQQʂ駴q#K˖Ql4J[иqTXHCЪU#p!}1 984nglˣAi>9Y}-GQ~d 8l97ҼydnNFFh;DQ9ӂ,^LqqҥdgGKOZ||ޞw&MH/k=~iCmgm t4dY[Snnσﰾ|~ ;+wWڥ9/D~/ GW^ ㍼cTIJ5&koϼM.QPDOEcfDAz46P$+LdeP+SQcD+}Jځ.A0 a2Xao8WD z^ٳwUՙ3gnܸaggrС/xۧK<<ɭ[Fᒮ]KٰAPƯ_5kS777Ϙ1ԧ򠠠XT*xe2)17ѐR ̙K>>jjQ==='--m۶m{G+Rhcn-ŋ[[[MLpPT-b`E{k?`sΜ9\3}1 ߧ'O&Gr[wt>ڈAd2 qu[77MMQgȨQF⸹EIZ?LDI)oׯ'%%eff3Jb^H$rvvvrrJJJd neoDCKmmD"ؽ{)͝;w֭[8{쀀FW(nnnL Lakk;`SV9R燅y{{/ QZ tɐ aŪU1UUcǂǃcn;:֟|K}xHxz5WIg'Lak//tv2XWJJJRSS콼޽{SӦMym?3m:Shcn!>**t&999<<ڵk555/@d2noo9N^^իW Fڈe_~\cgH5 lM L63B;RRq㐒7Ux8!+(O[Lw磥=2>8&CfR)|#R󕂂>|x)3$$$77WP#Gp_N֧8p@T*ʜwژownߴ4TV ő#GTLLn?ncc3f̘v2rrrGС3iҤǏ:ujXxW4k :>?2bc5=bz47KܹЌd_IT->\Yb[˱y3 HL4>8HLdᮧ0nlFD 1r9 ~ 4OoHÚ5ĉHNFQ¢EhoHMel܈}@|}5@+Lw"'cn922~=MF}qvB\(.f[ヿbS|=6nDDཽl}G) bEܿ;Z'edP(5  ز|3n(C P( :ӧcT =}PyBP(KP( Bt|BP(C+ BP,:_P( b() HIDAT BP(KW(y.{a?2 p襌8tB|Xlj:R 'V:s̍7]\\B:tE' y<@ccCn޼@mЀGM]_ mhHlWVV>}ݻ Ǐ7328t:R 'pFl܈`6`w2;x7E'W###ʊ^x͛.\8|]]˗ 뭭IIIBɓn磶VHnJ3})17P>{lTTTIIIqqX,63BX720wAyy@CoĉuI1T*STWW3uuuի ۷or!8YʹShcn"n[g˾>yX7mmm"(00/>>^P0/^|)wI \p!447<ّT ckڲ)+c2^s3 %c%V{{}4:@rs=|9uH>w4?\ҵkqr"6hʻ+UUUfb3f0\ J϶LF;6&rT*Uaa9s|Igu#V\YZZZRR~F?zhWWו+WΝ;WWWKuu˃***rss.\gϞ7>qDyy 222#;@ D sƮ]OH$1$c^utvɬ}Ӄnde!(]n$^Gaa :; hnҠToC"y2TV _kٱr9=7Vd> "DPj*ԄFHرȻG Og-8dkxNL^^ے2T蝯feei{yy5440{sӧM~guDC}TTTRQ&999<<ڵk555/@d2noo9N^^իW Fڈe_~\cgH5 lM L63B;RRq㐒g30sWሏLWTj>m1-~/΄ xx?|T >D|p U(rȑ#ܗaaaP*J2'''00116&7--M*jBq:S]ZZ豱!!!QQQ#Ӓyyy/^X} Ah(>ħ"?ߐ5k"VEގӑظjٰR);}ٰkp<[য়vˑ''lڄ_5苳k~6oFq1o ظ^^ wP(q> kޏBP(րH.tvb|H 5tBP(k`TLSvCjA BP,BP( ҡ BP(P( Bt|BP(C+ BP,:_PK0㍴J?tB|Xlj:R 'V:s̍7]\\B:tE' y<@ccCn޼@mЀGM]_ mhHlWVV>}ݻ Ǐ7328t:R 'pF''@w7bcQ\ ;;ǿ x+eeeEEEs /^x .?ˆ֤$PXZZz[nQ[[HO7ژhl={6**S,BP,B4?bzV׿`gV릭M$+ FyzzŋO:.  ./[wŊMMM\3(**ZdܹsW\8EqDyy 222#;@ D /_>R,hڅ?DC>E]_Gg'쐜n]}A$“'섷7DMKRܾ 䵗PY.|5֮5gxo^¬!1MMhlT;o!tK.miia6}||j5SjzzzzwwwOOOZZڶm WDCk[ ŋR-ZIKKJCww7~9sf:s ,+b744 O ;OL$(:E}+= |kj2}:~׿YC>%O2jϞWus#lJ%yLcC_77ҿ(I_GI4y>qs3Z_~zRRRff;٩T*upp0D"ggg''JFXff mM4J$ݻwbܹsgݺuga] []ٙ)lmml70@_0ooe3JK!.!<x-8dkxNL^^ے2T蝯feei{yy5440{sӧM~guDC}TTT}})Mrrrxxkjjj$ _vuudL>r-Wǎ!.ΐ8jz{ٚ@8mmKk_ź?u G| ~ 4OoHÚ5ĉHNFQ¢EhoHMtw/n8yEOåK>]Hoز?d[ _ww89a&7D_]y3Y}V௿EƍOBPWxg_뤌 ~ BD"tu[oF e BXSbtL wuB?P( b BP(P( BtUnAIENDB`code-001c16ac87ec/doc/images/new_issue.png0000644000000000000000000005354715046233326016464 0ustar 00000000000000PNG  IHDR`q\ IDATxwXJS lH F% S=* *Xc +Ć"EA@G+?֬w5ฃٝ}o {Mf):h[ $ "pA\ $ "pA\e@;$(Zͅ "@3QBEE=L r0Y~5f#$$&.XXU]-$eiCg'{YEsD6fe4 "@@ennn?-$tDﲷ499Ydy;h 3gnmSiA 8?_ryd%ݻ-hR֝A?i$' rp`VSiS?ӄ TUU%-4r5&rbOko vrvv3oK+^KĢ?s̙ڈfgHU@^L|YillR^.!>~ߞPggV x $Jxx)SԄWyfFFFEEçOIW8qb~~>|B*++=<< !?077'}`tr#GѣGS5V1=|ѣl6jƌcƌTq/y<7n8ydzzB޽,XǏ=bzIs +"QCCҥXqcQMLfhOUW5sGNMM-BHnN-1 NN.BB,-L׮x#r FpP32%Kuz"" {޵{O}D~IY__RVV)WfΜTVV`0RRR80š &g~3j͛TvH-li%{͝;ҥKuuuL&4))),,ۻ՚A")QQQ/NJJz}uuӧO׭[w^H\zǏkjj>|tҤ$^|yѢE ߿mQ;{5޿tR^x%#5;ᛔ8cK+m[7ih'Qf I+7o{&wg=N[7A/jorss !AAA;y򤩩)!$??ٲeTeGGG!_t! ЅwA:}ݻwOlZ~,g?<sqqY@mԲɐ ʂ 'Nus7.)ei=pvuY3AM*'N mee寿ʷg.5ydue''tjٳge3gFDDݼySWW߼CBرceccӧPy8 6CIނOѤ~/KS׮]gs А2M81klG.];vd@[g3?_n MLL233~8tpރZU9!!; }$2eږ-:~5i#HrL/[[[UUUⳋ/2LYEww .X+WPUUU Լȕ.]_effz*..ktRqoj!Чy4aNN\TTdllL-StAFFF_9Y23NWTZ+#Fz>*羔nX-OUAD3eeeJDJ/_~]d:t0`Le43zZnРA-|NtyUUUSQPᕕQqqq|rSwޥE(LZ{V#H\f|('ǛӹsgjyQQQUUU߿3f4ṬA]]ƳٹaǏiyy9zk}iR5B |ڧO|ތB} ?޿aaaMk׮qΘJ̙3?,,,99!!!ȑ#;q: %S̄%% lٲVEEE}w}'C''Cѫ}ܹso~UeeŠA SO>;vy6ݝ~ڳv^ӧccc=zիijj8c =1W#888!1It=hNnn.!AW\yA^^^MM^߾}G=tPq^i"!A.q.H D A.H D A.H D A.H D A.H D A.Hѣe! l6[1@SES111 ʑ"+y{{K!h p A.ʲ"..>!1IQȒѐ J:;:Y'#Gh>$k׮6mlWTv&@d-$tDC_lذaJJJ H:탅lMN*$'s֧Wȇ GADww{GD/x] sZ>-dѣ#G={`0--u=A466.((a(m&'sU]]gO>#UrKvJ7o^ol6f7/ PGOÈ b˩^1̦L8p xBODjg "JX,˗E[^YBUUԩd0l6b:vr$BH 9;[ٜ>MΙs<-`i7^^}gO~m~oyHLs$pō 픶ړ'o\\,ozLGG]:b#UVn>ǿ}[W{,ȪUg1QUUˢDIK`<',ￋlBzcws|[9bFjB-1gGq&B76fL{o$$dWiUVݽ'}o2 Mf@" x»w3amme8MAM._ZZcʔëW{NÇ@1 ̹I a<]I>>q(m2~t[ ھxQHңVt8Ay,ʕTB/vvf9fĉnVfVA\rJit~UUw"O}8cT]A7n޹~#6'uHmW,_)O'KIyujvlFHx=_xu\**/UO'qbanc7r@YY񫯆&%Ta*aa3]쟐7BV{f ?v,8 ?ODj bKm@pB1lI]\zzUrˇs:tP5ʚ-UBm; .NMM/D[aN׮]u7nrܙm  ##OmU׮]w$™3lڼШSN6|ӊgUPx>N3ƌ\Sva2jmm5jYA»Ǐ-nfEUUAqe55:zֻ9N;vL:qb^ K.tSTTػfIIUYo)**CPN޶ Mݭ+8MVݨÖvgjYMMdP˥%%ꛙ4n{މ4kTaAAlKKK9Ga|V'y4hFfg|Z(2ɬig<~pOS[;>xgOc+*j6]75}߾0O߬_Eo;S[P]]mlA ?ODj74=zoҤ !{,ҢEC|Qq/!FF޾ /FWC̦X\R]ݜk]]mCQBHl쭀UFyB~|ٳ|ee%[[]pFDPsG@v |H <2Bq{{SGQQaʔAvڣq'_qԤVر50p'޶uweݘL&*|[433#쇃{p,)ӶlSSSСk !:igffa)~x|?NS yƅ L 0u̘cp=[.?dܸ~*hɕO?puw$`<=&ODig bU]]Y>!dѢ!|N7|"/[mfc/]qÿ\ //¢GP?ΛyQQa_~ wqAz];&Mff鿕M6:y/A)!cO}:1a<ILd%oo)DN}ם;/^2b$YG͇sLv`<#A( hd/@1a<6#A( h&@BBaxmFH#kY,vdy~qwk„6oIt.)>o-®T sRJw+11#&fݻ+0$t@QVV~.($ȊN1_DCCZjau ;z…:8tECֱBHrCOJ ړ'o\\,n({kK۷|}]'LOW U:q֭, IDATAVVI]#)iuVV=7<ɫgZZΙGx'GViϞ}wc`kppLP$ΜyXPPad=wr>>Ç{W3usw&N<@ǷjDD6 $1 `̆ Q=zdjnuSbHܶmB^Eiiu1šy\]{dgV6`~'})++BV:=xǎ/_ED$R Nn|yX_(\Rv mիi7nًg˩1|pjj*|җ@83ga-fvȉo<H2!C,/^_,,+{/N5k<3VQQ#""*ߴk𞪪JЭ6o0Nˇ響AEE(8xN""=llTT7^ƓI={ȸqxEXTڵc]^^Soc 0OL6@\]{4xQHa2YyWFHzQSS6'5`e˕{lhkۍ^<˗ErZZʕ\$**~߭woCMӧ(::-66J#+.:u̙|xFvJJAwa2Y%eeQSS7eer|(^~0ާ}rG{̙cǤ';/kk}]M5ȷsԩ|(ϟ//M:t vvԩ[>>?!)((lr.30J^;(((̞ -bHf$q0Y!))%g>~NfMMC}=㼀~:}߾0O߬_688&5-JM}CMxн{o<}YSӐﴠN''6TW'&fkǑgAAtoM5Ƚ SqHn.$?@=~hC !u6mPhǧΜiOϚaFPB3OBB?'L:HI#;>x5픔N1;sӝ;:tPԝ>vҤ3=qbXC¢9N9úu޾00J{oġCoY,N1Ϟ+++ښ5Ed'F 8_XXil=oךk{Ă>V4tD!o$;[с@>>EЫ^^6556DQ?߅@!JJ&  f}5~5ɂ_lƍ+l<+BYYJ111R1xCH>;U[¯q2x4}a5bW2mqt$#G33ޚX,ҡihhر-[KgwOm)g(ؑTTJ\!2h V7ih==u_:6 #d;;Z‚zEtt< L!YY_?n!~?yXF1vim4#d;g2=r Ƒ7Iu5"qt35%nCs8v"9ʕo,e@ۅj "@7y29sFX%KwblLΝp!$8̙C"GFx D ɓ]zaXr%%ߗϜIrs Ç$/)ZFv "@K)++ڵjzbQR@WmFv 7Hdr ӌוq!# JcBb ((0@[R`Q\!!d4#{-'a?mM* e8 \pYJdwxm \QŋdHaa؏ɿWkjx۶ Ud٥*66#,NVVĉ8RWXXAuؼ{㈈Ă ##s&Oʆ bCfW$`c}A7涖oov_~Iz MqH\ffĉ@:Z7Ap!52e O.NZu{UU_,H?A崿zqx_,Z֬ר[WwJڼƍ^=Kik֓rcohmE!Ob|95<<>0pb>/^]{^MMO "iVe '^-j5m/$o?""q۶ z[akwfEo5hPÇQHЪZA,^ cb^Xu/>f%i'N_ƈf'' hLL̦7m>~`;ԦDy:o%0IlVCZQ=45k<3VQQ#""ccUUtm@ ڑ={ȸqxEXT \+&ϸsgujsg~_QӧRPPATN{h SzsbnC/wVS@-\y>3'"3ֶjn23K3;;b lw7:q⸛8/ӨZlX X]WW׸͛==[Y:`׻ŒoWUUp+44oݲf@^GQB̻w7d G3|{=FzziDH^0$$䆍3@Bb= Z R9}pt R+VܿX޽Wf;/\L XOR|b=E{'GS=<^ATXPp7bsr^lve~[,>y*ྔQ&AMmmWŋQQWoݎeX!2_t"(|˷p >̵f;EٺmũTs7lڵM[Ο;ӸZaaAqqqTad 300\*ڵW8sMuiÆxZ OiØڄ-<{2HN۳8wLʧyxymmҡ#N}ܪiʕ4ww+--'cwaP˫W!~~sjk:iV` ʼng{xM}=!)鵟ijcppLj[Y~PX9>((:%%d,a:VݨivgjYMMdP˥%%ꛙ4n{މ4kTaAAlKKK9-aei|V'y4hFfg|Z}zlIM}! E߿ƍr#!@{q>quVaT2n%ȟ"6t(I佔ZEk|+F5.4i`h3f̰;|gJvM**yz[\aa̙{cw?Ŧe66Fg;QFUUUpp<ۯ5zyoE=b|[Iܤ̦X΄R]ݜk]]mCQBHl쭀UFyB~mb^b'4 dJǎ"RPr WAH`UU"M2cbb._N{yy&O8bӟ$E!g|VYQ%@ڱbco͘YxΝ+Wv`ҋCB9;ٻIg w<>L4WA5,үyB ɢE$9!H\5xyxy:i|4 ^^ @qp }L7|-qr",믏,[\9;ɩuJ< ?e3@[0y29sFX%KwblLΝp3!$8̙CH2v912lw1 xxEȓ'd@B8M/KƎpL2s&WÇ$/zGH֒u9RV&+VkɥK-jzbQRDX D)^"(1$dr s:1!Ag'dzgprru ޛ7bY 9䘐M ݇!W A77BHB"ަRbCg'G}# ]>Zs\pYJdB @( Tv$AEM] JCh=޽Y-$t_'Yٳ:mmMOur2o7ַ}=wڸ F 5JdׯB$[b79t(vt3gŭܻw7.[Rtf4x0-Ib1L&`0\\\O4Jf1!!+66#<|v:08x?'HVz…:8tECֱI+s^M嗤%''O:'++{H܅ )#FX/_>R]]bomAΝ{rX|QQَ۷_ f*u8qut4,p  ķ™3#" *uy^ŋBq† ^!!+*jBKK݇sՇsOl6g/@k)dDWCX.Xk\\fUU]}=#5m@n oسcuu،M.?w NK+`0Xiiŋ{7̚~~̬˴iBC%3gE3g򃂢gUUUr^˩={?DkAp "HA+-QۻucrppeVi@Z~ 8GG(GFFDA s A^>5 aH D A.H D A.H D A.HɨH?H䁙Y||l)fy`ee%>^dM333 H1!1MցܹCB9;9݄Q\!!dNTD)qss;hSp3p '$&: tݻwISRRs6;wnAt yHĽhM6pf|aB薄Qw1@;q`af$9ٟD- Ml6fIA( ? %$́"2Aeމ/}S=DKSq֌ ig !f81…ҏ @Be[b;gƀ ֑'>0(Y7_ڸյGvv9mmaz:.E'ygtg)_i'1SQWSgijiّa 3S(rxxM^TFhm8a+H@ bvٺ=tp\ތOLlt&UUL"]M|Q@b #ii+W,QTTh:AR']:+V׳I}g.OǎJuu ,zu7dQ ] D dX:Ad0 M  pnAmЁ*RܧY cܜgo5'H*$ѧwu R7c3"\🊆l ~wy;%kU&'~hM]̒xн{o<}YSӐﴬhuL6[YzR]R묢c۱^KPIS̤evJA)ѩ;.f 3oġCoY,N I~WE svc:ݍ݇ 7Ew! / "1$Rq_uo& uvvߖT~tщ8>g7MVzyD_x՞[,>>ZSn]wijSsΚ*!$ZjE]]]/LJ u|Ą35bh<_xOsBHsлnK/?gdYH-0r钯*la/ө g_ ڸsɯ'"9Y[u?ni|anrȏ3>uC~gGۊ [, 5!A$";{5޿j]%$%&\s½{vqwޢ$ևQ-9t舙Y͛68rmKeE凭< 6~UGW ߝ?w.ldh>ou[S ,zҸBm#OmظHSCkժ׮]!l>txRB;W ^&`TVVq ~__QQў={|>ϷZ`1ٟp8SN5UͱTSˋj## & n~~>չÉ' X윔b'__"ҿy<^IIH$rppHMM򫺪ر_oh4..S ґiai>)?'P|CQeϬUsH@pO.d2-iL7액/A|>_zG;;;^D L&311144TR#GNɿ ŋMJ" UIѱzh-=b899%$$ڵKu֭[$I]$[ZZ*r[X[?Ӹ9P A R{7 pww6Θּ~]LD||ݻNGF0߼yۛΙ3nƲ쐐OOO___'''H҃^tSPh᡺> , dι Jd\BF kk+aeeO 357/[l ),,d)))ڻm߾ͭir< ުF;Rwvӿ(*;;{޽ ɬuuunnngϞ} /LouRݦqXә ;zkiP]aC.Y=%#11qǎ+++: ի7ntqqzdʕ\.ڵkr\ p܄j+WT3u늊kkk322&|obrr A$uvx)Sl 葴=7͎AEGS_Nyw~OAe|PHGzSFFQ__˗MswwnLrrrF$#s~~~ߗ卍YYYc7xeG6LwܬY&,,ڴqƏ?X"(J5"~~~ s^2>377Bx?O]Ej];ˏO^s[|&-==2{{;tY>HkCӧOY&o5n\ |ӦMKNNˣ6X`x{{%//Rw̙z2h> zsYYY\.7::ǯjbb!Ѹ-+tuAD\3gΘa5*]숫ssM09_ GOu\wAAY RRaMGO%K^߽??pe ÚfGY @ "A@5 DPj@ "A@5 DPja|&:IENDB`code-001c16ac87ec/doc/images/registration.png0000644000000000000000000005161515046233326017167 0ustar 00000000000000PNG  IHDRw w4 IDATxwXW೔ " AT&E*آT"/vŒR RlED"EI}Xe(ʕk朙3waΰc:N Y@VedY@VedY@VedY@Vco Y@zT4X, =*rk;vpvHHH`0Ithœz_:S'B{O|e?all}ɓ',l666-M8177>rȧ~J)//;vlMM !FFF{-ZZwW\ip_$Ra(]x1222++۷jjjFFF#G:u$?SSS خ0ٳ,bmK6y5ki淊&?9rʔ)"[aaaAAA=x555ybYhQ~~>5bŊBHmff5k^|ITTT$'''''_pĄq֭[|>5Ç>zYDGG^JÇ7Ԭ޽ٳ r~~bbV%K.Q)))T -44t޼yTZRTc$fQLMM]fMQQ]RVVFޟw^ +B _耥GO:E߽{w5(!֊GL5xDϜ9Sx/ u֥ /˗/_^tILodgg/^"''aÆɓ'SUmRh',feeC*++[l!PQQ>}t>}!+V(//~۩䡦}:H~ΝӧO^̌*OHHX'"x/_޸qcXXX xĉiӦQ%|>Ktu]JM$''7ITD;\b>nnnT֭ۡC}}}uF),,tssxdX vwwRln|}}`^dRsUjWj{vvvsHrI0I%&EjG!C6mt;w]tGWݒ%K|ݻw9?pB****zxx)/(B@ ݷo5fEʩS;WW1cưlSSSYAA3g3gTWWSӋ->|8Ͷ[pajY,֬YԔMMMԬE,^RWWoV䄐e˖}'***=]FOV/Y[[hT-++'Q#Tt,AM$(y^h Ͷ{M)ZuiDkkk`Đ"zMTWW7mG${גSj ǎr8++'R 9rd˄Ÿj|RdXpȑ NK&N8N_\!xvvvDwӭKtAAAAAAXXuA'м%*++m&|we^k3hx.((ի5ܿ/_xⴴ̨(6˗KNo3KaÆlkjkkɿ##Gz*Ͽy&0]iGQ_GPoY7t; 1R&HxIq$Jw>=zjb })O>tFF%ل u;77?ѣGoN ,]T>(ޞ}vO鈈)RTT2dȔ)S~oۊ zZ^^rffZ_Qfmmml6::t(U".51E f_^Kӧ, (pboI|p||޽Gjii ߖ"Y?|_m8gΜHMݽ{ݻnlC{e)! 1ɏf]k- _(=qDuuwqqn޼m۶/^֖FFF66blBzׯ{X {ӧO'BoKKKo!܎(~-}0BSWW577f9n馚|:j{s̡gׯ_?uTjŋ;wN:%bkKxO( Cxzz ߽{wٲe"|.>}s\+77~j#b6;jԝ*tvv޼y3uܺ_P 5O/o_tȑ?fnn~ܹ˗/gff:>ng„ ǎ8cƌ>ܹs<,**QSSӧ_G/`7o|~S ʹJ/QAt]x jȑ455E~Ә&T| t .DFF>BMM~ԩ"?R:xc=zMMM]\\[bҤI{>~xJJ@ ǍI[ٟ35hРyYYYIGbsU~V|Q__d@`ddW_M2E8 իor֭G6쫯!ꗲϧjiiV?5\iiiC;}B/0~70@;Ծ9sΝ;YUUÇLwwwᮆOK퉭ul\#F̝KMMygmРA]z r!^ ֶ벏=y{rrr*++uuunjcooPK$\h'WLp +Ȳ, +Ȳ, +Ȳ, +Ȳ, +Ȳ, +Ȳ, +Ȳ, +Ȳ, +Ȳ, +Ȳ, +Ȳ3f 1tN,@t FdQ8{Hь3 1 Ȋظxckc1tȲ0*pg-,0J\.@p\O/odYh9\8]?pSB䃂1@,ۥ];NI;p]KV?]\{{hիɪlUUT !ήm۾%YԒ'Nl2aԨlގ·GѾ0 #@}՞=ow.<UTT !rr,ظ=T5f,@', 2mР#M >_`aa0{M Ўx-, rFdظxch-Ȳ0*pg-,0Jx'+\.YZYV8]OԊ<9rY Е(#8p.!SGG?z؁}hVHP,=Q!̬+֘y3N^^96[\'W^jzɧN}8_^5dHkvolk׎]Ν~AA6lJa5ǎ5?8-OR[ܸq܉1ݗ-,%%700䝩ަMMMcEř39[,tH55#ѫ)98X$=^Nm-ڱ={vSUe9B@c<~O11ѥf :;R3jfS|kt;**>_ ~yu77ڷ/d˖ Uqqϋ’w"-hBEc D zZZ!d䔈s@m?ȋ,+I&M|fZ``_ ._Jbb…#fhh(k݂zщlQ|aa+Օ!@GcPgk33'O Z=i8%%;.OM}M;FCCےXXBْF:(dYƸrXUxo}|X  jε#8+*E }}Bnv6O\r܃g mْM,Yb(ӧ7R,Eqt19w/¨_L4ɏbfg:K{~۶}wg„C{k͙c#Űp\\?yOOڳ疟ߝCz̟?|&qw,7thc\^**U-- .w,'R4cƌ`FdgL9ڷ L<ch<׬vc: 0b~㥴~nn=!gt$1nƏ7wwٳ%%33{՟e/GcYAdYYAdY`ul\QO/o[kø\;B7ӁԱ>-, rFdظxch-Ȳ0*pg-,0Jx'+\.YZKgYͯ^I"/UQQ_oLK'dMβ|ӧ۶ܰjEEՔ)C DBO-?Wcܺ BH@@\km =?z4ѣ!D&HG͚ݎ"!YXYYD_0*),{^\O&LM=[awKKٳ4WYYKJ!DF%t'II嬬J'cc&@\yI__%11gfq44|nOHHx{ӂ9Օ,, >|[5y>_]RTT1lXUUv#4'S #ƍNO g ! ffQOMT !shh(BRRrkڹsbP۷;a"ĕ=ziiiɓqD,iO*l eʕcZTT c-X0;׎r@8;m27';ٳmn .[gDDziibnʄ &ȿ7@]Գ'QT/ʒATGxoQG1}wgI~3>>;{~۶}wg„C{k͙cwСp#ߴv={۶ZZǛ/_>*BȠA44˫L;@SS̬TU|49R IDATH|{֚7.!!5{cx<3f3MǕ͛2h߾.2KC;fQ@c㥴~nn=!g@Koxsw=+PRR03߻wʨQ dY9:ptt~a@VedY@VedYfkctƺ{a\!˛@XSLBqvFN #sY`^TTLl\x㽕c֯Z[ )((y,2ZjZD^vؿ̙NNeŶ'>h?:|=}:a#80oee?U߳Vq۳gN4(!*O maՊ)Se r^w{{NOWAAN[[m:U/.~KN ?I̬֭_BfЊ:Ȝ9rrƖ{~hԣGy3\[[cܽ{Sw?Ηg gڱ݉g5WZiie|Z|q'NVv_쳔䒒wz675Փp{B蒠G6\%cǚ͟?͖'8v^7ZZVVӦ 6#U&z?Г:rB..u" ~ܼw'/P{ w" ܫbc/?+//wʢŊ+V^6oՕρT9}*…ĩS(g۾9#h 99oΟ_cĴ[KYYń}ntIFFշoM6رCu?޴i;kNkoo믑MVB^B'%JJzUVKBG%OknX3^M|:eKKB44[(>_栣b/^fqFF=l?%Pgikdԃ=^t҈%KԔLY,^(I|ɓ|*%=Ru?VQQTQQ9Cu1UI>!DU(>n9uJ*J9L>_P[˧r'UhgO?E:b!+V8hk ɾt{ĸ[7咒w55U\|B.5KMQVEE q7FhB޽!rr,MlVVV41/'LJ +|}#S%% SSG/>hhplk== UVV}咒r!}h $22i`R+yy9+TH4 @ѱ!ž=|koO5HobJEʛ1_ILYpĬY %>_`m|}#^x>-x ))' `*uu% _dM<&ggU GUH8ߟI1[+6vjf֓^@>{VH8P"lu !shh(BRRrkڹsbP۷;wY|w8 MKK+O#BeT*lKrΡcga>ZjtRҫYTS/)ytɒpuɱ-*ɱ,l-anO9wAUUͳg۶]ψJ%%nݔ !MVo|9gO ssO>饣NݩD_%RܹvPmq[cB3xpӧoXݻlm}|GOG133]qwg-?;?MtϞmJ--͗/d!dР^JUԍKϝ{bfVw*E۶K?;&5o]BBvk@;x"E3ff$<ch<׬vc: :1@{, +Ȳ, +Ȳ, +Ȳ, K`: mkcrM~˵#xzy3@[k B1c/ųZN@:8EE3@CkQ8{V4Θ1PkR @P!B'`bNhW\7,l&M4x\[99UtȲ]JkkWMM…# SS):yy9 [r!ӱt68Bc_<U(occ~STŋqyyesL<*pvmZGfe/X0|m@B,Qg=v:'ssvk)7ROٱcopEYYq8skdmz} ÇyO?]T)@[ˆqWW[OK{uugO;' GQQ^[[uJǸT3 >xpoEEO>n MuD̖-Ff˛|pd!sp.uQɱ9;u?Z02ҦuS@MgdYZU闛\+--o͚›nfe.1?aɂ ""VhCÈ14C~:￤gibZ|8_qSȲ fq<Uo_HRRNuum~:}g4PL0=DL5"|v{bb@@\^^96'йlIM}/pgOѡ+{swzv瀀8u]\~v]vLxKwKd?xiĈ~7n,X~o?,M~iƍ'b~տc&y0l)/R\KKݺu9uuN9 {/f+ꪯ];V8S9iȐ>ڪ+W:=nnnQԔw,I9s&a('֭s:}M)aĸhh()--Pgk>-nOx **99]kdMOw\YAdӦ sqqU_}n4ۘ"K˺3uKK˒)!˶ssOZBB=+IJlpDYlBM v]b5Վ&X?ܷ/lV:M)aĸL2?9=mڧտnRR=NLYbaw6[r^vsC23w6N{xLͲXD 4T~:￤gibx:dٶ`:xpoWqq++?TV~{c(g<~kWSOK۵+_񘲲UU5[\oVKI L.)ygjixSS=zG6\%cǚ͟?͖'!T?;yyes؈+ :źVZZˣGSRrkjjӝ3f3j~RKKpڴaÆ}$ sCme /Μ.^}i ٭[>=^2#g:l.]J )/vfmNL#?|1<~E T2\8uիY,!޽K2s54==o[wAu뮤jkk\VV믑G|# sC=Pw$R.4bD?jv{55%S d===s&+֭ͲbBȊj77^X|-ںQzNm-ڱ={vVrc1T}$VTQ7|8sjE1U8R\50$()ӱ{kBXbqqϋ’wږF?'R$ccٴhhplk== U4d_99YWs.1kGCCX[iFh0J'F$$=}ZiARRN@Učׄsm44!))ވYOBꆩEƫ6€rkڹsbP۷;B=+l sCe>!ܹUU5Ϟnv;׎-.~*ym,WT߿?ӂZ~AA A.[gDDziibn߬, sÈ8rwСp#ߴ)umۗ~~w&L[k-, rFdظxNKȲ0*p:-xF-,0Jx'H͛7Mbhhhbbr=;X}0!$0p]jo%BƶH*&PbG䒷o&p8Ie@@Ր 0"NNN555B_dbgg`)SN2400R:7)e?/.+{oiiHy ^߾ P,N""*U_`ĉm̙{YYEUU5k9]۷;<U(occ~S<ۣG^MVUe;8Z娢܍Jh22X,֠Ak֌;Q!hq%y7.!$00?:?@syNMcUYLdeS]]ۯw89 S.ES'o̘1x{<GMU"LOj<ɟ%3gKL|Y]]S\f&WU}(((߲ڮ]ARlTDuci1cUU5o޼۱/f.ᇋG+fӍddꚇ_9;J7"~?韩S罊5))k^_.ES`;wH… %%%<^pA HdZ%%ْwοY1 ;s1z\--=23#<*'RlTG[2#-+{_YJם;7 &&ʠSUa4V.ESdYh,!fYiF3 ꥥBji +&&'~Ŵ5k. ɱi33}卌FuScc*|H;ڨ1,cl܃.P_"]"ĬiaK~iݴ*Rϴi\\~st`aa`eW_r)h=z 2&^$(pam-, ""V{Xц WLLtf+mmHQ Ͼckh[qƈYqљXr)h9*Rtuu  FDliie|󰰕u-/rvRSS.d@ =|8_J 9>>wɲۨDےuMMz 6&&fʔ)^kV}x,<񔗗3De144|a#FdHrY۷;e"///=ƌcYڵsO{{͛wf\ I:z_:N=bwrr壆CIL9p ,5ڵc #gg ~ !. 22޾Ah(:e/\H\+5UUSYٵ}ɓYYE66;uJ-~pdVV'NضxGF]vp0]QEE L/30М=Zxƪ8]۶}y̽b*޷/$))_?ﾳqr(\kÆOgn  wvml F gh[:eSS_o:~9wϞ[Ǯ[dnnP^^u`؎;u͛' ?tYSS7-ߗ.jciCCC?sDSSǏ7nJ"rDM ㏗f}"iA@@M+/ nvz>yqci= $Z:O ߘ1cծ55ֻiKK"rOjtUjj̙$۷UNNsbb2骨 KK&,-=RSsa4V.C$sh7[BΝ;M… %%%<7^pA H\VCCHyii->a-6/0SE13̴i\\~st`aa`eW_Dx@P-jNgYssI-, Y/t>_Jn6lbb{,}} 6[ok%ziFL0W;N`<::s߾￷S.9= E"lyWt2S ~paei>mr{>~/ɆsVeh؝V ܻMW=x𒞽$U ̬wٸO:uj1M TO6@{Ӂ]]O=PY!.$?Y~_UWVV~v%;~<}UUMDD-*]SS_SRr=<$jV0nn߿]u\^4ŗGz׮`ng{lCM1&l4d_߈"BY/$ɺ}|}#RS_ ٳm\rΉA"i/_hGPQQ~^4εݹ&_[9r'%%WAA~ذ>{|%>~]ֳƂ4Z6ްxÇ>|f0TdYYAdYYA@GG, ^=!L"JaƌL =*Rtuu  FBpp01HI[[[DOO$Zc8E B@ 'ٳ cw? ,m2e岔۷o3~YdYxkjj +{YcAdYYuY-~sYxlnoTTS啕kVhbzcT9=򹓃I_{͙ӧ*BFekcGr0x肐eyͲeee~}-YCR^v3ee];r/wb #B'Ěnn+HL>Z'{B~q×_/; !ߟkiB6nrn+BQVV./*,իΝEj)5NYasw-mI"G貐ey=K/_f_cZZJ޽ !yyy;9˰X,B^4$j!CWVVyǎ\X]]] ƹ,@, ̓|!$"Ȳ<)@ 1}s'\][Zr|O֬v4ZmφСD3E 2l={Q ,:y5X㒇-K.5f̘m tM^3f|VoX[2Jc޿};xj7F R@B ۗ.[Ç=ݩPYlI1p0OvW. N?ѣ.[Y,0OvYvogVxCJe,dY`l;ѹ@!@g_ ea6֗.9rӁPDD5QXEE3 XsvLG @\dYYAdYYAdYYAdYY&r8~#E08]JNk٬ZBPP_234HsY )VėNۿݻkmk׮uuu޽{Ժ~mTaa!Ci$Z UHeϟk.xb@@@^^9s&OL=Og/Çgee.X`ĉt;Gﻐ'N74d_x&Ut5SË]%9͢{D H)MfI4 bpD3(./6*9bSՖ6 R˽쓹ji3=̤tAaai_?B.67/_nCj.obA`xrH>gR#kW[턄BN㯧e^j67nܘKL~)H EJJʢl oߎJNN>vڵkUVV޼yd29V8,j5wouu 0 (..;wqz>--c399p d6KOeVf2Y׵k]\?ʵ5a>>>mL?Jcc/ff_}a؟~OWTĄj9wŖnXvOKKL&3 uT*{4Bbc7p]4!$+ٳр}xx8>>voNr|Ϟ=qqq "h,6ŋ]]]Vv{dJu'ӛ,!$##޽{f݁Ep&***iZ5|{8lkrُ?j;;;kjjryAAnND.kΝtԣ.kJ%~kY\"aaaΝ%IOO=>˶m6884}+16Bzz~nddFY[.BRB8{&XArJ,"##id2 B 'X~y%;;eG\.lNN7aÆn~-**NsnnNժT*:*Io6kZ֭%Ltѣ{oumm+2}t.l33.~ #˫F#tHRt/_>|0::z,SSSCTTT9quuu.Kח eqc\.W*:77W^^νɓo>n ܛ*ҥKFv î]ʴ˗SSiӺ}}%#wfUۛ<|;nw_0/ҦMtܟe߻wn?ylV*j:tЕ+W Cxxx|||uuYj5˲߼ysqqB̝XgQVVƲl٢P()6t<}j⋆>ZOosLXq~ ~Eu? !IoaLx7wٖzزfMT*ӧƾ1AP. oLhUY7)IBA ,PPe* TYU@(BA ,PPe* TYU@(s>⢣ӕIENDB`code-001c16ac87ec/doc/images/reset.png0000644000000000000000000010737115046233326015600 0ustar 00000000000000PNG  IHDR] sRGBgAMA a pHYs%%IR$tEXtSoftwareGreenshot^UpIDATx^kG`al(y0p|YZpc<lA;N9gE n'Q ;A-^gLp&`5ccvp k8 |3zh]]ϻ~v! }?x7+++++++++++++*ڻьӥk|;eIaç!O?on˃+"J.j.j}`o.|m^韃w]`y`E$VK2q9l|s[%7.Gġcv ˃} +"J޻W2ENy>s[%aq75?[(MOǼefx~z>Z9GsSVMV+3>O;ݡIe1^s=4g/ZI2WX~zn?~Z]*GǧW)tQ,soqzΝ*.hFY67 | nkw0J?]f 玏gfgk*蔤|V7WDC~[jW@jia`GaE$V]l/O{+L~vv(ټCw|5ﻌ*(r"6l]5F@܊:ՇkHs"y  `Yh߲]FO-۪Rhѩ!c%2뭵eu#Š ]VDmDh6OwJQ>럚9\G pW$t|I[+y! wn ˌX!hYd;LƔ"Mz͹ g,W;XV ˅;4n.Fٿ]+HC|'ѹ6jgtq~S/B˿v]VDmH]uպq̙:-UuԊS:\ݕ"~r%?խ cI*5!3˞lomF*7<ݘ6yݹI\iݳVL7ڤ kl'8.J0=f2zGx`"Xn쵍rv$F쿹/Zz8[6kYZ^=kͶK/c@qZ')54nyvVDm'ab8tXnu}RNk1/к̃TqZr+d^|pXKlmqSd?uFX3])1@rv%t~RͶ57.N[9%ͷKּ)7]90S|N拵5Tl.ڿ{k,0zI85m._T%׋3Ku]VDm~u1h)b v)ϞmknσN' 5Y:[UQZdX{m 7Lm6P aTd0ޱ&r5/CHkEs.DMo !DB$J$ l&],̕hKjMP2`ŠHҏ.uvZՙ6cپvd|W.AQM,g;R_iV.6l`&闋Ad jl6 ?:.jbD/hHwОf )hNxt1 " QHZεN]ekP:1+*q(WoΗ-K^Xx0_b mLڙ v h M)d 7fK@9Їm ސZ7EpvbMcʍk[{wP]8dƎG|)*[./ZM .'Z_NNZϠw ߽ kM>6amE#SGǢǭL1MnE3cq a(._c3 @>s[ekݷD//Unԛ:q+zegyUgi?phomjYFWI_ ފ){] /{I= #"ا"|nlsoYKOMIZ/LdJwF%2V^Dejf./Ma}s/_ T$KDL R'`t18V $lF٣]/][lF-6{koƻ,`ŠH𹭲nLrclU:颹~fOvٵebf %tж ggͭվp۩8S"/F13׬91%-D7$I -?"8"|nlf83i֬ΐxޏ '+'c3Y}.n4]"`RxߍPzbGwvnPzyRl=6p[Kf}2y,7ua4N,_-BV"k$k4hiQEz,wXZ[{жv&_KZ/Q77NT#;jE{=x-wk.-7Ɉ-ŠH𹭲f},o]t?qu$̞`wma9eIgcބP2dr^]{HaY)Hx S gL`'|xNӲ6ƫ\h_ ^K/^(*[ݯ_\n5)2Ljz-qgt*>51Wݡ z 5E&\T/Zj*D|ͺ(TpŚnA3%vѩ{K$ǥ)S NhV!,_*6ѳ֪v?ڃ=_O }=``GaE$Vَiz[f@SNT؋\/a& K`/%xZn~tQѹ[#tS{ JSK; )Ϛ┶rt<=TގQ(nI4丟HfwVy&ɗ>h|R_AKӐ1`471U`@`GaE$`_VD;Ev VD;Ev VD;Ev VD;Ev VD;Ev VDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVDVD`++!wd@VDu/"ŠH]VX ֽ8 +"t@ZaE$X.H+^Ei`݋ "{q@VDu/"ŠH]VX ֽ8 +"t@ZaE$X.H+^Ei`݋ "{q@VDu/"ŠH]VX ֽ8 +"t@ZaE$X.H+^Ei`݋ "{q@VDu/"ŠHݕs̹.~SW/6V5>I8zlvWgfYXZ|4ύ@} 5s"RgF\<&k>t\*2&.LU.,kfXG)X ֽ8W#"LNX+ɿ*?u[ةwَ9/|.'ؙReRͧ\{wKRNg+j3X%Owg3p=ؾ1)dJQ̯`E$XGQjf{k3/ONuqwg#ZIt}n_pv/}3p-(TIWo`݋#n~/3W,&;ɁE~H| f[tS{W*#+"G/͖9HgF 5}@Yc f*> +<215;vtϮ?ݍz<+N:<ʮ߫vW ܯy+3v|z !{̒vmJhn,f5~vw>7韣K$6.eXaJhr}Éփ A tVlvWS>cIp,˸DlŶ x4'b!#ӭ:k\3~ZT@u[kWHb6|TU />ESk+x,mdWuFJ rQ2 t o6uNy|D~ B[rem2~OkIvGOA,esH;N1VZE͟A<+əB1[azABAPz/tQDC+^x+he'V:FۙܩI勽?X:Ns26ݍf&/z5I .?TPhKRԞ v Rm|TeHA>ŲBn]IG\9UIFNdҩ jlEi,+9<.kڦҢ!M. .<n)Ãgk;&s]$W3AHlG䗓NIɤۂƢ=24E^UdMkM1P6PkIs.4M0NdR|>AP:8_X ֽ8v\v` LƢ5yɘB&GIUHO '.sQ!sKTCVZs*."Ym} KVm}՗X&;!ʡT*?ln|*pUstYg(2DX>"$IS}E%\F ˏڼZcBTd ׳+CQ!㨖. S;*ۚ.Ƭermh-b!x:YX^w b.QKBPTQ.~#؄JiqA$P4l5Y.);Et;𢡄7AQ]Mftg2,E/7D/p&T !nxz3*t V̷BV'GʍeY5 jdp}6PI]2;Hu6`>"l-lȢeپ=APa&(?;1cշc@Tf?W_c]*/_Xweۗ:^wSTA%n^Az?b> g{ Kkdmn.:eQ6zn2'EXhX66A lV<ɒL:OX1_^m.ʩ5oihWMoAQcVYmջ( jyRAu-d5+;\COe3Wo-\'}0q/79{o4wxil奧Ʀ)("Jdg2i]Ћ eGfOGX>"^ (Y֘޶ $$tE\^)I*uBS, T Ocm]/> I.*ȑJusx\ NmE_~JA&ѳK1e"}_AA/Cn7F@y5TqDJq<@4PJ^ל :og+,XW1XFX>ڟUIv˞%Df=.Y=p.TZX.@'kΗ+*W? ~-'VDu/b9ؕoۀ(Ti_3VE\%р ]@wVDu/b9lة'rP+b řTj1wW4Fn!ŝ`݋F] +,=@_qǠ?9謜=Q 2]iX ֽ8 +"t@ZaE$X.H+^Ei`݋ "{q@VDu/jϽE@c+KAw |I0^Hě&Sm^-keײcYcH]*)2_@tq_ү.^>f}|1N⬱_`E$X.nH.@A$/mE ߖv w|V_"{q@ tq.>(`E$XE{7Y߬aX+aLaYI+0"?^~"X1S&;J3꓊A_REACyWGXq3OuElK=]}k!FD=CTwYY982]$K4cXã3֋cQeѹ8%3z4~uG.ϐNjvyN_⯿ }[zCw٬T1q^+E|1/_;6yfm?T$GQwʕ0zujX/Da{=̱ҪsA$8+ ,6@ B +j+PTk\R_t[kNmqf~|SBm *TL⬱_`E$X/n/Zߣ٭OGþq_ɶ/㲚( TS/M_I`2,'*ABGV* J'"ʷ2\ҏqQEf/:X~&~F+Su4uY7*73UYcH= ".;&{%@a8OCC*ZgiqAy7np\_m/͗Q[$`'!1],K%k%I|sG}azg 9.>X<>6jDC`(!"J1sEG쪑qÎl]Ox(nf,8U Iܒ.j>]@-7),qIF6˹r+^Qzfj$V6c*oxL] cC`-5AA%34@UKU^,bz!9Dy뷠4b\2qWXqkrTE*ܡ QTyDrREQq|1E5?KE#nj6KZ_ xe,ߥ4÷q]ZZ̅ҽS3[6{j2&T!ʢ DŒrĘ)t?]\Pk2oU3ّ&JIEg\"0ÈxVx 8kX ֽ8"»5!jM2u~켡> 8uϩQ +٬ ^9YM 6_U<7D<B<@n3E*{k3r.R4;鿐7VHrMHMn]XʌR7fp} M"Th!𖛨)g*B׮JR,i+xD(Oǡ͕TЍ#S됸E Š7Y_b>DhU?(; nsdlE2Y1B~⬱_`E$XH\KEAJwn*ھByV4-= hyK]w@]vJ,.mݸ~pnzRF$(,לo{Z-(p&iF6ۼw 2Xe'pM/"(es__B/ P3ˋR/赥[t=7BMHMlJ&ko~ҌmΎo6W4=hI%ԇ T(r~EF-s0@4S V6+p ·IW/-$I}x$DbRmE]#K&v}Z&Pu&3+vij"b8x~⟵?`E$XHvzш~s~#2lfcQ{zc@2]DpP Vof̍t-S*l]o #ӭ=G&b/ ,"{q$E۪ꃫuۤdN L3tMQ߭jߐҗWzf^*>+"G]m iaiM(ۣj^%8?RQ.6bK}VAs.#R'I898pX ֽ8baMӹRLTIZ"-k3_R׮peUIHN2`݋c{t1uz SäH>WRe?UMjzcVDu/HzCJ/iu &8*EAڭQX"#g78pX ֽ8j.y$Z(CxC\t$Pig~aQ,G VDu/$8<^n+R_rFOgٿ{ΌBC#i^ߔvkdt]^b>{ n!P*(`'`E$XH.n>Xa8{s3_".`݋c'tQv~{g]cJ=z>;*O\mna66~6umESU:3KiM׿.w5_}ӻEN/s B ڳ]tq,.~69_V.H=>qqVXImLLe VБϛeD8%;fL㋂{Ք!co7SMzA*Mi6vZ;E}ןBVQirկ-i3nD\#~bYi;\uԨ\Lg zE/ep4 vVD; ca]Wຸ,R{RlzJr ъk{?}GQ-G(`'`E$^&9.Rʚk壃"m[2ƅ\$|O k,7?fc۽{3W" }SHiELxli##XT&ehZ{0\jDž,7mPtݐc?h3H w EPUw 8@/W,ID_>6Ώ˟~!%ERATB-Uu7?oԤ8EQB"`]|42irř>}#5Eu{U3gnb"8蠸/W#tQx~EяОO~Ub]lߐ]4{ӄn<𒖱-4&D_Ŵ~;c]W"u+~AgG~_6Xx˽3Q!?}7oF&.}Ewm]Dw~'W^ͥeǷKog_b?TK?:rγ꿽*.[I?Џ>|;8*yo_+ɓOe*ȶ%BoLȍ7.K*a_]L1[ŧ7O?+CG׾Z^^pbD8BȊoW_.yȑ71~8+Krt߼.<{_.Ӎo?/w>wj#^}#?^`_=>].N-'_^'cCtܑά>ӥW^$'~Y!۞%e9K^ԵOa۞9p@敄k|"[dUt/.Au?--_{GޜÕ_9,/"4}u4HCF^}W^ʓ,}^17(E<4O] ݕy׎ KjVoj>6aJ\E=s_?f[ 7@"ꄇat1$^kǬ74!z!{ JP$pgy,U}w.FLr%z?>)]#$s.R^--b _޸yoƄ.(X>G^?)7>} r6NWa$萅XO^k‰EKz-l[Gؼ7BAAdKbT& hV1Uz]Ho +@U_K"ݲ4k+G"Cᓉ2qMWuqݦuCk"N^ȝ!o7NXD<4:>Gr86> 7aϰu7iM uqpFx `ouҿbEz?Y9}ҕow(ރk׏}74x4x\N 5##>rY{aBFI|}qr%X&tIFյ+G^yED%⡑b":_wLE$_> Cz/q&-7:#o]{1]Q+ >;ч^y v{Kz_^h|)>_ YQ!7:7O_'E_ 7 ^&+76/p(aRmۢOpe`+ǶM\_ƨ-oмq7Y~], ;)&. A!X!]{ "c_]L1E"[HKb./w@BXv@S tDҿbN``oaE$, ;)"[X Kb.=VDҿb* 'vQD!^HXv@S_WD=A?Q8"Ei/.H+at@ZaE$, ; +"a_]VX K"ŠHXv@VDҿ "Ei/.H+at@ZaE$, ; +"a_]VX K"ŠHXv@VDҿ "Ei/.H+at@ZaE$, ; +"a_]VX K"ŠHXv@VDҿ "Ei/.H+at@ZaE$, ; +"a_]VX KŽi.WrÊvo5e滵k,Lҳ+rAD|lvWg+Ptm'9aB c^.vg|nl3`.n⡂/iˍ`Ul'%[Fhͽ_]+:: .]\Yuv.9s[]˫/2.sMï8/7_ȟY:w?M_j*Gx+IkSJOH6T?-.tgsYc?[CpϪ_Xn/GTb/ _hӸZlefǚ~֬Bø 8>T2/N踰y. c2߂Nz~rL/9Y= t[kWܔhȀd4;zݱIpb>~rpB6F=[,2WEfҒޒ]G'"RA̙Zqۢ`#uř a\BNm _Ct>D(IkQV﮷wՆ]+A$Pb2#63ȐD?+r] bed5ۻ/VR@1<0`E$, ;"uљΉHPRM"GߡTaQUSFJku7Q,z.ӁFq.NW\ ʡ'2: uGu5ftQhrR&o}Ft\2uI,`thl OHW_Om D?+me>Y:+M.r/tUOdŠHXvDɅ'-&]IuYOe: 5|!{$eHPq*gIJJx]L= *ב4nNN繕u@մUl5VL~urٚ )kI;Qj'F,̑ -^f= }>="]}==>l_gBwe窑$.&quW{I;K AaG.XR Lro.iI5J468Q(dًFxK^ޖ=g@GV(zx'ԜnCP&Q+TY[ "XƜZg5OFxQ:+Q $қ8ZbN.J|OStJԍ>ܜs7"]}==>l_vgBVe}ɖj$jD֠j5b1:/EpvͷzTr~Ӻ+.KoKjmro٠ũeO4dNN'K2&?@.z{ AbQVr8կ.JEW1ǩ$ʳS^^;: zw"b3<{_wޏ5"-ڦM3ˋNv]U"Hx|#D%ɋjS#'m ٗC, ʃG},6.G'qY47B[,z՞wk"/Hnkux*K!kߙ ( juW/y:hޞ"[J){ݕsxӖ u|d!]fEB⍽B'lwv{$֭4hN\ [9uQйTdj VDҿctw<9q;*'j"cY?.JIc-دDMÊHXv8㢜+\MIg(0F'gVUp`E$׷oZAE VD_/]VX[[U&s']VX ){O[Om9t"ŠH(|B CC  "Rmaj~@VD⿞4fSB.H+R3EB.H+)~PEq@VD_xQt@ZaE$"ft@ZaE$|x@VDҿ "Ei|Ö "EVDҿ "Ei/.H+at@ZaE$, ; +"a_]VX K"ŠHXv@VDҿ "Ei/.&.pX K_( "] P\A:`E$, ; 8@tHXv$!p4 +"a_]5hVDҿkр+Hatq׀WX KŽͧM;P^~?2ϚQyAXyz{faakG>fݨ|L/o=mϾ_:q[]/|75'j!{Z~Qqx.}vI GS WX KŽͿ(9TQeɜ[u$t棌a ̎3#fnTf 7]* )/gIrn"_et77Oλ G9򹲌|uYޫbEk|˗ՋJGO|VwX|ͻ"Vp4 +"a_رCػ$..daqrK+,g-i/ e|O Օ#_4EU/_|G2wΧ+,>U?PuOYo;@AVDҿct.iEւ s;sS?+D07/ҳ3 rN>jGvTkùL[[Һ^'Տ7 A-o 8@tHXv8ïdjS3ر{mF|o~,VJajC g#7x4|"'akW(R.jE3pEȩQѸ'o?Aр+HaGu?(cg妳nM~O0'*={u"MX:rE+8]TOC/ڗe?+8p@q/HAf CZcY)^VótujQ=QVn'8hu ] = -tHXvjj}c.>sqԏu1~EPet}ÿIWX KŽ>tqY7.'l9w%iR9AuzuR괸qk(. !5 8@tHXv/_*{KKkmmo,=| +-7j[)^1+mQ[ ^|W*;2_{OWcG;jcr YܸE]TM{FsᑏnX=T8p@q/K_nEGX9?!Z).Cg_?ow6gn;JٻCfgo}[P!{9~@(h;9vR t 8@tHXvv._& p?'_;c9. }H/rĩt6:Xv@wĺmfN|ʿ=@J, ;VtysAy~zD\~owK~&x䧿:e󇅷{~>ۗ~mdWt׆%H$}7".y\Z6z|v5+ڨqCZ#<+۫t÷ӫVOߺ7Ф?>?|՗ gwd3++tաW)> y72_~AVȶgI#G/’׮|!umSض?ujh>y%7Xv@wAu?--_{GޜÕ_9,/"4}u4HCF^}W^ʓ,}^17(E<4O] ݕy׎ KjVoj>6aJ\E=s_?f[ 7@aCBK⮑Xx嗧OOUx1(AU!T ݑ2ɕnz:@v|H^ݻFI5{G޻x>Rd!zWN+Q¦E[ּް}捾Q@0xXv@wĺGo82tOAuJ #.F,D`V ~zw^N.ZaoO7WE\8=A(;-HuCSJҔd &@-b]/*捻@(\WK⮑Xxzg}̍;JH!3O7V!ޠ@h[oLzO+䡒?I9čkg68lQZ>yco.H.]c ]k4o=rG}~[u/7圿ƄlӯC f(;o98i袋PO27IEx\^u&QS϶m7F"aa_]5EIC.|Urj^Rh[CJPג/.w|6 ++ʑȐdL\|7Fr]{iݐ`㚈ӫ,rg[o"(|葡o&8=rC?M}3lͿp,acmi9kB]ܼ9c|"8lZa_]5Ez?Y9}ҕow(ރk׏}74x4x\N 5##>rY{aBFI|}qr%X&tIFյ+G^yED%⡑b":_wLE$_> Cz/q&-7:#o] UG, ;VtQ8F?3@FzN/J/W~yzpК~|[\g2dݳGg<旧)xB|*DZ O,,{uc+כwCCݣȇI+ImjEp Ad, ;t$atq׀./w@a/.E"8l 2]ctatq׀.=atq׀.=atqרT*+++uD#VDҿk^I4D#VDҿ "Ei/.H+at@ZaE$, ; +"a_]VX K"ŠHXv@VDҿ "Ei/.H+at@ZaE$, ; +"a_]VX K"ŠHXv@VDҿ "Ei/.H+at@ZaE$%+" +"@`E$yİ "Ei/.H+at@ZaE$, ; +"a_]VX KŽ>t~93,.>Z䘊ا9ot\*/<>B,Rn}_kүcYϳ:}yPyRy=\s8Pez\<>,ױ"u׸Ɉ\n>(<_W{7?V Eѩ4D35%)G'|Q]< /HݕHLvV3]ΧGռ~jU@rZzum$.KVӏuNEt?7=gO DrL.]8X8HlaE$, ;bzB$":ja]*ʍ3cǧj]U>NSS%erS\\WM[/,hRb捺fѹ8uTo4~uܼQa̱rK6^s9yqfdajlvWSgqW^g/UgxD/5Dqnj3S*&ã[*zt[kW9E2䙚7 Y=?9&ǟUʀ{UfM7zX:?qVY?rji9`6ڵw'$Y9np@]n N^6:^[ F+KrV=s):X=E H8Wk4fC&TV,8cj.U?RFlX,*C lv[KE^ ڂh jM+A1uЄJgh/:KJu$׵UIb`E$, ;ꤰ,O+7\2S'U6^gY2 ӥ|⺬qy5Ŋ 92yeH\& Sd*鳣l1DpV(O>Dⲱ3%xEEZ,'.ޗmGO@q8-Tf ys~^(7nͻՇ.r>'[Y 跨rņ ɓL\-EK[T\঑K6 O UJ,~ I*zSge4Gf+V* ;q!6E|fg2A3v4RF;_}~]ũ\Ad(*>+Mf{f s3vKNsɳ;9%&OVij1ნv[Ɏ+!D NYhJ3ۏ.lU'ğ 7-0摕6l8.66TmgCԌ|F0KҚ)O~G=a^*Q(]Z9q] o`fVf,IIj.袌B/C^n tGn#&v;Ce-7rjprt<_b`6bP9J1DfW6)e$ɋ/ErFlrN\W!xuiָOT[Y٪HvEÇ`JQLТ|}d~쨭L _d} uNV}o|jS(B&:6'h!ׇKFmlŧ/]|*RK?K nTXw<H6/-cvF.WyUy^S*ɢ^Do%j]T_`x۠a.Athˍ <>C,|PJV0bKDU>~`>_7<}˰1f(/VDҿ#VX m(W(1R jlzwlbe->u^* Ҍ@>7֖_Y4etڵ)3nzflHɦnD63XP};ۉnYywvLvNUaܨH:ms2c#Ŷ97d3zۙ1JںoZ1ay6arha]C6 k̊? 9L.2zܮ5*8nlȢcUZݚSfcx:yZЩ?^Iu0`_A}6HXv"|zXyZ(p [42CP tqX>"s,?ylzJ>:?'(8}غi,;>WsP|'UisDyVG@%d1F plJMME $TzuXNmj*x@k6T<@w(!tR)瘬W+#3?|3$]/҄B5d&M%(k 2G(7: =n b[aE$, ;bt|yP-7V]\&"eQ $]ۨ*Z'ݮk{TY+܌\C+E,FfݞoS9lRS9TWK(@qV0'UgęJaj~b]5ECjLVswA*BA%݂^ZuYq*0`Flz Z\*: =nbaE$, ;u1(S ̥>le/JFwm.RXg"J Nmt1IE 9zlQ)}ؠq*O#Q!=-1%[n޸(6dHlp,~b]:J0|U/R-Wڬ[;.&'2CQ kڼZo؊IDT-G.;W yqK +"a_m1S^}C+u7(9u3<aeKta޵}{Rj'Pc"lFY:.Zg]T!HsLmHH(*3!1غb8%xoqzT-LFfSQMlD} u|F|+,.>+QBGt(H5&1dTFzZ)g jwN9|lR+HTX"/Y MnQH:zh$/VDҿ#Ji(5 [9p0F~^Sc2Q5V2WͻO-7ur)3xV B8klT#ׯMݠ=.R+8; fAz٬(c^UGz?cͺ]͵*xR2:^^ ^YW0Vv;' ]w]OxҹsHTsɃ4vfhUBpWƳj:G3G)3vJM%hл&ѵ j:@s1 +"a_-no)Jk{+"ͻO脪&zFO˲FY.ldbX颠]V;dN=Ҥ~At0oU dge<.rVDPSSHG{*-Qi3ѳuMW8PxGii +MMM__: mSIPs9i.3jSy0WMPU`4ngJi wK~™vӾ~- A`vlxZkL(|c->/VDҿ#TyŷD )ߙ/QoZmN`+.JGXWHO7x2/%O5r=YI(>MXYcz# [f (.S56H䊵H (>^:4_/.2D(.H?b2C +4w u(Qۥ/V5,z^$VH\HŶŠHXvDNXhsBpKX K"V٩l" VDҿpr[.`E$, ;r's`%Eat@ZaE$, ; +"a_]VX K"ŠHXv@VDҿ "Ѻcٮ~)Cۃ, H{'Dž䚃Mb6aN{vY &X KŽ]E6ҝ@ ]E B Njuq,aǮ%]g&t{mjtI.H;at]o@w"VDҿqTU߄f% /-Q8 }pCyv7 ˭ż|+9Snyk,35J,!^G}k(|7GQ-9qvmJh~E]}Z}St_1?b]8t._/5">ʆFE\3%rYmp>wl AUJ /'d>lX2[kzP^xh7F'8.-mU&C멠gI4:df~TNX0 MYQ+WY"T?˾ƗXFxHgaE$, ;ųҸ|}$)u8~Ο>I߳~"?)?9Y__S%>;>g mؖ>W|߱\<Vꖩߗ&G#7B3oYvO3 w ,ՇIkDkT }D<ˑ76+ eg ^XE_SZab6*ʲ>RdfTnߗIE7˰ZJc!}: +"a_ѷ.ʂZBĩњ[Zfzb47QZa#ΖyŏO"}R\ҽS.P! y _uwlr2Rz;S)btt,r),?ʏ/yYaÌ*lXeya6.| 8֭+5t1+r3`|$2ݒK<{CלW!腓=8PYrd\nlߔQvҿux7'ddO!ZvםK.?pfgs=-9Y^T*fqC['Go f1?C#2OTT$*?ꛔù˦aeljOEۙ8X KŽu*T$Ր[C|zvu:jqi(dcj<}Wzl:[w SpJԱKzdsfqqBKrwEv!g(q(4"I t.32K64W!E seZ^*=uSSV櫏.NpȜ)f$u[$ tth{dwY6G|loRzkF=Hel=/ f(vdHϜ|JEC)*B|~/I*b=Jc_HXv# <\ѩj~PB|;@H]Vڼ Ri;F6~-gA1ᐻ^|q3)朸"!$ :FeX] )ymńf .{?Vdz]pvFU-1f]S5JjO*=̼ S\O ,Մ6?C7Z4ZK4xT,?2Ii"IRa2D8 +"a_ѷ.ZeEPș1U.t2Rs-g,n.߬IѳC5D3{T]mi2lhTdIItX?$ ۤ,̆kl#]Lhv W\ؒAU6^ ;7u?WCASN*$ˏ/QngLc q,v I$r~n3Q1."QMI8ٷ3Ѱ"ۮ^Z-HxɃ|z >;{G`! ^Kyŝ j! ͸&RZJ_ol[OfC\5V59VeKn^T2CqRaE&]~|.Z6{GkUg"W/A KC4O@*d(˙HX KŽEIY d>=ާ}Snm؁qT 8]|!ljYZTӖ4H#+mF` f(7ͭOӼT$*?)}(cV&HEЙpX KŽmGemUuwV]/WW~_,B^줖[G Yn_myVsmSp ]tvkf^7cGpT>ţR;l'"sz߄8S5I߸+~_"L'ln\@~2]V'+43sbeڤM‰Z EU՜v{m,fnxb6*\n /&HP~lR!8JtŠHXvlb[:Ez1 f=R+T0+֥rJ8_L] &7gڃhVқ|".3n =p1yעeD36^ 'Ƃ8+d. "T^j3ЛˏND=5sg(p5on p Y:9h^-VDҿ#ZAj '+ath"aE$, ;D]<8@ +"a_] lX K"ŠHXv@VDҿ "Ei/.H+at@ZaE$%+" +" +" +" +" +" +" +" +"<.\7'O%F1*RIENDB`code-001c16ac87ec/doc/implementation.txt0000644000000000000000000000403215046233326016257 0ustar 00000000000000.. meta:: :description: Additional implementation notes for the Roundup Issue Tracker. Supplement for docstrings in the Roundup package. ==================== Implementation notes ==================== [see also the roundup package docstring] There have been some modifications to the spec. I've marked these in the source with 'XXX' comments when I remember to. In short: Class.find() - may match multiple properties, uses keyword args. Class.filter() - isn't in the spec and it's very useful to have at the Class level. CGI interface index view specifier layout part - lose the '+' from the sorting arguments (it's a reserved URL character ;). Just made no prefix mean ascending and '-' prefix descending. ItemClass - renamed to IssueClass to better match it only having one hypderdb class "issue". Allowing > 1 hyperdb class breaks the "superseder" multilink (since it can only link to one thing, and we'd want bugs to link to support and vice-versa). template - the call="link()" is handled by special-case mechanisms in my top-level CGI handler. In a nutshell, the handler looks for a method on itself called 'index%s' or 'item%s' where %s is a class. Most items pass on to the templating mechanism, but the file class _always_ does downloading. It'll probably stay this way too... template - call="link(property)" may be used to link "the current item" (from an index) - the link text is the property specified. template - added functions that I found very useful: List, History and Submit. template - items must specify the message lists, history, etc. Having them by default was sometimes not wanted. template - index view determines its default columns from the template's ``tal:condition="request/show/"`` directives. template - menu() and field() look awfully similar now .... ;) roundup_admin.py - the command-line tool has a lot more commands at its disposal ----------------- Back to `Table of Contents`_ .. _`Table of Contents`: ../docs.html code-001c16ac87ec/doc/index.txt0000644000000000000000000000216015046233326014341 0ustar 00000000000000.. meta:: :description: Table of contents for documentation on the Roundup Issue Tracker. ======================================================= Roundup: an Issue-Tracking System for Knowledge Workers ======================================================= For how to contact the community see https://www.roundup-tracker.org . Contents ======== .. toctree:: :maxdepth: 2 :includehidden: features installation upgrading security FAQ user_guide customising rest xmlrpc reference glossary admin_guide man pages license acknowledgements upgrading-history tracker_templates Design Overview Design (original) Software Carpentry and Papers developers Notes about the MySQL Database backend Notes about the PostgreSQL Database backend Richard Jones implementation notes security-history .. toctree:: :hidden: pydoc See: https://wiki.roundup-tracker.org/ReleaseErrata for fixes to documentation. Indices ======= * :ref:`genindex` code-001c16ac87ec/doc/installation.txt0000644000000000000000000026401115046233326015740 0ustar 00000000000000.. meta:: :description: Everything about installing the Roundup issue tracker web and mail interfaces and configuring a tracker. How to download and demonstrate Roundup using using command line or Docker. Optional software that adds functionality to Roundup. .. index:: Installation ================== Installing Roundup ================== .. contents:: :depth: 3 :local: Overview ======== A Roundup installation is made up of several pieces. Roundup scripts These include the Roundup HTTP server, email gateway, administration command-line interface, demo installer etc. These are usually placed in a directory that is on your path. Roundup core code Is installed into your Python's lib directory. We recommend using a virtual environment for your Roundup installation. Roundup trackers Trackers consist of issues (be they bug reports or otherwise). Each tracker is put in its own directory (called a tracker home) and has its own: * configuration files, * HTML (web) files, * database, * logic files (detectors, schema, ...) Roundup trackers are initialised with a "template" which defines the fields usable/assignable on a per-issue basis. Descriptions of the provided templates are given in `choosing your template`_. Usually you start with a template then modify the tracker to implement your desired workflow. One Roundup instalation can support multiple trackers with different look/feel and workflow. For The Really Impatient ======================== If you just want to give Roundup a whirl **Right Now**, follow these directions to run ``demo.py``. Demo mode starts the `classic tracker`_ without installing Roundup on your system. If you have Docker installed, you can run `demo mode using docker`_ instead. This is also a way to spin up a development environment or even deploy a tracker for a handful of users. You can choose different templates and backend databases using demo mode. For example replacing ``demo.py`` (or ``demo`` if you are using docker) with:: demo jinja2 anydbm will start the tracker using the jinja2 template with the dbm database backend (rather then the default sqlite). See `Choosing Your Template`_ for a description of available templates. (In the directions below, replace ``-2.2.0`` with the version number of the file you downloaded. On systems that don't have a ``python3`` program you can run ``python demo.py`` instead.) .. _install the source: 1. ``python3 -m pip download roundup`` * (If you are really impatient, you probably don't want to `verify the downloaded file `_.) 2. ``tar -xzvf roundup-2.2.0.tar.gz`` * if you don't have a tar command, ``python3 -c "import tarfile, sys; tarfile.open(sys.argv[1]).extractall();" roundup-2.2.0.tar.gz`` can be used. 3. ``cd roundup-2.2.0`` 4. ``python3 demo.py`` This will set up a classic demo tracker on your machine without installing Roundup. [1]_ When it's done, it'll print out a URL for your web browser at so you can explore a Roundup tracker. Three users are set up: 1. anonymous - the "default" user with permission to do very little 2. demo (password "demo") - a normal user who may create issues 3. admin (password "admin") - an administrative user who has complete access to the tracker Note the demo tracker removes the detector (nosyreaction.py) that sends email notifications. If you later convert your demo tracker to production you will need to replace the detector to send notification emails. Once you install Roundup, you can use the ``roundup-demo`` command to install new demo trackers. .. [1] Demo tracker is set up to be accessed by localhost browser. If you run demo on a server host, please stop the demo (using Control-C) after it has shown the startup notice, open file ``demo/config.ini`` with your editor, change host name in the ``web`` option in section ``[tracker]``, save the file, then re-run the demo.py program. .. _demo mode using docker: Running in Demo Mode with Docker -------------------------------- You can either: * use a published container from hub.docker.com with ``rounduptracker/roundup:latest`` and start demo mode with:: docker run --rm -p 127.0.0.1:8917:8080 --name roundup_demo -v \ $PWD:/usr/src/app/tracker rounduptracker/roundup:latest demo or * Use steps 1-3 to `install the source`_ then * build a local docker container using:: docker build -t roundup-app -f scripts/Docker/Dockerfile . (see `Docker Support`_ and `Building a Docker Container`_ for more details) and start demo mode with:: docker run --rm -p 127.0.0.1:8917:8080 --name roundup_demo -v \ $PWD:/usr/src/app/tracker roundup-app:latest demo This will create a ``demo`` subdirectory which is your tracker's home. It will also print the URL for exploring your new tracker. .. caution:: Removing ``127.0.0.1:`` will make the tracker accessible from any host with network access to your system. However the URL's created by Roundup will still reference ``localhost`` unless you modify the ``web`` url in the ``tracker`` section of ``config.ini`` and restart the container [1]_. In the docker run command we used port 8917 for Roundup. When starting Roundup, Docker may report a long error ending with: `bind: address already in use.` This means that port 8917 is in use. When running inside a Docker container, demo mode is unable to automatically find a free port. You have to provide an unused port to ``-p``. To fix this, you can change the change the port mapping provided with ``-p``. If you do this you **must** set the docker PORT_8080 environment variable on the command line to match. (If Docker ever fixes https://github.com/moby/moby/issues/3778 we won't need to worry about this.) For example:: docker run --rm -e PORT_8080=9090 -p 127.0.0.1:9090:8080 -v \ --name roundup_demo $PWD:/usr/src/app/tracker \ rounduptracker/roundup:latest demo will run Roundup on port 9090 and Roundup will generate the correct URL. To shut down the tracker and get your shell back, use control-c. You can remove the tracker using ``rm -f`` on the ``demo`` directory. Prerequisites ============= Roundup requires Python 3.7 or newer with a functioning anydbm or sqlite module. The version installed by most vendors should work if it meets the version requirements. If necessary, you can download the latest version from https://www.python.org/. It is highly recommended that users install the latest patch version of Python as these contain many fixes to serious bugs. Some variants of Linux will need an additional '``python-dev``' package installed for Roundup installation to work. Debian and derivatives, are known to require this. Optional Components =================== You may optionally install and use: An RDBMS Sqlite, MySQL and Postgresql are all supported by Roundup and will be used if available. One of these is recommended if you are anticipating a large user base (see `choosing your backend`_ below). Sqlite should always be available. Timezone Definitions Full timezone support requires pytz_ module (version 2005i or later) which brings the `Olson tz database`_ into Python. If pytz_ is not installed, timezones may be specified as numeric hour offsets only. This is optional but strongly suggested. Xapian full-text indexer The Xapian_ full-text indexer is also supported and will be used by default if it is available. This is strongly recommended if you are anticipating a large number of issues (> 5000). You may install Xapian at any time, even after a tracker has been installed and used. You will need to run the "roundup-admin reindex" command if the tracker has existing data. Roundup requires Xapian 1.0.0 or newer. Note that capitalization is not preserved by the Xapian search. This is required to make the porter stemmer work so that searching for ``silent`` also returns documents with the word ``silently``. Note that the current stemming implementation is designed for English. Whoosh full-text indexer The Whoosh_ full-text indexer is also supported and will be used by default if it is available (and Xapian is not installed). This is recommended if you are anticipating a large number of issues (> 5000). It is also the only search backend that implements fuzzy search. It matches any word that has a 1 character difference from the search term. You may install Whoosh at any time, even after a tracker has been installed and used. You will need to run the "roundup-admin reindex" command if the tracker has existing data. Roundup was tested with Whoosh 2.5.7, but earlier versions in the 2.0 series may work. Whoosh is a pure Python indexer so it is slower than Xapian, but should be useful for moderately sized trackers. It uses the StandardAnalyzer which is suited for Western languages. pyopenssl If pyopenssl_ is installed the roundup-server can be configured to serve trackers over SSL. If you are going to serve roundup via proxy through a server with SSL support (e.g. apache) then this is unnecessary. gpg If gpg_ is installed you can configure the mail gateway to perform verification or decryption of incoming OpenPGP MIME messages. When configured, you can require email to be cryptographically signed before roundup will allow it to make modifications to issues. (Note with python 3.13 or newer on some platforms, you may need to install version 2.0 of gpg from test.pypi.org. See the `gpg install directions in the upgrading document`_. jinja2 To use the jinja2 template (may still be experimental, check out its TEMPLATE-INFO.txt file) you need to have the jinja2_ template engine installed. defusedxml If you are going to enable and use the XMLRPC endpoint, you should install the defusedxml_ module. It will still work with the default xmlrpc standard library, but it will log a warning when used. .. _install/docutils: docutils To use ReStructuredText rendering you need to have the `docutils`_ package installed. .. _install/markdown: markdown, markdown2 or mistune To use markdown rendering (as supplied by the jinja2 template) you need to have the markdown_, markdown2_ (2.4.9 known to be broken, 2.3.3, 2.4.10+ known to work), or mistune_ (v0.8.4 tested; python3 only) package installed. zstd, brotli To have roundup compress the returned data using one of these algorithms, you can install one or more of zstd_ or brotli_. Roundup's responses can always be compressed with gzip from the Python standard library. Also nginx and various wsgi server can compress the response from Roundup as they transmit/proxy it to the client. redis Storing ephemeral data: session keys, CSRF tokens etc. can be performance bottleneck. You can choose to deploy a Redis_ database using the redis-py_ pypi package. See the section on `Using Redis for Session Databases`_ in the `administration guide`_ for details. pyjwt To use JWT (JSON web tokens) for login (experimental), install `pyjwt`_ (v1.7.1, v2.0.1 tested). If you don't have it installed, JWT's are not supported. polib Roundup includes translations in various languages. To extract strings designated for translation from your tracker's HTML templates, you can utilize `roundup-gettext`. However, if you wish to extract translatable strings from the Python code in tracker's detectors or extensions directories using roundup-gettext, you must install polib_. See the `developer's guide`_ for details on translating your tracker. pywin32 - Windows Service You can run Roundup as a Windows service if pywin32_ is installed. Otherwise it must be started manually. pyreadline3 When running roundup-admin on windows, installing pyreadline3_ will allow history and editing on the command line. requests If you are using OAuth authentication with the roundup-mailgw mail gateway you must install the requests_ library. .. _Using Redis for Session Databases: admin_guide.html#using-redis-for-session-databases .. _gpg install directions in the upgrading document: upgrading.html#directions-for-installing-gpg Installing Roundup ================== To get a production installation running will take 15-30 minutes. If you want to spend less than 5 minutes to test Roundup without installing it, see `For The Really Impatient`_. .. note:: Some systems, such as Gentoo and NetBSD, already have Roundup installed. Try running the command "roundup-admin -v". If it runs and reports the current version, you may skip the `Standard installation`_ below and go straight to `configuring your first tracker`_. However it may be an old version. If so you should probably install it in a virtual environment from the Roundup web site or pypi. If Roundup is not installed on your system, or needs to be updated, there are multiple ways to install Roundup. * `Standard installation`_ using pip in a Virtual Environment is the recommended standard. * `Installing from downloaded source`_ allows more control over how things are installed (including overwriting a vendor install). But it also increases complexity as well. * Use a prebuilt docker container from ``rounduptracker/roundup:latest`` and follow the steps in `Running Your Container`_. * Install in a docker container by downloading the source and following the steps in `Docker Support`_. There are several steps to get Roundup serving a tracker: 1. Install using one of the methods listed above. 2. Configure your tracker following `configuring your first tracker`_ for all install methods. 3. Optionally `configure a web interface`_. 4. Optionally `configure an email interface`_. 5. Follow `UNIX environment steps`_ to restrict local access to Roundup if you're installing on a shared UNIX system. For information about what Roundup installs, see the `What does Roundup install`_ section in the `administration guide`_. Standard Installation ---------------------- Installation of Roundup using Python3 in a virtual environment is recommended. Use:: python3 -m venv /path/to/environment/roundup Activate the Python environment (assuming a Bourne like shell) using:: . /path/to/environment/roundup/bin/activate To install the released Roundup core code into your Python tree and Roundup scripts into ``/path/to/environment/roundup/usr/bin`` run:: python3 -m pip install roundup If everything went well, you should now be able to run:: roundup-admin help and see the help text. If you want to run Roundup commands in the future without activating the virtual environment, just call the commands using the full path. For example:: /path/to/environment/roundup/usr/bin/roundup-admin You can use the command ``deactivate`` to return to the normal Python environment. However, for now continue with `configuring your first tracker`_. .. _downloaded and unpacked the source: Installing from downloaded source --------------------------------- In general you should be installing from a released Roundup version into a virtual environment. .. _current development version: ../code.html If you are installing a `current development version`_ or are a developer or are an expert you can use the manual installation method from a source install. From the unpacked source distribution, run:: sudo python3 setup.py install which will put the Roundup core code into your systems Python tree and the command scripts into ``/usr/bin`` If you would like to place the Roundup scripts in a directory other than ``/usr/bin``, then specify the preferred location with ``--install-scripts``. For example, to install them in ``/opt/roundup/bin``:: sudo python setup.py install --install-scripts=/opt/roundup/bin You can also use the ``--prefix`` option to install roundup into a completely different base directory. If you choose to do this, you will have to change Python's search path (sys.path) yourself. Configuring your first tracker ============================== Make sure the ``roundup-admin`` script location is on your ``PATH`` evironment variable. This is done automatically when you activate a virtual environment. You can also specify the full path to the command in the following steps. 1. To create a Roundup tracker (necessary to do before you can use the software in any real fashion), you need to set up a "tracker home": a. (Optional) If you intend to keep your roundup trackers under one top level directory which does not exist yet, you should create that directory now. Example:: mkdir /opt/roundup/trackers .. index:: roundup-admin; install subcommand b. Install a new tracker with the command ``roundup-admin install``. You will be asked a series of questions. Descriptions of the provided templates can be found in `choosing your template`_ below. Descriptions of the available backends can be found in `choosing your backend`_ below. The questions will be something like (you may have more templates or backends available):: Enter tracker home: /opt/roundup/trackers/support Templates: minimal, jinja2, classic, responsive, devel Select template [classic]: classic Back ends: anydbm, sqlite Select backend [anydbm]: anydbm Note: "Back ends" selection list depends on availability of third-party database modules. Standard python distribution includes anydbm and sqlite module only. The "support" part of the tracker home can be anything you want - it is the directory where the tracker information will be stored. You will now be directed to edit the tracker configuration and initial schema. At a minimum, you must set "tracker :: web" (that's the "web" option in the "tracker" section), "mail :: host", and "mail :: domain". You should also set "main :: admin_email" to your local admin address to get email on unusual occurances. If you get stuck, and get configuration file errors, then see the `tracker configuration`_ section of the `reference documentation`_. If you just want to get set up to test things quickly (and follow the instructions in step 3 below), you can even just set the "tracker :: web" variable to:: web = http://localhost:8080/support/ The URL *must* end in a '/', or your web interface *will not work*. See the `Roundup reference`_ for details on configuration and schema changes. You may change any of the configuration after you've initialised the tracker - it's just better to have valid values for this stuff now. .. index:: roundup-admin; initialise subcommand c. Initialise the tracker database with ``roundup-admin initialise``. You will need to supply an admin password at this step. You will be prompted:: Admin Password: Confirm: Note: running this command will *destroy any existing data in the database*. In the case of MySQL and PostgreSQL, any existing database (or optionally database schema for PostgreSQL) will be dropped and re-created. Once this is done, the tracker has been created. See the note in the `administration guide`_ on how to :ref:`initialise a tracker without being prompted for the password ` or exposing the password on the command line. 2. At this point, your tracker is set up, but doesn't have a nice user interface. To set that up, we need to `configure a web interface`_ and optionally `configure an email interface`_. If you want to try your new tracker out, assuming the ``web`` setting in the ``[tracker]`` [4]_ section of config.ini is set to ``'http://localhost:8080/support/'``, run:: roundup-server support=/opt/roundup/trackers/support then direct your web browser at: http://localhost:8080/support/ and you should see the tracker interface. To run your tracker on some interface other than 127.0.0.1 and port 8080 (make sure you change the "tracker :: web" option to match) use:: roundup-server -p 1080 -n 0.0.0.0 support=/opt/roundup/trackers/support to run the server at port 1080 and bind to all ip addresses on your system. Then direct your web browser to ``http://your_host_name:1080/support/``. .. [4] The rest of the documentation uses the abbreviated form "tracker :: web" for specifying a section and setting. Choosing Your Template ---------------------- Roundup ships with 5 templates. A description of each follows. When Roundup is installed, you can also get a description of available templates using ``roundup-admin templates``. You can use this to view additional templates that you create or download. .. _classic tracker: Classic Template ~~~~~~~~~~~~~~~~ The classic template is the one defined in the `Roundup Specification`_. It holds issues which have priorities and statuses. Each issue may also have a set of messages which are disseminated to the issue's list of nosy users. Minimal Template ~~~~~~~~~~~~~~~~ The minimal template has the minimum setup required for a tracker installation. That is, it has the configuration files, defines a user database and the basic HTML interface to that. It's a completely clean slate for you to create your tracker on. Other Templates ~~~~~~~~~~~~~~~ There are three other templates distributed with Roundup: devel This is a generic issue tracker that may be used to track bugs, feature requests, project issues or any number of other types of issues. Most users of Roundup will find that this template suits them, with perhaps a few customisations. responsive This issue tracker uses the same schema as devel. The difference between devel and responsive templates is the use of Twitter bootstrap (https://github.com/twbs/bootstrap) in templates and HTML5 markup. Make sure the "static_files" setting in your config.ini of your instance is set to the directory where the static files live (the subdirectory "static" in the default of the template). jinja2 This is a generic issue tracker based on classic schema. It uses Jinja2 for templating and Twitter bootstrap for responsive markup. You will need jinja and gettext for this to work. See the wiki page https://wiki.roundup-tracker.org/Jinja2 for updates between releases. Also other people have listed their trackers for different needs at: https://wiki.roundup-tracker.org/TrackerTemplates. .. index:: database; choosing your backend Choosing Your Backend --------------------- The actual storage of Roundup tracker information is handled by backends. Roundup supports basic full text search (FTS) for all backends. Some backends support a faster native FTS. Also Roundup supports using whoosh or xapian for FTS. There are several backends to choose from, each with benefits and limitations: ========== =========== ===== ============================== Name Speed Users Support ========== =========== ===== ============================== anydbm Slowest Few Always available sqlite Fastest Few Always available postgresql Fast Many Needs install/admin (psycopg2_) mysql Fast Many Needs install/admin (MySQLdb_) ========== =========== ===== ============================== **anydbm** This was one of the original database backends. It is a simple key/value store and is a prototype implementation for NoSQL backends. It also used to be the only backend that was guaranteed to be present. These days using SQLite is preferred unless you have some reason for preferring a key/value backend (e.g. you are interested in adding support for MongoDB or other NoSQL persistence layer). **sqlite** This uses the embedded database engine SQLite and the PySQLite_ driver to provide a very fast backend. This is not suitable for trackers which will have many simultaneous users, but requires much less installation and maintenance effort than more scalable postgresql and mysql backends. SQLite is supported via PySQLite version 2.1.0 and sqlite3 (the last being bundled with Python 2.5+) Installed SQLite should be the latest version available (3.9.0 or newer). .. _fts5-testing: Installation of Roundup 2.2.0 or newer requires that the installed SQLite supports FTS5. This is required even if you are not going to use FTS5 for full text searching. FTS5 was included in SQLite release 3.9.0 in October 2015. However some vendors choose not to include it. RedHat 7's native sqlite3 is known to not work. You can check your SQLite by using the command line:: echo 'pragma compile_options' | sqlite3 | grep FTS5 it should output ``ENABLE_FTS5`` if FTS5 is supported. You can check using the same version of Python you use for running Roundup with:: import sqlite3 con = sqlite3.connect(':memory:') cur = con.cursor() cur.execute('pragma compile_options;') available_pragmas = cur.fetchall() con.close() The output should include ``('ENABLE_FTS5',)`` in the output. Roundup supports using `SQLite's full text search capability `_. This can improve searching if you are not installing another indexer like xapian or whoosh. It works best with English text. **postgresql** Backend for popular RDBMS PostgreSQL. You must read `doc/postgresql.txt`_ for additional installation steps and requirements. You must also configure the ``rdbms`` section of your tracker's ``config.ini``. It is recommended that you use at least version 2.8 of psycopg2. Roundup supports using `postgresql's full text search capability `_. This can improve searching if you are not installing another indexer like xapian or whoosh. It can be tuned to work with different languages. **mysql** Backend for popular RDBMS MySQL. You must read `doc/mysql.txt`_ for additional installation steps and requirements. You must also configure the ``rdbms`` section of your tracker's ``config.ini`` You may defer your decision by setting your tracker up with the anydbm backend (which is guaranteed to be available) and switching to one of the other backends at any time using the instructions in the `administration guide`_. Regardless of which backend you choose, Roundup will attempt to initialise a new database for you when you run the "``roundup-admin initialise``" command. In the case of MySQL and PostgreSQL you will need to have the appropriate privileges to create databases. Configure a Web Interface ========================= There are multiple ways to deploy the web interface. If your tracker will be heavily used and accessible from the internet, we suggest using Apache or Nginx in WSGI mode or as a reverse proxy to the stand alone web server or WSGI server like Gunicorn. A FastCGI deployment with an alternate web server is suitable for lower traffic sites. If you already run Zope, Roundup should deploy nicely in that framework. If you are internet accessible, but expect a few users, or are on a hosted web server, using cgi-bin is a reasonable deployment. Using a true HTTP server provide tools including: DOS prevention, throttling, web application firewalls etc. that are worth having in an internet facing application. If you are running on an internal intranet, you can use the stand alone server: roundup-server, but even in this environment, using a real web server to serve static files and other resources will perform better. .. contents:: :depth: 1 :local: You may need to give the web server user permission to access the tracker home - see the `UNIX environment steps`_ for information. You may also need to configure your system in some way - see `platform-specific notes`_. .. index:: pair: web interface; cgi Web Server cgi-bin ------------------ A benefit of using the cgi-bin approach is that it's the easiest way to restrict access to your tracker to only use HTTPS. Access will be slower than through the `stand-alone web server`_ though. If your Python isn't installed as "python" then you'll need to edit the ``roundup.cgi`` script to fix the first line. .. index:: windows; IIS cgi installation If you're using IIS on a Windows platform, you'll need to run this command for the cgi to work (it turns on the PATH_INFO cgi variable):: adsutil.vbs set w3svc/AllowPathInfoForScriptMappings TRUE The ``adsutil.vbs`` file can be found in either ``c:\inetpub\adminscripts`` or ``c:\winnt\system32\inetsrv\adminsamples\`` or ``c:\winnt\system32\inetsrv\adminscripts\`` depending on your installation. See: https://github.com/MicrosoftDocs/iis-docs/blob/main/iis/web-dev-reference/server-variables.md More information about IIS setup may be found at: https://learn.microsoft.com/en-us/iis/ Copy the ``share/roundup/cgi-bin/roundup-cgi`` (``frontends/roundup.cgi`` in source tree) file to your web server's ``cgi-bin`` directory. You will need to configure it to tell it where your tracker home is. You can do this either: Through an environment variable Set the variable TRACKER_HOMES to be a colon (":") separated list of name=home pairs (if you're using apache, the SetEnv directive can do this) Directly in the ``roundup.cgi`` file itself Add your instance to the TRACKER_HOMES variable as ``'name': 'home'`` The "name" part of the configuration will appear in the URL and identifies the tracker (so you may have more than one tracker per cgi-bin script). Make sure there are no spaces or other illegal characters in it (to be safe, stick to letters and numbers). The "name" forms part of the URL that appears in the tracker config "tracker :: web" variable, so make sure they match. The "home" part of the configuration is the tracker home directory. If you're using Apache, you can use an additional trick to hide the ``.cgi`` extension of the cgi script. Place the ``roundup.cgi`` script wherever you want it to be, rename it to just ``roundup``, and add a couple lines to your Apache configuration:: SetHandler cgi-script CGI-bin for Limited-Access Hosting ---------------------------------- If you are running in a shared-hosting environment or otherwise don't have permission to edit the system web server's configuration, but can create a ``.htaccess`` file then you may be able to use this approach. 1. Install flup_ 2. Create a script ``roundup_stub`` in your server's ``cgi-bin`` directory containing:: #!/usr/bin/env python # if necessary modify the Python path to include the place you # installed Roundup #import sys #sys.path.append('...') # cgitb is needed for debugging in browser only #import cgitb #cgitb.enable() # obtain the WSGI request dispatcher from roundup.cgi.wsgi_handler import RequestDispatcher tracker_home = '/path/to/tracker/home' app = RequestDispatcher(tracker_home) from flup.server.cgi import WSGIServer WSGIServer(app).run() 3. Modify or created the ``.htaccess`` file in the desired (sub-)domain directory to contain:: RewriteEngine On RewriteBase / RewriteRule ^(.*)$ /cgi-bin/roundup_stub/$1 [L] Now loading the (sub-)domain in a browser should load the tracker web interface. If you get a "500" error then enable the "cgitb" lines in the stub to get some debugging information. .. index:: pair: web interface; stand alone server Stand-alone Web Server ---------------------- This approach will give you faster response than cgi-bin. You may investigate using ProxyPass or similar configuration in apache to have your tracker accessed through the same URL as other systems. The stand alone serveris used by the Docker image. The stand-alone web server is started with the command ``roundup-server``. It has several options - display them with ``roundup-server -h``. The tracker home configuration is similar to the cgi-bin - you may either edit the script to change the TRACKER_HOMES variable or you may supply the name=home values on the command-line after all the other options. To make the server run in the background, use the "-d" option, specifying the name of a file to write the server process id (pid) to. .. index:: pair: web interface; Zope Zope Product - ZRoundup ----------------------- ZRoundup installs as a regular Zope product. Copy the ``share/roundup/frontends/ZRoundup`` (frontends/ZRoundup in the source tree) directory to your Products directory either in INSTANCE_HOME/Products or the Zope code tree lib/python/Products. When you next (re)start up Zope, you will be able to add a ZRoundup object that interfaces to your new tracker. .. index:: ! triple: web interface; apache; mod_wsgi ! single: wsgi; apache Apache HTTP Server with mod_wsgi -------------------------------- This is a work in progress thanks to Garth Jensen. See the main web site for `mod_wsgi`_ which include directions for using mod_wsgi-express which is easier if you are not used to apache configuration. Also there is the `main mod_wsgi `_ for more detailed directions. Background ~~~~~~~~~~ These notes were developed on a Microsoft Azure VM running Ubuntu 18.04 LTS. The instructions below assume: - python and roundup are already installed - roundup is running in the system python instance (e.g. no virtual environment) - the tracker ``mytracker`` is installed in the ``trackers`` folder of home directory of a user called ``admin``. Thus, the absolute path to the tracker home directory is ``/home/admin/trackers/mytracker``. - the server has a static public IP address of 198.51.100.25 Install mod-wsgi ~~~~~~~~~~~~~~~~ You can install/build it using the python package manager pip, or install using the OS package manager (apt). Pip install of mod_wsgi ''''''''''''''''''''''' This is the tested method, and offers an easier path to get started, but it does mean that you will need to keep up to date with any security or other issues. If you use the packages supplied by your OS vendor, you may get more timely updates and notifications. The mod_wsgi docs talk about two installation methods: (1) the so-called CMMI method or (2) with pip. The pip method also provides an admin script called ``mod_wsgi-express`` that can start up a standalone instance of Apache directly from the command line with an auto generated configuration. These instructions follow the pip method. 1. The `mod_wsgi`_ PyPi page lists prerequisites for various types of systems. For Ubuntu, they are apache2 and apache2-dev. To see installed apache packages, you can use ``dpkg -l | grep apache``. If apache2 or apache2-dev are not installed, they install them with: - ``sudo apt update`` - ``sudo apt install apache2 apache2-dev`` 2. If ``pip`` is not already installed, install it with ``sudo apt install python-pip`` If you are using python 3, use ``sudo apt-install python3-pip`` and change references to pip in the directions to pip3. 3. ``sudo pip install mod_wsgi``. In my case, I got warnings about the user not owning directories, but it said it completed "successfully." 4. For testing, open port 8000 for TCP on the server. For an Azure VM, this is done with Azure Portal under ``Networking`` > ``Add inbound port`` rule. 5. Test with ``mod_wsgi-express start-server``. This should serve up content on localhost port 8000. You can then direct a browser on the server itself to ``http://localhost:8000/`` or on another machine at the server's domain name or ip address followed by colon then 8000 (e.g. ``http://198.51.100.25:8000/``). If successful, you should see a Malt Whiskey image. Package manager install of mod_wsgi ''''''''''''''''''''''''''''''''''' On debian (which should work for Ubuntu), install apache2 with libapache2-mod-wsgi: - ``sudo apt update`` - ``sudo apt install apache2 libapache2-mod-wsgi`` this is the less tested method for installing mod_wsgi and may not install mod_wsgi-express, which is used below. However there is an example apache config included as part of `WSGI Variations`_ that can be used to hand craft an apache config. You should make sure that the version you install is 3.5 or newer due to security issues in older releases. Configure web interface via wsgi_handler ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1. In the tracker's home directory create a ``wsgi.py`` file with the following content (substituting ``/home/admin/trackers/mytracker`` with the absolute path for your tracker's home directory): .. code:: python from roundup.cgi.wsgi_handler import RequestDispatcher tracker_home = '/home/admin/trackers/mytracker' application = RequestDispatcher(tracker_home) To run the tracker on Port 8000 as a foreground process ''''''''''''''''''''''''''''''''''''''''''''''''''''''' 1. Change the ``tracker.web`` url in ``config.ini`` to port 8000 at the server domain name or ip address (e.g. ``http://198.51.100.25:8000/``). 2. Open port 8000 for TCP on the server if you didn't already do so. 3. ``cd`` to your tracker home directory, then run ``mod_wsgi-express start-server wsgi.py``. 4. Test by directing a browser on another machine to the url you set ``tracker.web`` to in ``config.ini``. Run tracker as background daemon '''''''''''''''''''''''''''''''' To run the tracker on Port 80 or as a background process, you'll need to configure a UNIX group with appropriate privileges as described in `UNIX environment steps`_. These steps are summarized here: 1. To add a group named "mytrackergrp" run: ``sudo groupadd mytrackergrp``. 2. Add the owner of the tracker home (admin in this example) run: ``sudo usermod -a -G mytrackergrp admin`` 3. Add user that runs Apache (the default on Ubuntu is www-data) run: ``sudo usermod -a -G mytrackergrp www-data`` 4. Add user mail service runs as (e.g. daemon) run: ``sudo usermod -a -G mytrackergrp daemon`` 5. Change group of the database in the tracker folder run: ``sudo chgrp -R mytrackergrp ~/trackers/mytracker``. 6. Make sure group can write to the database, and any new files created in the database will be owned by the group run: ``sudo chmod -R g+sw ~/trackers/mytracker/db`` To run mod_wsgi on PORT 80 '''''''''''''''''''''''''' 1. Change the ``tracker.web`` url in ``config.ini`` to the server url with no port designator. E.g. ``http://198.51.100.25``. 2. Open port 80 on the server for TCP traffic if it isn't open already. 3. Stop the system instance of Apache to make sure it isn't holding on to port 80 run: ``sudo service apache2 stop``. To run as a foreground process ++++++++++++++++++++++++++++++ 1. From the tracker home directory, run ``sudo mod_wsgi-express start-server wsgi.py --port 80 --user admin --group mytrackergrp`` To run as a background process ++++++++++++++++++++++++++++++ 1. From the tracker home directory, bash ``sudo mod_wsgi-express setup-server wsgi.py --port=80 --user admin --group mytrackergrp --server-root=/etc/mod_wsgi-express-80`` 2. Then, run ``sudo /etc/mod_wsgi-express-80/apachectl start`` 3. To stop, run ``sudo /etc/mod_wsgi-express-80/apachectl stop`` .. index:: triple: web interface; apache; mod_python (depricated) Apache HTTP Server with mod_python ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ As of roundup 2.0, mod_python support is deprecated. The apache.py file is still available, but may be limited to working for Python 2 only. Using mod_wsgi with Apache is the recommended way to deploy roundup under apache. `Mod_python`_ is an `Apache`_ module that embeds the Python interpreter within the server. Running Roundup this way is much faster than all above options and, like `web server cgi-bin`_, allows you to use HTTPS protocol. The drawback is that this setup is more complicated. The following instructions were tested on apache 2.0 with mod_python 3.1. If you are using older versions, your mileage may vary. Mod_python uses OS threads. If your apache was built without threads (quite commonly), you must load the threading library to run mod_python. This is done by setting ``LD_PRELOAD`` to your threading library path in apache ``envvars`` file. Example for gentoo linux (``envvars`` file is located in ``/usr/lib/apache2/build/``):: LD_PRELOAD=/lib/libpthread.so.0 export LD_PRELOAD Example for FreeBSD (``envvars`` is in ``/usr/local/sbin/``):: LD_PRELOAD=/usr/lib/libc_r.so export LD_PRELOAD Next, you have to add Roundup trackers configuration to apache config. Roundup apache interface uses the following options specified with ``PythonOption`` directives: TrackerHome: defines the tracker home directory - the directory that was specified when you did ``roundup-admin init``. This option is required. TrackerLanguage: defines web user interface language. mod_python applications do not receive OS environment variables in the same way as command-line programs, so the language cannot be selected by setting commonly used variables like ``LANG`` or ``LC_ALL``. ``TrackerLanguage`` value has the same syntax as values of these environment variables. This option may be omitted. TrackerDebug: run the tracker in debug mode. Setting this option to ``yes`` or ``true`` has the same effect as running ``roundup-server -t debug``: the database schema and used html templates are rebuilt for each HTTP request. Values ``no`` or ``false`` mean that all html templates for the tracker are compiled and the database schema is checked once at startup. This is the default behaviour. TrackerTiming: has nearly the same effect as environment variable ``CGI_SHOW_TIMING`` for standalone roundup server. The difference is that setting this option to ``no`` or ``false`` disables timings display. Value ``comment`` writes request handling times in html comment, and any other non-empty value makes timing report visible. By default, timing display is disabled. In the following example we have two trackers set up in ``/var/db/roundup/support`` and ``/var/db/roundup/devel`` and accessed as ``https://my.host/roundup/support/`` and ``https://my.host/roundup/devel/`` respectively (provided Apache has been set up for SSL of course). Having them share same parent directory allows us to reduce the number of configuration directives. Support tracker has russian user interface. The other tracker (devel) has english user interface (default). Static files from ``html`` directory are served by apache itself - this is quicker and generally more robust than doing that from python. Everything else is aliased to dummy (non-existing) ``py`` file, which is handled by mod_python and our roundup module. Example mod_python configuration:: ################################################# # Roundup Issue tracker ################################################# # enable Python optimizations (like 'python -O') PythonOptimize On # let apache handle static files from 'html' directories AliasMatch /roundup/(.+)/@@file/(.*) /var/db/roundup/$1/html/$2 # everything else is handled by roundup web UI AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) /var/db/roundup/$1/dummy.py/$2 # roundup requires a slash after tracker name - add it if missing RedirectMatch permanent ^/roundup/([^/]+)$ /roundup/$1/ # common settings for all roundup trackers Order allow,deny Allow from all AllowOverride None Options None AddHandler python-program .py PythonHandler roundup.cgi.apache # uncomment the following line to see tracebacks in the browser # (note that *some* tracebacks will be displayed anyway) #PythonDebug On # roundup tracker homes PythonOption TrackerHome /var/db/roundup/support PythonOption TrackerLanguage ru PythonOption TrackerHome /var/db/roundup/devel Notice that the ``/var/db/roundup`` path shown above refers to the directory in which the tracker homes are stored. The actual value will thus depend on your system. .. index:: windows; apache config On Windows the corresponding lines will look similar to these:: AliasMatch /roundup/(.+)/@@file/(.*) C:/DATA/roundup/$1/html/$2 AliasMatch /roundup/([^/]+)/(?!@@file/)(.*) C:/DATA/roundup/$1/dummy.py/$2 In this example the directory hosting all of the tracker homes is ``C:\DATA\roundup``. (Notice that you must use forward slashes in paths inside the httpd.conf file!) The URL for accessing these trackers then become: ``http:///roundup/support/`` and ``http:///roundup/devel/`` Note that in order to use https connections you must set up Apache for secure serving with SSL. Nginx HTTP Server ----------------- This configuration uses Gunicorn to run Roundup behind an Nginx proxy. The proxy also compresses the data using gzip. The url for the tracker in config.ini should be ``https://tracker.example.org``. .. code:: user nginx; worker_processes auto; worker_rlimit_nofile 10000; error_log /var/log/nginx/global-error.log; pid /var/run/nginx.pid; events { worker_connections 1024; } upstream tracker-tracker { # Gunicorn uses this socket for communication server unix:/var/run/roundup/tracker.sock fail_timeout=0; } http { include /etc/nginx/mime.types; default_type application/octet-stream; log_format main '$remote_addr - $remote_user [$time_local] "$request" ' '$status $body_bytes_sent "$http_referer" ' '"$http_user_agent" "$http_x_forwarded_for"'; access_log /var/log/nginx/global-access.log main; sendfile on; tcp_nopush on; tcp_nodelay on; server_tokens off; gzip_http_version 1.1; gzip_proxied any; gzip_min_length 500; # default comp_level is 1 gzip_comp_level 6; gzip_disable msie6 gzip_types text/plain text/css text/xml application/xml text/javascript application/javascript text/json application/json; # upstream proxies need to match Accept-Encoding as # part of their cache check gzip_vary on server { listen 80; server_name tracker.example.org; location /.well-known/acme-challenge/ { alias /etc/lego/.well-known/acme-challenge/; try_files $uri =404; } location / { return 301 https://$http_host$request_uri; } } server { listen 443 ssl; server_name tracker.example.org; include mime.types; # By default use the snakeoil certificate... # change this if you are using a real SSL cert ssl_certificate /etc/ssl/certs/ssl-cert-snakeoil.pem; ssl_certificate_key /etc/ssl/private/ssl-cert-snakeoil.key; # These are useful for @@files where roundup is bypassed. # but can be set by roundup as well. See: # https://wiki.roundup-tracker.org/AddingContentSecurityPolicy # which also sets other security headers. add_header Strict-Transport-Security "max-age=63072000; includeSubdomains; preload"; add_header X-Frame-Options "sameorigin"; add_header X-Xss-Protection "1; mode=block"; add_header X-Content-Type-Options "nosniff"; add_header X-Permitted-Cross-Domain-Policies "none"; error_log /var/log/nginx/roundup-tracker.error.log; access_log /var/log/nginx/roundup-tracker.access.log root /home/roundup/trackers/tracker/; # have nginx return files from @@file directly rather than # going though roundup location /@@file/ { rewrite ^/@@file/(.*) /html/$1 break; # note that you can not use cache control (see customising doc) # in roundup to set the expires headers since we are # bypassing roundup. Consider using a map or different # location stanzas to vary the expiration times. expires 1h; } location / { # must define tracker-tracker in upstream stanza proxy_pass http://tracker-tracker/; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; } } } FastCGI (Cherokee, Hiawatha, lighttpd) -------------------------------------- The Hiawatha and lighttpd web servers can run Roundup using FastCGI. Cherokee can run FastCGI but it also supports wsgi directly using a wsgi server like uWSGI, Gnuicorn etc. To run Roundup using FastCGI, the flup_ package can be used under Python 2 and Python 3. We don't have a detailed config for this, but the basic idea `can be found in the wayback machine archive`_. If you have deployed Roundup using FastCGI and flup we welcome example configuration files and instructions. .. _can be found in the wayback machine archive: https://web.archive.org/web/20241010170738/https://flask.palletsprojects.com/en/2.0.x/deploying/fastcgi/ .. _flup: https://pypi.org/project/flup/ WSGI Variations --------------- .. index:: triple: web interface; apache; mod_wsgi single: wsgi; apache Apache Alternate ~~~~~~~~~~~~~~~~ This method from Thomas Arendsen Hein goes into a bit more detail and is designed to allow you to run multiple roundup trackers each under their own user. The tracker instances are read-only to the tracker user and located under /srv/roundup/. The (writable) data files are stored in the home directory of the user running the tracker. To install roundup, download and unpack a distribution tarball and run the following as user "roundup":: python setup.py build_doc python setup.py sdist --manifest-only python setup.py install --home="/home/roundup/install" --force Create a user roundup-foo, group roundup-foo to run the tracker. Add the following apache config to /etc/apache2/sites-available/roundup-foo (under debian/Ubunutu, modify as needed): .. code:: ApacheConf ServerAdmin webmaster@example.com ErrorLog /var/log/apache2/error.log LogLevel notice DocumentRoot /var/www/ CustomLog /var/log/apache2/access.log vhost_combined # allow access to roundup docs Alias /doc/ /home/roundup/install/share/doc/roundup/html/ # make apache serve static assets like css rather than # having roundup serve the files Alias /foo/@@file/ /srv/roundup/foo/html/ # make /foo into /foo/ RedirectMatch permanent ^/(foo)$ /$1/ # start a wsgi daemon process running as user roundup-foo # in group roundup-foo. This also changes directory to # ~roundup-foo before it starts roundup.wsgi. WSGIDaemonProcess roundup-foo display-name=roundup-foo user=roundup-foo group=roundup-foo threads=25 # make tracker available at /foo and tie it into the # wsgi script below. WSGIScriptAlias /foo /srv/roundup/foo/roundup.wsgi WSGIProcessGroup roundup-foo The directory ~roundup-foo should have: * a ``db`` subdirectory where messages and files will be stored * a symbolic link called ``instance`` to /srv/roundup/foo which has been initialised using ``roundup-admin``. The `Apache HTTP Server with mod_wsgi`_ section above has a simple WSGI handler. This is an enhanced version to be put into ``/srv/roundup/foo/roundup.wsgi``. .. code:: python import sys, os sys.stdout = sys.stderr enabled = True if enabled: # Add the directory with the roundup installation # subdirectory to the python path. sys.path.insert(0, '/home/roundup/install/lib/python') # obtain the WSGI request dispatcher from roundup.cgi.wsgi_handler import RequestDispatcher tracker_home = os.path.join(os.getcwd(), 'instance') application = RequestDispatcher(tracker_home) else: def application(environ, start_response): status = '503 Service Unavailable' output = 'service is down for maintenance' response_headers = [('Content-type', 'text/plain'), ('Content-Length', str(len(output)))] start_response(status, response_headers) return [output] This handler allows you to temporarily disable the tracker by setting "enabled = False", apache will automatically detect the changed roundup.wsgi file and reload it. One last change is needed. In the tracker's config.ini change the db parameter in the [main] section to be /home/roundup-foo/db. This will put the files and messages in the db directory for the user. .. index:: pair: web interface; Gunicorn single: wsgi; Gunicorn Gunicorn Installation ~~~~~~~~~~~~~~~~~~~~~ To run with Gunicorn use ``pip install gunicorn``. This configuration uses a front end web server like nginx, hiawatha, or apache configured as a reverse proxy. See your web server's documentation on how to set it up as a reverse proxy. The file wsgi.py (obtained from ``frontends/wsgi.py``) should be in the current directory with the contents:: # if roundup is not installed on the default PYTHONPATH # set it here with: import sys sys.path.append('/path/to/roundup/install/directory') # obtain the WSGI request dispatcher from roundup.cgi.wsgi_handler import RequestDispatcher tracker_home = '/path/to/tracker/install/directory' app = RequestDispatcher(tracker_home) Assuming the proxy forwards /tracker, run Gunicorn as:: SCRIPT_NAME=/tracker gunicorn --bind 127.0.0.1:8917 --timeout=10 wsgi:app this runs roundup at port 8917 on the loopback interface. You should configure the reverse proxy to talk to 127.0.0.1 at port 8917. If you want you can use a unix domain socket instead. Example: ``--bind unix:///var/run/roundup/tracker.sock`` would be used for the nginx configuration below. If you are customizing a docker continer to use gunicorn, see https://pythonspeed.com/articles/gunicorn-in-docker/. .. index:: pair: web interface; Waitress single: wsgi; Waitress Waitress Installation ~~~~~~~~~~~~~~~~~~~~~ Waitress is a pure Python WSGI server. It runs on Windows and you could use IIS or other web server to reverse proxy HTTP to it. You can use Waitress to serve Roundup without a proxy. It's not recommended, but it can be used on a local network where roundup can't be accessed from the internet. Assuming you have installed Roundup in a virtual environment (venv), install ``waitress`` and ``paste`` into the same venv using pip. ``paste`` is optional, but it provides logging middleware that produces standard combined format HTTP connection logs. You need to modify the file wsgi.py (obtained from ``frontends/wsgi.py``) to invoke waitress. It will look like:: # If you installed roundup to the system locations # using pip you don't need to change this # section. If you installed roundup in a custom # location, uncomment these lines and change the # path in the append() method to your custom path. #import sys #sys.path.append('/custom/location/where/roundup/is/installed') # Obtain the WSGI request dispatcher from roundup.cgi.wsgi_handler import RequestDispatcher # Set the path to tracker home. tracker_home = 'demo' # Definition signature for app: app(environ, start_response): # If using apache mod_wsgi change app to application. app = RequestDispatcher(tracker_home) from waitress import serve # Optional replaced TransLogger(app) with app if not installed from paste.translogger import TransLogger serve(TransLogger(app), host='0.0.0.0', port=8917, url_prefix=f"/{tracker_home}/") This will make Roundup available to any host on your local network at port 8917 under the ``/demo/`` path. Run it with ``python wsgi.py``. If you want to run just on the local loopback interface, replace ``0.0.0.0`` with ``127.0.0.1`` `See the Waitress docs`_ for more info on configuring waitress including putting it behind a proxy, IPV6 support etc. .. _`See the Waitress docs`: https://docs.pylonsproject.org/projects/waitress/en/stable/ .. index:: pair: web interface; uWSGI single: wsgi; uWSGI uWSGI Installation ~~~~~~~~~~~~~~~~~~ For a basic roundup install using uWSGI behind a front end server, install uwsgi and the python3 (or python) plugin. Then run:: uwsgi --http-socket 127.0.0.1:8917 \ --plugin python3 --mount=/tracker=wsgi.py \ --manage-script-name --callable app using the same wsgi.py as was used for Gunicorn. If you get path not found errors, check the mount option. The /tracker entry must match the path used for the [tracker] web value in the tracker's config.ini. Configure an Email Interface ============================ If you don't want to use the email component of Roundup, then remove the "``nosyreaction.py``" module from your tracker "``detectors``" directory. See `platform-specific notes`_ for steps that may be needed on your system. There are five supported ways to get emailed issues into the Roundup tracker. You should pick ONE of the following, all of which will continue my example setup from above: As a mail alias pipe process ---------------------------- Set up a mail alias called "issue_tracker" as (include the quote marks): "``|/usr/bin/python /usr/bin/roundup-mailgw ``" (substitute ``/usr/bin`` for wherever roundup-mailgw is installed). In some installations (e.g. RedHat Linux and Fedora Core) you'll need to set up smrsh so sendmail will accept the pipe command. In that case, symlink ``/etc/smrsh/roundup-mailgw`` to "``/usr/bin/roundup-mailgw``" and change the command to:: |roundup-mailgw /opt/roundup/trackers/support To test the mail gateway on unix systems, try:: echo test |mail -s '[issue] test' support@YOUR_DOMAIN_HERE Be careful that some mail systems (postfix for example) will impose limits on processes they spawn. In particular postfix can set a file size limit that is inherited by the mailgw. If the database files (anydbm, sqlite) exceed this limit, *this can cause your Roundup database to become corrupted.* As a custom router/transport using a pipe process (Exim4 specific) ------------------------------------------------------------------ The following configuration snippets for `Exim 4`_ configuration implement a custom router & transport to accomplish mail delivery to roundup-mailgw. A configuration for Exim3 is similar but not included, since Exim3 is considered obsolete. .. _Exim 4: https://www.exim.org/ This configuration is similar to the previous section, in that it uses a pipe process. However, there are advantages to using a custom router/transport process, if you are using Exim. * This avoids privilege escalation, since otherwise the pipe process will run as the mail user, typically mail. The transport can be configured to run as the user appropriate for the task at hand. In the transport described in this section, Exim4 runs as the unprivileged user ``roundup``. * Separate configuration is not required for each tracker instance. When a email arrives at the server, Exim passes it through the defined routers. The roundup_router looks for a match with one of the roundup directories, and if there is one it is passed to the roundup_transport, which uses the pipe process described in the previous section (`As a mail alias pipe process`_). The matching is done in the line:: require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py The following configuration has been tested on Debian Sarge with Exim4. .. note:: The Debian Exim4 packages don't allow pipes in alias files by default, so the method described in the section `As a mail alias pipe process`_ will not work with the default configuration. However, the method described in this section does. See the discussion in ``/usr/share/doc/exim4-config/README.system_aliases`` on any Debian system with Exim4 installed. For more Debian-specific information, see suggested addition to README.Debian in https://bugs.debian.org/cgi-bin/bugreport.cgi?bug=343283, which will hopefully be merged into the Debian package eventually. This config makes a few assumptions: * That the mail address corresponding to the tracker instance has the same name as the directory of the tracker instance, i.e. the mail interface address corresponding to a Roundup instance called ``/var/lib/roundup/trackers/mytracker`` is ``mytracker@your.host``. * That (at least) all the db subdirectories of all the tracker instances (ie. ``/var/lib/roundup/trackers/*/db``) are owned by the same user, in this case, 'roundup'. * That if the ``schema.py`` file exists, then the tracker is ready for use. Another option is to use the ``config.ini`` file (this changed in 0.8 from ``config.py``). Macros for Roundup router/transport. Should be placed in the macros section of the Exim4 config:: # Home dir for your Roundup installation ROUNDUP_HOME=/var/lib/roundup/trackers # User and group for Roundup. ROUNDUP_USER=roundup ROUNDUP_GROUP=roundup Custom router for Roundup. This will (probably) work if placed at the beginning of the router section of the Exim4 config:: roundup_router: driver = accept # The config file config.ini seems like a more natural choice, but the # file config.py was replaced by config.ini in 0.8, and schema.py needs # to be present too. require_files = /usr/bin/roundup-mailgw:ROUNDUP_HOME/$local_part/schema.py transport = roundup_transport Custom transport for Roundup. This will (probably) work if placed at the beginning of the router section of the Exim4 config:: roundup_transport: driver = pipe command = /usr/bin/python /usr/bin/roundup-mailgw ROUNDUP_HOME/$local_part/ current_directory = ROUNDUP_HOME home_directory = ROUNDUP_HOME user = ROUNDUP_USER group = ROUNDUP_GROUP As a regular job using a mailbox source --------------------------------------- Set ``roundup-mailgw`` up to run every 10 minutes or so. For example (substitute ``/usr/bin`` for wherever roundup-mailgw is installed):: 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support mailbox Where the ``mail_spool_file`` argument is the location of the roundup submission user's mail spool. On most systems, the spool for a user "issue_tracker" will be "``/var/mail/issue_tracker``". As a regular job using a POP source ----------------------------------- To retrieve from a POP mailbox, use a *cron* entry similar to the mailbox one (substitute ``/usr/bin`` for wherever roundup-mailgw is installed):: 0,10,20,30,40,50 * * * * /usr/bin/roundup-mailgw /opt/roundup/trackers/support pop where pop_spec is "``username:password@server``" that specifies the roundup submission user's POP account name, password and server. apop (authenticated) and pops (pop over ssl) methods are also supported. See `the section on mailgw in the admin guide `_. On windows, you would set up the command `using the windows scheduler`_. As a regular job using an IMAP source ------------------------------------- To retrieve from an IMAP mailbox, use a *cron* entry similar to the POP one (substitute ``/usr/bin`` for wherever roundup-mailgw is installed):: 0,10,20,30,40,50 * * * * /usr/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 securnae connection. To use imap with CRAM or OAUTH, see `the section on mailgw in the admin guide `_ . As with the POP job, on windows, you would set up the command `using the windows scheduler`_. UNIX Environment Steps ====================== Each tracker ideally should have its own UNIX group, so create a UNIX group (edit ``/etc/group`` or your appropriate NIS map if you're using NIS). To continue with my examples so far, I would create the UNIX group 'support', although the name of the UNIX group does not have to be the same as the tracker name. To this 'support' group I then add all of the UNIX usernames who will be working with this Roundup tracker. In addition to 'real' users, the Roundup email gateway will need to have permissions to this area as well, so add the user your mail service runs as to the group (typically "mail" or "daemon"). The UNIX group might then look like:: support:*:1002:jblaine,samh,geezer,mail If you intend to use the web interface (as most people do), you should also add the username your web server runs as to the group. My group now looks like this:: support:*:1002:jblaine,samh,geezer,mail,apache The tracker "db" directory should be chmod'ed g+sw so that the group can write to the database, and any new files created in the database will be owned by the group. If you're using the mysql or postgresql backend then you'll need to ensure that the tracker user has appropriate permissions to create/modify the database. If you're using roundup.cgi, the apache user needs permissions to modify the database. Alternatively, explicitly specify a database login in ``rdbms`` -> ``user`` and ``password`` in ``config.ini``. An alternative to the above is to create a new user who has the sole responsibility of running roundup. This user: 1. runs the CGI interface daemon 2. runs regular polls for email 3. runs regular checks (using cron) to ensure the daemon is up 4. optionally has no login password so that nobody but the "root" user may actually login and play with the roundup setup. If you're using a Linux system (e.g. Fedora Core) with SELinux enabled, you will need to ensure that the db directory has a context that permits the web server to modify and create files. If you're using the mysql or postgresql backend you may also need to update your policy to allow the web server to access the database socket. Public Tracker Considerations ============================= If you run a public tracker, you will eventually have to think about dealing with spam entered through both the web and mail interfaces. See the section on `Preventing SPAM`_ in the `customisation documentation`_ that has a simple detector that will block lot of spam attempts. Also you can consider adding `reCaptcha to reduce bot logins as described on the wiki `_. The wiki also documents how to add `multi-factor (MFA)/one time keys/password using TOTP/HOTP `_. If you have a single sign on system see: the `wiki page on using Shibboleth `_ or `LDAP `_ with Roundup. More customisation can be found under the Security headings of the `CustomisationExamples wiki page `_ and `AdminstrationExample `_ pages on the wiki. Docker Support ============== If you don't want to install Roundup on a host, you can create a Docker container or use the `pre-built container on hub.docker.com `_. Docker hub images support `multiple tags <#tags-for-dockerhub-docker-images>`_. Docker images run Roundup using the `stand-alone web server`_ method. The image only supports http. We suggest putting an https terminating proxy in front of it. This is a work in progress and patches to improve it are welcome. You can find the docker config files under the `scripts/Docker` directory of the source tree. The Roundup container uses the 64 bit Alpine Python distribution. It includes database drivers for anydbm, SQLite, MySQL and Postgresql (Postgresql is untested). It also includes additional libraries that are listed in `scripts/Docker/requirements.txt` (including redis client support). Email support is a work in progress. Outgoing email to an external SMTP server should work. Receiving email should work by using a scheduled (cron) job to access email: * `As a regular job using a mailbox source`_ * `As a regular job using a POP source`_ * `As a regular job using an IMAP source`_ However running cron in a container is problematic (running busybox crond as root vs. non-root, requiring setgrp privs etc). Using the host's crontab with a command like:: docker exec roundup-tracker roundup-mailgw tracker \ mailbox /var/spool/mail/roundup might be a solution if you can mount a mail spool directory or use pop/imap. Patches for implementing better email support are welcome. If you want to use a MySQL backend, see `Docker-compose Deployment`_ to deploy a Roundup container and a MySQL container backend for use with Roundup. We recommend you follow the `OSWAP Docker Security practices`_ for your production Roundup instance. .. _OSWAP Docker Security practices: https://cheatsheetseries.owasp.org/cheatsheets/Docker_Security_Cheat_Sheet.html Building a Docker Container --------------------------- You can build a docker container in one of 4 modes defined by the ``source`` build-arg. ``--build-arg="source=local"`` the default if no source is defined. Build using the version in the source tree by running ``setup.py install``. ``--build-arg="source=pypi"`` build the newest production release version deployed to pypi. If you want to build using a pre-release, you can append `pip version specifiers `_ to `pypi` without embedding any spaces. For example:: # install 2.2.0 if available or 2.2.0b1 or 2.2.0b2 etc. --build-arg="source=pypi~=2.2.0b1" # install only a 2.2.0 beta --build-arg="source=pypi~=2.2.0b1,!=2.2.0" Note that versions of Roundup before 2.2 may not run correctly in a Docker container. ``--build-arg="source=pip_local"`` Build using the version in the source tree by running ``pip install``. This places some files (e.g. man pages, templates) in different directories from the `local` install but is preferred by some Python users. ``--build-arg="source=pip_sdist"`` Disabled - hopefully it will be available in the future. This is meant for maintainer/developer use. It installs using pip from a source distribution (sdist) tarball built by following the RELEASE.txt. It is meant for testing releases or building a docker image that installs a new pending source distribution release. Normal users/admins should not use it. Use ``local`` or ``pip_local`` instead. Build a docker container using the code in the current directory, with this build command from the top of the source tree:: docker build -t roundup-app -f scripts/Docker/Dockerfile . Build a container using the newest production (non pre-release) Roundup release on PyPI, by running:: docker build -t roundup-app --build-arg="source=pypi" \ -f scripts/Docker/Dockerfile . Change the ``build-arg`` for building in other modes. The Dockerfile declares a single volume mounted at ``/usr/src/app/tracker`` inside the container. You will mount your tracker home directory at this location. The ``/usr/src/app`` path can be changed by adding:: --build-arg="appdir=/new/path" You can also add additional modules to the docker container by using:: --build-arg="pip_mod=requests setproctitle" Because of deficiencies in the docker program (see: https://github.com/moby/moby/issues/29110#issuecomment-1100676306), there is no way to determine the version of Python inside the container and make that available as part of the build process. If your build fails because the ``pythonversion does not match``, add the suggested ``--build-arg`` to the ``docker build`` command line. .. _UID at image build time: By default the container runs Roundup using UID 1000. By setting ``--build-arg="roundup_uid=2000"`` you can change the UID and GID. Configuring Roundup in the Container ------------------------------------ .. caution:: Docker modifies iptables firewall rules. This allows access to the container from your local network. `See the official documentation for details `_. UFW rules are known to be be ignored (see: https://github.com/moby/moby/issues/4737). Use ``-p 127.0.0.1:ext_port:container_port`` in your docker run commands or implement suggestions like: https://github.com/chaifeng/ufw-docker. Once the docker image is created using one of the build commands above, run an interactive session with:: docker run -it --rm -p 127.0.0.1:9017:8080 \ -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest The ``-v`` option maps a directory from the host into the docker container. Note that uid 1000 is used by roundup by default. The uid of the directory (and all files under it) must match the uid. You can set the `UID at image build time`_. This example assumes your tracker configs are in the tracker subdirectory. Replace ``$PWD/tracker`` with the full path name to the directory where the tracker home(s) are to be stored. The ``-p`` option maps an external port (9017) to proxy the roundup server running at port 8080 to the outside. Note if you remove ``127.0.0.1:`` from the -p argument, *any host* on the network will be able to access the tracker at port 9017. If the tracker directory is empty, the docker container will prompt you to `install a tracker template`_ (step 3) and prompt you for the database type. .. _install a tracker template: #configuring-your-first-tracker Then you need to configure the tracker by editing ``template/config.ini``. Make sure that the tracker web setting ends in ``/issues/`` See `Configuring your first tracker`_ and the top of ``config.ini`` for other settings. Once you have configured the tracker, run another interactive session to `initialise the tracker`_ (step 4) with:: docker run -it --rm -p 127.0.0.1:9017:8080 \ -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest this will initialise the database and attempt to start the server. If that is successful, use control-c to exit the server. .. _initialise the tracker: #configuring-your-first-tracker Now start the server non-interactively (note no `-it` option) with:: docker run -p 9017:8080 -d \ -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest Your tracker will be available at: ``http://yourhost:9017/issues/``. If you need to access your container while the server is running you can use:: docker exec -it c0d5 sh where ``c0d5`` is the id prefix for the running container obtained from ``docker container ls``. You should place a web server in front of Roundup (in reverse proxy mode) for production use. See the proxy_pass example below: * `Nginx HTTP Server`_ You can expose the port directly to your intranet by removing ``127.0.0.1`` from the ``-p`` option. See `Stand-alone Web Server`_ for more details. Running Your Container ---------------------- .. note:: The examples below use the locally built docker container specification: ``roundup-app``. You can replace it with the docker hub specification ``rounduptracker/roundup:latest`` (provided latest is newer than 2.3.0). As of version 2.3.0 the Docker container has multiple entry points. Guided install ~~~~~~~~~~~~~~ By default, running:: docker run -it --rm -p 127.0.0.1:9017:8080 \ -v $PWD/tracker:/usr/src/app/tracker roundup-app:latest 3 times will install, initialize and serve a Roundup tracker at ``..../issues/`` using ``$PWD/tracker`` as the tracker home. This is the "guided install" method described in `Configuring Roundup in the Container`_. Arguments for roundup-server ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Once you have initialized your tracker, any arguments placed at the end of the ``docker run`` command are passed to the ``roundup-server``. These arguments **replace** the default arguments of ``issues=tracker``. Brief Help ~~~~~~~~~~ You can get help running the docker image:: docker run -it \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest help Invoking a Shell ~~~~~~~~~~~~~~~~ You can invoke a shell inside the container without exec'ing into the container using:: docker run -it \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest shell Then you can manually configure your tracker using ``roundup-admin -i tracker`` using the directions for `Configuring your first tracker`_. This is also how you would access tools like ``roundup-gettext`` which do not have direct entry points like ``admin`` for ``roundup-admin`` and ``demo`` for ``roundup-demo``. Invoke roundup-admin ~~~~~~~~~~~~~~~~~~~~ You can run ``roundup-admin`` directly by using:: docker run -it \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest admin -i tracker/tracker1 to start ``roundup-admin`` using the directory ``$PWD/tracker/tracker1``. This is one way to create multiple trackers in subdirectories. It is no different from starting a shell and invoking ``roundup-admin`` manually. One possibly useful command is:: docker run -it \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest admin templates to list description of all the installed templates. Invoke roundup-demo ~~~~~~~~~~~~~~~~~~~ Lastly you can:: docker run -it -p 127.0.0.1:8917:8080 \ -v $PWD/tracker:/usr/src/app/tracker \ roundup-app:latest demo anydbm responsive to create a directory ``$PWD/tracker/demo`` and autoconfigure a server using the anydbm backend based on the responsive tracker template. See `demo mode using docker`_ for steps to change the server port. Debugging ~~~~~~~~~ If you add ``-e SHELL_DEBUG=1`` to the docker command, it sets the ``SHELL_DEBUG`` environment variable which will enable debugging output from the startup script. Running Multiple Trackers -------------------------- If you want to run multiple trackers, create a subdirectory for each tracker home under the volume mount point (``$PWD/tracker``). Then invoke ``docker run`` passing the roundup-server tracker specifications like:: docker run --rm -p 9017:8080 \ -v /.../issue.tracker:/usr/src/app/tracker \ roundup-app:latest tracker1=tracker/tracker1_home \ tracker2=tracker/tracker2_home This will set up two trackers that can be reached at ``http://yourhost:9017/tracker1/`` and ``http://yourhost:9017/tracker2/``. The arguments after ``roundup-app:latest`` are arguments including tracker paths that are passed to ``roundup-server``. Docker-compose Deployment ------------------------- If you want to run using the mysql backend, you can use docker-compose with ``scripts/Docker/docker-compose.yml``. This will run Roundup and MySQL in containers. Directions for building using docker-compose are at the top of the yml file. Tags for Dockerhub Docker Images -------------------------------- The docker images available from https://hub.docker.com/r/rounduptracker/roundup are tagged with: version-build, version, and ``latest`` tags. Only production releases (not pre-releases) are tagged this way. For example, the tags when 2.3.0 is released will be: ``rounduptracker/roundup:latest`` is a moving tag that tracks the latest build with the newest production version of Roundup using the current newest Alpine release with the versions of Python packages at the time of the build. ``rounduptracker/roundup:2.3.0`` is a moving tag that tracks the latest build of version 2.3.0 of Roundup. The Roundup software in this build will match the 2.3.0 version released on PyPi, but the underlying Alpine image or versions of the supporting Python libraries (redis, xapian, psycopg2, ...) will change. ``rounduptracker/roundup:2.3.0-1`` is a static tag and marks the first build of the version 2.3.0 docker image. When a new release of the image is done, it will get the tag ``2.3.0-2`` etc. This is an alternative to pulling using a sha256 sum. However it is possible to overwrite this image/tag. So it **does not** provide the same security guarantees that using a sha256 sum does. In addition to the release tags, there may be one or more development tags available. All tags will include `devel`. For example: ``rounduptracker/roundup:2.3.0b1-devel``, ``rounduptracker/roundup:devel`` You should not assume that any ``devel`` tag is static. They are mainly for use by Roundup developers/maintainers/testers for testing. There may be alternate tags ending with ``-devel`` to indicate builds from specific Mercurial versions/hashes. Also the tag may be overwritten to change the underlying Python libraries or images. Unless you like the bleeding edge, these should **not** be used in production. Maintenance =========== Read the `Tasks section of the administration guide `_ for information about how to perform common maintenance tasks on Roundup. Upgrading ========= Read the separate `upgrading document`_, which describes the steps needed to upgrade existing tracker trackers for each version of Roundup that is released. Further Reading =============== If you intend to use Roundup with anything other than the default templates, if you would like to hack on Roundup, or if you would like implementation details, you should read `Customising Roundup`_ and the `Roundup reference`_. Running Multiple Trackers ========================= Things to think about before you jump off the deep end and install multiple trackers, which involve additional URLs, user databases, email addresses, databases to back up, etc. 1. Do you want a tracker per product you sell/support? You can just add a new property to your issues called Product, and filter by that. See the customisation example `adding a new field to the classic schema`_. 2. Do you want to track internal software development issues and customer support issues separately? You can just set up an additional "issue" class called "cust_issues" in the same tracker, mimicing the normal "issue" class, but with different properties. See the customisation example `tracking different types of issues`_. Platform-Specific Notes ======================= Windows ------- .. index:: windows; choose non-default session/otk database Configure session database ~~~~~~~~~~~~~~~~~~~~~~~~~~ By default the session and one time key (OTK) databases default to using anydbm as the session store. Because GNU dbm and Ndbm are available on Linux, this is a reasonable default. However Windows doesn't have compiled libraries for these databases. So it defaults to "dumb" dbm which is written in Python and is slow. So we recommend using `some other backend for your session database`_. SQLite or Redis can be used if you don't want to run a separate supported RDBMS database server. .. index:: windows; add Roundup to path Windows command-line tools ~~~~~~~~~~~~~~~~~~~~~~~~~~ To make the command-line tools accessible in Windows, you need to update the "Path" environment variable in the Registry via a dialog box. On Windows 2000 and later: 1) Press the "Start" button. 2) Choose "Settings" 3) Choose "Control Panel" 4) Choose "System" 5) Choose "Advanced" 6) Choose "Environmental Variables" 7) Add: "\Scripts" to the "Path" environmental variable. Where in 7) is the root directory (e.g., ``C:\Python27\Scripts``) of your Python installation. I understand that in XP, 2) above is not needed as "Control Panel" is directly accessible from "Start". I do not believe this is possible to do in previous versions of Windows. Use pip to install pyreadline3 for roundup-admin line editing If you install pyreadline3_ using pip, roundup-admin will support command line editing and history. This will remove the dreaded:: Note: command history and editing not available warning when starting roundup-admin. Windows Server ~~~~~~~~~~~~~~ To have the Roundup web server start up when your machine boots up, there are two different methods, the scheduler and installing the service. .. index:: windows; use scheduler for email integration .. _Using the Windows scheduler: 1. Using the Windows scheduler '''''''''''''''''''''''''''''' Set up the following in Scheduled Tasks (note, the following is for a cygwin setup): Run ``c:\cygwin\bin\bash.exe -c "roundup-server TheProject=/opt/roundup/trackers/support"`` Start In ``C:\cygwin\opt\roundup\bin`` Schedule At System Startup To have the Roundup mail gateway run periodically to poll a POP email address, set up the following in Scheduled Tasks: Run ``c:\cygwin\bin\bash.exe -c "roundup-mailgw /opt/roundup/trackers/support pop roundup:roundup@mail-server"`` Start In ``C:\cygwin\opt\roundup\bin`` Schedule Every 10 minutes from 5:00AM for 24 hours every day Stop the task if it runs for 8 minutes .. index:: windows; setup Roundup a service 2. Installing the roundup server as a Windows service ''''''''''''''''''''''''''''''''''''''''''''''''''''' This is more Windows oriented and will make the Roundup server run as soon as the PC starts up without any need for a login or such. It will also be available in the normal Windows Administrative Tools. For this you need first to create a service ini file containing the relevant settings. 1. It is created if you execute the following command from within the scripts directory (notice the use of backslashes):: roundup-server -S -C \server.ini -n -p 8080 -l \trackerlog.log software=\Software where the item ```` is replaced with the physical directory that hosts all of your trackers. The ```` item is the name of your roundup server PC, such as w2003srv or similar. 2. Next open the now created file ``C:\DATA\roundup\server.ini`` file (if your ```` is ``C:\DATA\roundup``). Check the entries for correctness, especially this one:: [trackers] software = C:\DATA\Roundup\Software (this is an example where the tracker is named software and its home is ``C:\DATA\Roundup\Software``) 3. Next give the commands that actually installs and starts the service:: roundup-server -C C:\DATA\Roundup\server.ini -c install roundup-server -c start 4. Finally open the AdministrativeTools/Services applet and locate the Roundup service entry. Open its properties and change it to start automatically instead of manually. If you are using Apache as the webserver you might want to use it with mod_python instead to serve out Roundup. In that case see the mod_python instructions above for details. Linux ----- Make sure you read the instructions under `UNIX environment steps`_. Sendmail smrsh ~~~~~~~~~~~~~~ If you use Sendmail's ``smrsh`` mechanism, you will need to tell smrsh that roundup-mailgw is a valid/trusted mail handler before it will work. This is usually done via the following 2 steps: 1. make a symlink in ``/etc/smrsh`` called ``roundup-mailgw`` which points to the full path of your actual ``roundup-mailgw`` script. 2. change your alias to ``"|roundup-mailgw "`` Solaris ------- You'll need to build Python. Make sure you read the instructions under `UNIX environment steps`_. Problems? Testing your Python... ================================ .. note:: The ``run_tests.py`` script is not packaged in Roundup's source distribution anymore. You should install: * pytest, * requests, and * mock using your distributions package manger or using pip/pip2/pip3 to install pytest etc. for your Python version. See the `administration guide`_ for details. Remember to have a database user 'rounduptest' prepared (with password 'rounduptest'). This user must have at least the rights to create and drop databases. Documentation: details on `adding MySQL users`_, for PostgreSQL you want to call the ``createuser`` command with the ``-d`` option to allow database creation. This can only be done if you `install the source`_ distribution (steps 1-3) or from a `mercurial checkout <../code.html#get-sources>`_. It will not work if you used `pip install` as the test suite is not installed. Once you've unpacked roundup's source, if you have pytest installed, run ``python -m pytest test`` in the Roundup source directory and make sure there are no errors. If there are errors, please let us know! Note that redis tests uses database 15 of the redis server running on localhost.The tests verify that the database is empty before the redis tests start. If you use a password on your redis database it can be specified in the ``pytest_redis_pw`` environment variable when you run the test. .. _`user guide`: user_guide.html .. _`roundup specification`: spec.html .. _`tracker configuration`: reference.html#tracker-configuration .. _`customisation documentation`: customizing.html .. _`Roundup reference`: reference.html .. _`reference documentation`: reference.html .. _`preventing spam`: customizing.html#preventing-spam .. _`Adding a new field to the classic schema`: customizing.html#adding-a-new-field-to-the-classic-schema .. _`some other backend for your session database`: admin_guide.html#configuring-session-databases .. _`Tracking different types of issues`: customizing.html#tracking-different-types-of-issues .. _`customising roundup`: customizing.html .. _`upgrading document`: upgrading.html .. _`administration guide`: admin_guide.html .. _`What does Roundup install`: admin_guide.html#what-does-roundup-install .. _`doc/postgresql.txt`: postgresql.html .. _`doc/mysql.txt`: mysql.html .. _External hyperlink targets: .. _`adding MySQL users`: https://dev.mysql.com/doc/refman/8.0/en/creating-accounts.html .. _apache: https://httpd.apache.org/ .. _brotli: https://pypi.org/project/Brotli/ .. _`developer's guide`: developers.html .. _defusedxml: https://pypi.org/project/defusedxml/ .. _docutils: https://pypi.org/project/docutils/ .. _flup: https://pypi.org/project/flup/ .. _gpg: https://www.gnupg.org/software/gpgme/index.html .. _jinja2: https://palletsprojects.com/projects/jinja/ .. _markdown: https://python-markdown.github.io/ .. _markdown2: https://github.com/trentm/python-markdown2 .. _mistune: https://pypi.org/project/mistune/ .. _mod_python: https://github.com/grisha/mod_python .. _mod_wsgi: https://pypi.org/project/mod-wsgi/ .. _MySQLdb: https://pypi.org/project/mysqlclient/ .. _Olson tz database: https://www.iana.org/time-zones .. _polib: https://polib.readthedocs.io .. _Psycopg2: https://www.psycopg.org/ .. _pyjwt: https://pypi.org/project/PyJWT/ .. _pyopenssl: https://pypi.org/project/pyOpenSSL/ .. _pyreadline3: https://pypi.org/project/pyreadline3/ .. _pysqlite: https://pysqlite.org/ .. _pytz: https://pypi.org/project/pytz/ .. _pywin32: https://pypi.org/project/pywin32/ .. _Redis: https://redis.io .. _redis-py: https://pypi.org/project/redis/ .. _requests: https://requests.readthedocs.io/en/latest/ .. _Whoosh: https://whoosh.readthedocs.io/en/latest/ .. _Xapian: https://xapian.org/ .. _zstd: https://pypi.org/project/zstd/ code-001c16ac87ec/doc/license.txt0000644000000000000000000000034415046233326014656 0ustar 00000000000000License ======= Roundup is Free Software under the following license (from the file COPYING.txt in the software distribution): .. raw:: html
.. include:: ../COPYING.txt .. raw:: html
code-001c16ac87ec/doc/man_pages.txt0000644000000000000000000000067515046233326015175 0ustar 00000000000000.. meta:: :description: Links to man pages for the top level commands provided by Roundup. ==================== Roundup Manual Pages ==================== Roundup man pages have been formated as html for your use. * `roundup-admin `_ * `roundup-demo `_ * `roundup-mailgw `_ * `roundup-server `_ code-001c16ac87ec/doc/mysql.txt0000644000000000000000000000660615046233326014410 0ustar 00000000000000.. index:: mysql; deployment notes ============= MySQL Backend ============= This notes detail the MySQL backend for the Roundup issue tracker. Prerequisites ============= To use MySQL as the backend for storing roundup data, you also need to install: 1. MySQL RDBMS 8.0.11 or higher - https://www.mysql.com/. Your MySQL installation MUST support InnoDB tables. 2. Python MySQL interface - https://pypi.org/project/mysqlclient/ Preparing the Database ====================== The Roundup user expects to be able to create and drop its database when using ``roundup_admin init``. In the examples below, replace ``roundupuser``, ``rounduppw`` and ``roundupdb`` with suitable values. This assumes you are running MySQL on the same host as you are running Roundup. If this is not the case, setting up remote credentials, SSL/TLS etc. is beyond the scope of this documentation. However examples are welcome on the wiki or mailing list. These references may be helpful: https://dev.mysql.com/doc/refman/8.0/en/create-user.html and https://dev.mysql.com/doc/refman/8.0/en/grant.html. Creating a Role/User -------------------- The following command will create a ``roundupuser`` with the ability to create the database:: mysql -u root -e 'CREATE USER "roundupuser"@"localhost" IDENTIFIED WITH mysql_native_password BY "rounduppw"; GRANT ALL on roundupuser.* TO "roundupuser"@"localhost";' Other Configuration =================== If you are indexing large documents (e.g attached file contents) using MySQL, you may need to increase the max_allowed_packet size. If you don't you can see the error:: 'MySql Server has gone away (2006)' To do this edit /etc/my.conf and change:: [mysqld] max_allowed_packet = 1M the 'max_allowed_packet' value from '1M' to '64M' or larger. Alternatively you can install an alternate indexer (whoosh, xapian etc.) and force the tracker to use it by setting the ``indexer`` setting in the tracker's ``config.ini``. This fix was supplied by telsch. See issue https://issues.roundup-tracker.org/issue2550743 for further info or if you are interested in developing a patch to roundup to help work around this issue. Running the MySQL tests ======================= Roundup tests expect an empty MySQL database. Two alternate ways to provide this: 1. If you have root permissions on the MySQL server, you can create the necessary database entries using the following SQL sequence. Use ``mysql`` on the command line to enter:: CREATE DATABASE rounduptest; USE rounduptest; GRANT ALL PRIVILEGES ON rounduptest.* TO rounduptest@localhost IDENTIFIED BY 'rounduptest'; FLUSH PRIVILEGES; 2. If your administrator has provided you with database connection info, see the config values in 'test/db_test_base.py' about which database connection, name and user will be used. The MySQL database should not contain any tables. Tests will not drop the database with existing data. Note that ``rounduptest`` is a well known account. You should delete it and the ``rounduptest`` database and create a new user/database for production use. Showing MySQL who's boss ======================== If things ever get to the point where that test database is totally hosed, just:: $ su - # /etc/init.d/mysql stop # rm -rf /var/lib/mysql/rounduptest # /etc/init.d/mysql start and all will be better (note that on some systems, ``mysql`` is spelt ``mysqld``). code-001c16ac87ec/doc/overview.txt0000644000000000000000000005747415046233326015122 0ustar 00000000000000.. meta:: :description: Original proposal for the Roundup Issue Tracker. The problem it solves, and guiding principles. Presents the components of Roundup and how they interact. ======================================================= Roundup: an Issue-Tracking System for Knowledge Workers ======================================================= :Authors: Ka-Ping Yee (original_), Richard Jones (implementation) .. _original: original_overview.html .. contents:: Introduction ============ Roundup is an issue-tracking system called which will manage a number of issues (with 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. Roundup facilitates communication among the participants by managing discussions and notifying interested parties when issues are edited. Background ---------- A typical software project requires the management of many tasks, usually distributed among several collaborators. In fact, any project team could use a tool for sorting out and discussing all the relevant issues. A common approach is to set up some kind of "to-do" list that people can share. However, to address the overall problem we need much more than just a shared to-do list; we need to manage a growing body of knowledge and experience to help a team collaborate effectively on a project. The issue-tracking tool becomes a nexus for communication: the Grand Central Station of the group intelligence. The primary focus of this design is to help developers work together well, not to provide a customer service interface to the developers. This is not to say that the design is to be made unsuitable for customers to use. Rather, it is assumed that many of the same qualities that are good for supporting development (see below) are also good for non-developers using the system. Additional niceties for providing a safe or simplified interface to clients are intentionally deferred for later consideration. A good issue-tracking system should have at least the following properties: **Low barrier to participation** The usefulness of the tool depends entirely on the information people contribute to it. It must be made as easy as possible to submit new issues and contribute information about existing issues. **Straightforward navigation** It should be easy for users to extract information they need from the system to direct their decisions and tasks. They should be able to get a decent overview of things as well as finding specific information when they know what they're after. **Controlled information flow** The users must have control over how much information and what information they get. A common flaw of some issue-tracking systems is that they inundate users with so much useless e-mail that people avoid the system altogether. With a nod to the time-honoured computer science tradition of "filling in the fourth quadrant", we note that there are really four kinds of information flow going on here. The three mentioned qualities really address the first three quadrants of this 2-by-2 matrix, respectively: 1. User push: a user submits information to the system. 2. User pull: a user queries for information from the system. 3. System push: the system sends information out to users. 4. System pull: the system solicits information from users. An example of the fourth kind of flow is voting. Voting isn't described in this design, but it should be noted as a potential enhancement. Guiding Principles ------------------ **Simplicity** It is a strong requirement that the tool be accessible and understandable. It should be fairly obvious what different parts of the interface do, and the inner mechanisms should operate in ways that most users can easily predict. **Efficiency** We aim to optimize for minimum effort to do the most common operations, and best use of resources like screen real estate to maximize the amount of information that we summarize and present. **Generality** We try to avoid making unnecessary assumptions that would restrict the applicability of the tool. For example, there is no reason why one might not also want to use this tool to manage a design process, non-software projects, or organizational decisions. **Persistence** We prefer hiding or reclassifying information to deleting it. This helps support the collection of statistics later. If records are never destroyed, there is little danger in providing access to a larger community, and logging yields accountability, which may encourage better behaviour. Data Model ========== Roundup stores a number of *items*, each of which can have several properties and an associated discussion. The properties can be used to classify or search for items. The discussion is a sequence of e-mail messages. Each item is identified by a unique number, and has an activity log which records the time and content of edits made on its properties. The log stays fairly small since the design intentionally provides only small data types as item properties, and encourages anything large to be attached to e-mail where it becomes part of the discussion. The next section explains how items are organized. The Hyperdatabase ----------------- Often when classifying information we are asked to select exactly one of a number of categories or to fit it into a rigid hierarchy. Yet things only sometimes fall into one category; often, a piece of information may be related to several concepts. For example, forcing each item into a single keyword category is not just suboptimal but counterproductive: seekers of that item may expect to find it in a different category and conclude that the item is not present in the database -- which has them *worse* off than if the items were not categorized at all. Some systems try to alleviate this problem by allowing items to appear at multiple locations in a tree, as with "aliases" or "symbolic links" in a filesystem, for example. This does help somewhat, but we want to be even more flexible by allowing the organization of items into sets that may freely intersect. Rather than putting each item at exactly one place in an overall "grand scheme", a item can belong to as many sets as are appropriate. If we choose to represent the sets themselves as items and set membership as a link between items, we're now ready to present the definition of a hyperdatabase. A *hyperdatabase* is a collection of *items* that may be hyperlinked to each other (hence the name "hyperdatabase"). Each item carries a collection of key-value pairs, where some of the values may be links to other items. Any item may have an arbitrary number of outgoing and incoming links. Hyperdatabases are able to efficiently answer queries such as "what items link to this item?" and "what items does this item link to?" Rationale --------- There are several reasons for building our own kind of database for Roundup rather than using an existing one. Requiring the installation of a full-blown third-party SQL database system would probably deter many potential users from attempting to set up Roundup; yet a real relational database would be too complicated to implement on our own. On the other hand, a hyperdatabase can be implemented fairly easily using one of the Python DBM modules, so we can take the "batteries-included" approach and provide it as part of the system. It's easier to build and understand than a true relational database (in accordance with our guiding principle of *simplicity*), but provides most of the query functionality we want. A hyperdatabase is well suited for finding the intersection of a number of sets in which items belong. We expect that most of the queries people want to do will be of this form, rather than complicated SQL queries. For example, a typical request might be "show me all critical items related to security". The ability to store arbitrary key-value pairs and links on items gives it more flexibility than an RDBMS. Users are not going to be making thousands of queries per second, so it makes sense to optimize for simplicity and flexibility rather than performance. .. img: images/hyperdb.png Roundup's Hyperdatabase ----------------------- For our application, we store each item as a item in a hyperdatabase. The item's properties are stored as key-value pairs on its item. Several types of properties are allowed: *string*, *number*, *boolean*, *date*, *interval, *link*, and *multlink*. Another type, *password*, is a special type of string and it's only used internally to Roundup. The *string* type is for short, free-form strings. String properties are not intended to contain large amounts of text, and it is recommended that they be presented as one-line fields to encourage brevity. A *number* is a special type of string that represents a numeric value. A *boolean* is further constrained to be a *true* or *false* value. The *date* type is for calendar dates and times. An *interval* is the time between two dates. The *link* type denotes a single selection from a number of options. A *link* property entails a link from the item possessing the property to the item representing the chosen option. The *multilink* type is for a list of links to any number of other items in the in the database. A *multilink* property, for example, can be used to refer to related items or keyword categories relevant to an item. For Roundup, all items have four properties that are not customisable: 1. a *date* property named **creation** 2. a *link* property named **creator** 3. a *date* property named **activity** These properties represent the date of the creation of the item, who created it, and when the last change was made. Further, all *issue* items have an additional four properties: 1. a *string* property named **title** 2. a *multilink* property named **nosy** 3. a *multilink* property named **messages** 4. a *multilink* property named **files** 5. a *multilink* property named **superseder** The **title** property is a short one-line description of the item. The detailed description can go in the first e-mail message of the item's messages spool. The **nosy** property contains a list of the people who are interested in an item. This mechanism is explained in the section on `Submission and Discussion`_. Each message added to the item goes in the **messages** spool - any attached files go in the **files** spool. The **superseder** property is used to support the splitting, joining, or replacing of items. When several items need to be joined into a single item, all the old items link to the new item in their **superseder** property. When an item needs to be split apart, the item references all the new items in its **superseder** propety. We can easily list all active items just by checking for an empty **superseder** property, and trace the path of an item's origins by querying the hyperdatabase for links. Users of the system are also represented by items in the hyperdatabase, containing properties like the user's e-mail address, login name, and password. The Default Schema ------------------ It is hoped that the hyperdatabase together with the specializations mentioned above for Roundup will be applicable in a variety of situations (in accordance with our guiding principle of *generality*). To address the problem at hand, we need a specific schema for items applied particularly to software development. Again, we are trying to keep the schema simple: too many options make it tougher for someone to make a good choice:: # IssueClass automatically gets these properties: # title = String() # messages = Multilink("msg") # files = Multilink("file") # nosy = Multilink("user") # superseder = Multilink("issue") # (it also gets the Class properties creation, activity and creator) issue = IssueClass(db, "issue", assignedto=Link("user"), keyword=Multilink("keyword"), priority=Link("priority"), status=Link("status")) The **assignedto** property assigns responsibility for an item to a person or a list of people. The **keyword** property places the item in an arbitrary number of relevant keyword sets (see the section on `Browsing and Searching`_). The **prority** and **status** values are initially: =========== ===================================== Priority Description =========== ===================================== "critical" panic: work is stopped! "urgent" important, but not deadly "bug" lost work or incorrect results "feature" want missing functionality "wish" avoidable bugs, missing conveniences =========== ===================================== ============= ===================================== Status Description ============= ===================================== "unread" submitted but no action yet "deferred" intentionally set aside "chatting" under review or seeking clarification "need-eg" need a reproducible example of a bug "in-progress" understood; development in progress "testing" we think it's done; others, please test "done-cbb" okay for now, but could be better "resolved" fix has been released ============= ===================================== As previously mentioned, each item gets an activity log. Whenever a property on an item is changed, the log records the time of the change, the user making the change, and the old and new values of the property. This permits the later gathering of statistics (for example, the average time from submission to resolution). We do not specify or enforce a state transition graph, since making the system rigid in that fashion is probably more trouble than it's worth. Experience has shown that there are probably two convenient automatic state transitions: 1. from **unread** to **chatting** when e-mail is written about an item 2. from **testing** to **resolved** when a new release of the software is made Beyond these, in accordance with our principle of *generality*, we allow access to the hyperdatabase API so that scripts can automate transitions themselves or be triggered by changes in the database. User Interface ============== Roundup provides its services through two main interfaces: e-mail and the Web. This division is chosen to optimize the most common tasks. E-mail is best suited for the submission of new items since most people are most comfortable with composing long messages in their own favourite e-mail client. E-mail also permits them to mention URLs or attach files relevant to their submission. Indeed, in many cases people are already used to making requests by sending e-mail to a mailing list of people; they can do exactly the same thing to use Roundup without even thinking about it. Similarly, people are already familiar with holding discussions in e-mail, and plenty of valuable usage conventions and software tools already exist for that medium. The Web, on the other hand, is best suited for summarizing and seeking information, because it can present an interactive overview of items. Since the Web has forms, it's also the best place to edit items. Submission and Discussion ------------------------- The system needs an address for receiving mail and an address that forwards mail to all participants. Each item has its own list of interested parties, known as its *nosy list*. Here's how nosy lists work: 1. New items are always submitted by sending an e-mail message to Roundup. The "Subject:" field becomes the description of the new item. The message is saved in the mail spool of the new item, and copied to the list of all participants so everyone knows that a new item has been added. The new item's nosy list initially contains the submitter. 2. All e-mail messages sent by Roundup have their "Reply-To:" field set to Roundup's address, and have the item's number in the "Subject:" field. Thus, any replies to the initial announcement and subsequent threads are all received by Roundup. Roundup notes the item number in the "Subject:" field of each incoming message and appends the message to the appropriate spool. 3. Any incoming e-mail tagged with an item number is copied to all the people on the item's nosy list, and any users found in the "From:", "To:", or "Cc:" fields are automatically added to the nosy list. Whenever a user edits an item's properties in the Web interface, they are also added to the nosy list. The effect is like each item having its own little mailing list, except that no one ever has to worry about subscribing to anything. Indicating interest in an issue is sufficient, and if you want to bring someone new into the conversation, all you need to do is "Cc:" a message to them. It turns out that no one ever has to worry about unsubscribing, either: the nosy lists are so specific in scope that the conversation tends to die down by itself when the issue is resolved or people no longer find it sufficiently important. Each nosy list is like an asynchronous chat room, lasting only a short time (typically five or ten messages) and involving a small group of people. However, that group is the *right* group of people: only those who express interest in an item in some way ever end up on the list, so no one gets spammed with mail they don't care about, and no one who *wants* to see mail about a particular item needs to be left out, for they can easily join in, and just as easily look at the mail spool on an item to catch up on any messages they might have missed. We can take this a step further and permit users to monitor particular keywords or classifications of items by allowing other kinds of items to also have their own nosy lists. For example, a manager could be on the nosy list of the priority value item for "critical", or a developer could be on the nosy list of the keyword value item for "security". The recipients are then determined by the union of the nosy lists on the item and all the items it links to. Using many small, specific mailing lists results in much more effective communication than one big list. Taking away the effort of subscribing and unsubscribing gives these lists the "feel" of being cheap and disposable. The transparent capture of the mail spool attached to each issue also yields a nice knowledge repository over time. Editing ------- Since Roundup is intended to support arbitrary user-defined schema for item properties, the editing interface must be automatically generated from the schema. The configuration for Roundup will include a template describing how to lay out the properties to present a UI for inspecting and editing items. For example:: Priority priority Status status To display the editing form for an item, Roundup inserts an HTML form widget where it encounters an expression like ``tal:content="structure context/priority/menu"``. Each type has its own appropriate editing widget: - *string* and *number* properties appear as text fields - *boolean* properties appear as a yes/no selection - *date* and *interval* properties appear as text fields - *link* properties appear as selection lists - *multilink* properties appear as multiple-selection lists or text fields with pop-up widgets for larger selections. We foresee the use of custom date fields for things like deadlines, so input fields for *date* properties support a simple way of specifying relative dates (such as "3w" for "three weeks from now"). The **superseder** property is a special case: although it is more efficient to store a **superseder** property in the superseded item, it makes more sense to provide a "supersedes" edit field on the superseding item. We use a special widget on items for this purpose (a text field containing a comma-separated list of items). Links in the **superseder** property appear on both the superseding and superseded items to facilitate navigating an item's pedigree. After the editing widgets, the item inspection page shows a "note" text box and then a display of the messages in the discussion spool. This field lets you enter a note explaining your change when you edit the item, and the note is included in the notification message that goes out to tell the interested parties on the nosy list of your edits. Browsing and Searching ---------------------- The ideal we would like to achieve is to make searching as much like browsing as possible: the user simply clicks about on things that seem interesting, and the information narrows down comfortably until the goal is in sight. This is preferable to trying to digest a screen filled with widgets and buttons or entering a search expression in some arcane algebraic syntax. While a one-shot search may be appropriate when you're looking for a single item and you know exactly what you want, it's not very helpful when you want an overview of things ("Gee, there are a lot more high-priority items than there were last week!") or trying to do comparisons ("I have some time today, so who is busiest and could most use some help?") The browsing interface presents filtering functionality for each of the properties in the schema. As with editing, the interface is generated from a template describing how to lay out the properties. Each type of property has its own appropriate filtering widget: - *string* properties appear as text fields supporting case-insensitive substring match - *date* properties appear as a text field which accepts a date range with start, end or both. Multiple date ranges can be specified separated by a comma. An empty date can be searched for by specifying '-' instead of a date range - *link* properties appear as a group of selectable options (the filter selects the *union* of the sets of items associated with the active options) - *multilink* properties appear as a group of selectable options (the filter selects the *intersection* of the sets of items associated with the active options) For a *multilink* property like **keyword**, one possibility is to show, as hyperlinks, the keywords whose sets have non-empty intersections with the currently displayed set of items. Sorting the keywords by popularity seems reasonable. Clicking on a keyword then narrows both the list of items and the list of keywords. This gives some of the feel of walking around a directory tree -- but without the restriction of having to select keywords in a particular hierarchical order, and without the need to travel all the way to the leaves of the tree before any items are visible. Below the filtering form is a listing of items, with their properties displayed in a table. Rows in the table are generated from a template, as with the editing interface. This listing is the central overview of the system, and it should aim to maximize the density of useful information in accordance with our guiding principle of *efficiency*. Colour may be used to indicate the status of each item to help the eye sift through the index quickly. Roundup sorts items in groups by priority, and then within groups by the date of last activity. This reveals at a glance where discussion is most active, and provides an easy way for anyone to move an issue up in the list. The page produced by a given set of browsing options constitutes an *index*. The options should all be part of the query parameters in the URL so that views may be bookmarked. An index specifies: - search strings for string properties - date ranges for date properties - acceptable values for choice properties - required values for reference properties - a sorting key - a grouping key - a list of properties for which to display filtering widgets Our default index is: - all **status** values except "resolved" - show **priority** and **fixer** - grouping by **priority** in sections - sorting by decreasing **activity** date The starting URL for Roundup immediately presents the listing of items generated by this default index, with no preceding query screen. code-001c16ac87ec/doc/postgresql.txt0000644000000000000000000001054615046233326015444 0ustar 00000000000000.. index:: postgres; deployment notes ========================== PostgreSQL/psycopg Backend ========================== This are notes about PostqreSQL backend based on the psycopg adapter for Roundup issue tracker. Prerequisites ============= To use PostgreSQL as backend for storing roundup data, you should additionally install: 1. PostgreSQL_ 8.x or higher 2. The psycopg_ python interface to PostgreSQL_ Note that you currently need at least version 2.8 of psycopg_ -- the postgresql backend will work with 2.7 but if you're using the native postgresql indexer you need at least 2.8. Also if you want to run the tests, these also need 2.8. If your distribution has an older version we suggest that you install into a python virtual environment. .. _psycopg: https://www.psycopg.org/ .. _PostgreSQL: https://www.postgresql.org/ Preparing the Database ====================== Roundup can use Postgres in one of two ways: 1. Roundup creates and uses a database 2. Roundup uses a pre-created database and creates and uses a schema under the database. In the examples below, replace ``roundupuser``, ``rounduppw`` and ``roundupdb`` with suitable values. This assumes that you are running Postgres on the same machine with Roundup. Using a remote database, setting up SSL/TLS and other authentication methods is beyond the scope of this documentation. However examples are welcome on the wiki or mailing list. Creating a Role/User -------------------- For case 1 (Roundup user creates and uses a database) create a user using:: psql -c "CREATE ROLE roundupuser WITH CREATEDB LOGIN PASSWORD 'rounduppw';" -U postgres After running ``roundup-admin init`` to create your databases, you can remove the CREATEDB permission using:: psql -c "ALTER ROLE roundupuser NOCREATEDB;" If needed (e.g. you want to deploy a new tracker) you can use ``ALTER ROLE`` with ``CREATEDB`` to add the permission back. For case 2 (Roundup user uses a schema under a pre-created database) you need to create the user:: psql -c "CREATE ROLE roundupuser LOGIN PASSWORD 'rounduppw';" -U postgres This psql command connects as the postgres database superuser. You may need to run this under sudo as the postgres user or provide a password to become an admin on the postgres db process. Creating a Database ------------------- For case 1, roundup will create the database on demand using the ``roundup_admin init`` command. So there is nothing to do here. For case 2, run:: psql -c "CREATE DATABASE roundupdb;GRANT CREATE ON DATABASE roundupdb TO roundupuser;" -U postgres This creates the database and allows the roundup user to create a new schema when running ``roundup_admin init``. Running the PostgreSQL unit tests ================================= The user that you're running the tests as will need to be able to access the postgresql database on the local machine and create and drop databases and schemas. See the config values in 'test/db_test_base.py' about which database connection, name and user will be used. At this time the following commands will setup the users and required databases:: sudo -u postgres psql -c "CREATE ROLE rounduptest WITH CREATEDB LOGIN PASSWORD 'rounduptest';" -U postgres sudo -u postgres psql -c "CREATE ROLE rounduptest_schema LOGIN PASSWORD 'rounduptest';" -U postgres sudo -u postgres psql -c "CREATE DATABASE rounduptest_schema;GRANT CREATE ON DATABASE rounduptest_schema TO rounduptest_schema;" -U postgres Note ``rounduptest`` and ``rounduptest_schema`` are well known accounts, so you should remove/disable the accounts after testing and set up a suitable production account. You need to remove any database owned by ``rounduptest`` first. To clean everything up, something like this should work:: sudo -u postgres psql -c "DROP DATABASE rounduptest;" -U postgres sudo -u postgres psql -c "DROP ROLE rounduptest;" -U postgres sudo -u postgres psql -c "DROP DATABASE rounduptest_schema;" -U postgres sudo -u postgres psql -c "DROP ROLE rounduptest_schema;" -U postgres If the ``rounduptest`` database is left in a broken state (e.g. because of a crash during testing) dropping the database and restarting the tests should fix it. If you have issues while running the schema test, you can drop the ``rounduptest` schema in the ``rounduptest_schema`` database. Credit ====== The postgresql backend was originally submitted by Federico Di Gregorio code-001c16ac87ec/doc/pydoc.txt0000644000000000000000000000040715046233326014352 0ustar 00000000000000================ Pydocs from code ================ .. contents:: :local: Client class ============ .. autoclass:: roundup.cgi.client::Client Templating Utils class ====================== .. autoclass:: roundup.cgi.templating::TemplatingUtils :members: code-001c16ac87ec/doc/reference.txt0000644000000000000000000046774115046233326015214 0ustar 00000000000000.. meta:: :description: Reference for the internals of Roundup. Includes background information for cookbook and how-to examples. Reference for the design and internals needed to understand and extend the examples to meet new needs. :tocdepth: 2 ================= Roundup Reference ================= .. admonition:: Welcome This document was part of the `customisation document`_. The customisation document was getting large and unwieldy. The combination of examples and internal information that made finding information difficult. Questions raised on the mailing list were well answered in the customisation document, but finding the info was difficult. The documentation is slowly being reorganized using the `Diataxis framework`_. Help with the reorganization is welcome. This document provides background for the tutorials or how-tos in the customisation document. .. _customisation document: customizing.html .. _diataxis framework: https://diataxis.fr/ .. This document borrows from the ZopeBook section on ZPT. The original was at: http://www.zope.org/Documentation/Books/ZopeBook/current/ZPT.stx .. contents:: :depth: 2 :local: Trackers in a Nutshell ====================== Trackers have the following structure: .. index:: single: tracker; structure db directory single: tracker; structure detectors directory single: tracker; structure extensions directory single: tracker; structure html directory single: tracker; structure html directory single: tracker; structure lib directory .. table:: :class: valign-top =================== ======================================================== Tracker File Description =================== ======================================================== config.ini Holds the basic `tracker configuration`_ schema.py Holds the `tracker schema`_ initial_data.py Loads initial data into the tracker (status, priority ...) when initializing the tracker (optional) interfaces.py Allows `modifying the core of Roundup`_ (optional) db/ Holds the tracker's database db/files/ Holds the tracker's uploaded files and message db/backend_name Names the database back-end for the tracker (obsolete). Use the ``backend`` setting in the ``[rdbms]`` section of ``config.ini`` instead. detectors/ `Auditors and reactors`_ for this tracker extensions/ Additional `actions`_ and `templating utilities`_ html/ Web interface templates, images and style sheets lib/ optional common imports for detectors and extensions =================== ======================================================== .. index:: config.ini .. index:: configuration; see config.ini Tracker Configuration ===================== The ``config.ini`` located in your tracker home contains the basic configuration for the web and e-mail components of Roundup's interfaces. The `tracker schema`_ defines the data captured by your tracker. It also defines the permissions used when accessing the data: see the `security / access controls`_ section. For example, you must grant the "Anonymous" Role the "Email Access" Permission to allow users to automatically register through the email interface,. .. index:: single: config.ini; sections see: configuration; config.ini The following is taken from the `Python Library Reference`__ (July 18, 2018) section "ConfigParser -- Configuration file parser": The configuration file consists of sections, led by a [section] header and followed by name: value entries, with continuations in the style of RFC 822 (see section 3.1.1, “LONG HEADER FIELDS”); name=value is also accepted. Note that leading whitespace is removed from values. The optional values can contain format strings which refer to other values in the same section, or values in a special DEFAULT section. Additional defaults can be provided on initialization and retrieval. Lines beginning with '#' or ';' are ignored and may be used to provide comments. For example:: [My Section] foodir = %(dir)s/whatever dir = frob would resolve the "%(dir)s" to the value of "dir" ("frob" in this case) resulting in "foodir" being "frob/whatever". The reference above discusses using the ``[DEFAULT]`` section and interpolation. For example:: [DEFAULT] local_admin_email = admin@example.com [main] admin_email = %(local_admin_email)s will set the admin_email setting. This works when running the tracker. When upgrading Roundup using ``updateconfig`` to create a new ``config.ini``, the ``DEFAULT`` section is not preserved and interpolation tokens (e.g. ``%(local_admin_email)s`` are replaced with their values (``admin@example.com``). This may be fixed in a future release of Roundup. Note that you can not reference settings in the ``DEFAULT`` section from Roundup. They are only useful when interpolated into a defined setting. __ https://docs.python.org/2/library/configparser.html A default ``config.ini`` file broken into sections is shown below. .. include:: tracker_config.txt Additional notes: The ``[rdbms]`` service defines the Connection Service for your PostgreSQL connection when using a system-wide pg_service.conf or ~/.pg_service.conf as discussed in https://www.postgresql.org/docs/current/libpq-pgservice.html. Setting this to the name of the service allows different trackers to connect to different services when running multiple trackers under one Roundup server. If you are only running one tracker, you can set the PGSERVICE environment variable. Note that other settings specified in this file (rdbms: user, password, port, host, (db)name) will override the corresponding connection service setting. .. index:: single: roundup-admin; config.ini update single: roundup-admin; config.ini create single: config.ini; create single: config.ini; update You may generate a new default config file using the ``roundup-admin genconfig`` command. You can generate a new config file merging in existing settings using the ``roundup-admin updateconfig`` command. Configuration variables may be referred to in lower or upper case. In code, refer to variables not in the "main" section using their section and name, so "domain" in the section "mail" becomes MAIL_DOMAIN. .. index:: pair: configuration; extensions pair: configuration; detectors Extending the configuration file -------------------------------- You can't add new variables to the config.ini file in the tracker home but you can add two new config.ini files: - a config.ini in the ``extensions`` directory is loaded and attached to the config variable as "ext". - a config.ini in the ``detectors`` directory is loaded and attached to the config variable as "detectors". These configuration files support the same operations as the main ``config.ini`` file. This included a ``DEFAULT`` section and interpolation. Note that you can not reference settings in the ``DEFAULT`` section from Roundup. They can only be used for interpolation. For example, the following in ``detectors/config.ini``:: [main] qa_recipients = email@example.com is accessible as:: db.config.detectors['QA_RECIPIENTS'] Note that the name grouping applied to the main configuration file is applied to the extension config files, so if you instead have:: [qa] recipients = email@example.com then the above ``db.config.detectors['QA_RECIPIENTS']`` will still work. Unlike values in the tracker's main ``config.ini``, the values defined in these config files are not validated. For example: a setting that is supposed to be an integer value (e.g. 4) could be the word "foo". If you are writing Python code that uses these settings, you should expect to handle invalid values. Also, incorrect values are discovered when the config setting is used not set. This can be long after the tracker is started and the error may not be seen in the logs. It's possible to validate these settings. Validation involves calling the ``update_options`` method on the configuration option. This can be done by the ``init()`` function in the Python files implementing extensions_ or detectors_. As an example, adding the following to an extension:: from roundup.configuration import SecretMandatoryOption def init(instance): instance.config.ext.update_option('RECAPTCHA_SECRET', SecretMandatoryOption,description="Secret securing reCaptcha.") similarly for a detector:: from roundup.configuration import MailAddressOption def init(db): try: db.config.detectors.update_option('QA_RECIPIENTS', MailAddressOption, description="Email used for QA comment followup.") except KeyError: # COMMENT_EMAIL setting is not found, but it's optional # so continue pass will allow reading the secret from a file or append the tracker domain to an email address if it does not have a domain. Running ``roundup-admin -i tracker_home display user1`` will validate the settings for both config.ini`s. Otherwise detector options are not validated until the first request to the web interface (or email gateway). ``update_option`` takes 4 arguments: 1. config setting name - string (positional, mandatory) 2. option type - Option derived class from configuration.py (positional, mandatory) 3. default value - string (optional, named default) 4. description - string (optional, named description) The first argument is the config setting name as described at the beginning of this section. The second argument is a class in the roundup.configuration module. There are many of these classes: BooleanOption, IntegerNumberOption, RegExpOption.... Please see the configuration module for all Option validators and their descriptions. You can also define your own custom validator in `interfaces.py`_. The third and fourth arguments are optional strings. They are printed when there is an error and may help the user correct the problem. .. index:: ! schema 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 ``schema.py`` module of your tracker. .. index:: schema; allowed changes What you can/can't 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 repercussions 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_. You must never: **Remove the user class** This class is the only *required* class in Roundup. **Remove the "username", "address", "password", "roles" 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* [1]_ 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. .. [1] If you shut down the tracker, `export the database`_, modify the exported csv property data to be compatible with the new type, change the property type in the schema, and finally import the changed exported data, you can change the property type. This is not trivial nor for the faint of heart. But it can be done. .. _export the database: admin_guide.html#using-roundup-admin The ``schema.py`` and ``initial_data.py`` modules ------------------------------------------------- The schema.py module is used to define 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. The initial_data.py module sets up the initial state of your tracker. It’s called exactly once - by the ``roundup-admin initialise`` command. See the start of the section on `database content`_ for more info about how this works. .. index:: schema; classic - description of The "classic" schema -------------------- The "classic" schema looks like this (see section `setkey(property)`_ below for the meaning of ``'setkey'`` -- you may also want to look into the sections `setlabelprop(property)`_ and `setorderprop(property)`_ for specifying (default) labelling and ordering of classes.):: 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(), alternate_addresses=String(), queries=Multilink('query'), roles=String(), timezone=String()) user.setkey("username") msg = FileClass(db, "msg", author=Link("user"), summary=String(), date=Date(), recipients=Multilink("user"), files=Multilink("file"), messageid=String(), inreplyto=String()) file = FileClass(db, "file", name=String()) issue = IssueClass(db, "issue", keyword=Multilink("keyword"), status=Link("status"), assignedto=Link("user"), priority=Link("priority")) issue.setkey('title') .. index:: schema; classes and properties Classes and Properties - creating a new information store --------------------------------------------------------- The tracker above, defines 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. It defines the "priority" and "status" classes to allow two things: 1. reduction in the amount of information stored on the issue 2. more powerful, accurate searching of issues by priority and status By requiring a link on the issue (stored as a single number) the chance that someone mis-types a priority or status - or makes a new one up is reduced. Class names access items of that class in the `REST api`_ interface. The classic tracker was created before the REST interface was added. It uses the single form (i.e. issue and user not issues and users) for its classes. Most REST documentation suggests using plural forms. However, to make your API consistent, use singular forms for classes that you add. .. index:: schema; classes schema; items 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*. .. index:: schema; property types Properties ~~~~~~~~~~ A Class consists of one or more properties of the following types: Boolean properties store on/off, yes/no, true/false values. Date properties store date-and-time stamps. Their values are Timestamp objects. Integer properties store integer values. (Number can store real/float values.) Interval properties store time periods rather than absolute dates. For example 2 hours. Link properties refers to a single item selected from a specified class. The class is part of the property; the value is an integer, the id of the chosen item. Multilink properties refer to one or more items in a specified class. The value is a list of integers. Number properties store numeric values. There is an option to use double-precision floating point numbers. Password properties store encoded arbitrary-length strings. The default encoding is defined in the ``roundup.password.Password`` class. String properties store arbitrary-length strings. Properties have attributes to change the default behaviour: .. index:: triple: schema; property attributes; required triple: schema; property attributes; default_value triple: schema; property attributes; quiet * All properties support the following attributes: - ``required``: see `design documentation`_. Adds the property to the list returned by calling get_required_props for the class. - ``default_value``: see `design documentation`_ Sets the default value if the property is not set. - ``quiet``: see `design documentation`_. Suppresses reporting user visible changes to this property. The property change is not reported: - in the change feedback/confirmation message in the web interface - the property change section of the nosy email - the web history at the bottom of an item's page This is useful when storing the state of the user interface (e.g. the names of elements that are collapsed or hidden from the user). Properties updates as an indirect result of a user's change (e.g. updating a blockers property, counting number of times an issue is reopened or reassigned etc.) should not be displayed to the user as they can be confusing. .. index:: triple: schema; property attributes; indexme * String properties have an ``indexme`` attribute. The default is 'no'. Setting it to 'yes' includes the property in the full text index. .. index:: triple: schema; property attributes; use_double * Number properties can have a ``use_double`` attribute that, when set to ``True``, will use double precision floating point in the database. * Link and Multilink properties can have several attributes: .. index:: triple: schema; property attributes; do_journal - ``do_journal``: By default, every change of a link property is recorded in the item being linked to (or being unlinked). A typical use-case for setting ``do_journal='no'`` would be to turn off journalling of nosy list, message author and message recipient link and unlink events to prevent the journal from clogged with these events. .. index:: triple: schema; property attributes; try_id_parsing - ``try_id_parsing`` is turned on by default. If a number is entered into a Link or Multilink field, Roundup interprets this number as an ID of the item to link to. Sometimes items can have numeric names (e.g., product codes). For these Roundup needs to match the numeric name and should never match an ID. In this case you can set ``try_id_parsing='no'``. .. index:: triple: schema; property attributes; rev_multilink - The ``rev_multilink`` option takes a property name to be inserted into the linked-to class. This property is a Multilink property that links back to the current class. The new Multilink is read-only (it is automatically modified if the Link or Multilink property defining it is modified). The new property can be used in normal searches using the "filter" method of the Class. This means it can be used like other Multilink properties when searching (in an index template) or via the REST and XMLRPC APIs. As a example, suppose you want to group multiple issues into a super issue. Each issue can be part of one super issue. It is inefficient to find all of the issues linked to the super issue by searching through all issues in the system looking at the part_of link property. To make this more efficient, you can declare an issue's part_of property as:: issue = IssueClass(db, "issue", ... part_of = Link("issue", rev_multilink="components"), ... ) This automatically creates the ``components`` multilink on the issue class. The ``components`` multilink is never explicitly declared in the issue class, but it has the same effect as though you had declared the class as:: issue = IssueClass(db, "issue", ... part_of = Link("issue"), components = Multilink("issue"), ... ) Then wrote a detector to update the components property on the corresponding issue. Writing this detector can be tricky. There is one other difference, you can not explicitly set/modify the ``components`` multilink. The effect of setting ``part_of = 3456`` on issue1234 automatically adds "1234" to the ``components`` property on issue3456. You can search the ``components`` multilink just like a regular multilink, but you can't explicitly assign to it. Another difference of reverse multilinks to normal multilinks is that when a linked node is retired, the node vanishes from the multilink. In the example above, when issue 1234 with ``part_of`` set to issue 5678 is retired, 1234 vanishes from the ``components`` multilink of issue 5678. You can also link between different classes. If the issue definition includes:: issue = IssueClass(db, "issue", ... assigned_to = Link("user", rev_multilink="responsibleFor"), ... ) This makes it easy to list all issues that the user is responsible for (aka assigned_to). .. index:: triple: schema; property attributes; msg_header_property - The ``msg_header_property`` is used by the mail gateway when sending out messages. When a link or multilink property of an issue changes, Roundup creates email headers of the form:: X-Roundup-issue-prop: value where ``value`` is the ``name`` property for the linked item(s). For example, if you have a multilink for attached_files in your issue, you will see a header:: X-Roundup-issue-attached_files: MySpecialFile.doc, HisResume.txt when the class for attached files is defined as:: file = FileClass(db, "file", name=String()) ``MySpecialFile.doc`` is the name for the file object. If you have an ``assigned_to`` property in your issue class that links to the user class and you want to add a header:: X-Roundup-issue-assigned_to: ... so that the mail recipients can filter emails where ``X-Roundup-issue-assigned_to: name`` contains their username. The user class is defined as:: user = Class(db, "user", username=String(), password=Password(), address=String(), realname=String(), phone=String(), organisation=String(), alternate_addresses=String(), queries=Multilink('query'), roles=String(), # comma-separated string of Role names timezone=String()) Because the user class does not have a ``name`` parameter, no header will be written. Setting:: assigned_to=Link("user", msg_header_property="username") will make the mail gateway generate an ``X-Roundup-issue-assigned_to`` using the username property of the linked user. Assume assigned_to for an issue is linked to the user with username=joe_user, setting:: msg_header_property="username" for the assigned_to property will generated message headers of the form:: X-Roundup-issue-assigned_to: joe_user for emails sent on issues where joe_user has been assigned to the issue. If this property is set to the empty string "", no header will be generated on outgoing mail. .. index:: triple: schema; class property; creator triple: schema; class property; creation triple: schema; class property; actor triple: schema; class property; activity All Classes automatically have four properties by default: *creator* Link to the user that created the item. *creation* Date the item was created. *actor* Link to the user that last modified the item. *activity* Date the item was last modified. .. index:: double: schema; class methods Methods ~~~~~~~ All classes have the following methods. .. index:: triple: schema; class method; setkey setkey(property) :::::::::::::::: .. index:: roundup-admin; setting assignedto on an issue Set the key property of a class to a string property. The key property must be unique. References to the items in the class can be done by the content of the key property. For example, you can refer to users by their username. 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 use:: 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. .. index:: triple: schema; class method; setlabelprop setlabelprop(property) :::::::::::::::::::::: Select a property of the class to be the label property. The label property is used whenever an item should be uniquely identified, e.g., when displaying a link to an item. If setlabelprop is not specified for a class, the following values are tried for the label: * the key of the class (see the `setkey(property)`_ section above) * the "name" property * the "title" property * the first property from the sorted property name list In most cases you can get away without specifying setlabelprop explicitly. Users should have View access to this property or the id property for a class. If the property can not be viewed by a user, looping over items in the class (e.g. messages attached to an issue) will not work. .. index:: triple: schema; class method; setorderprop setorderprop(property) :::::::::::::::::::::: Select a property of the class to be the order property. The order property is used whenever using a default sort order for the class, e.g., when grouping or sorting class A by a link to class B in the user interface, the order property of class B is used for sorting. If setorderprop is not specified for a class, the following values are tried for the order property: * the property named "order" * the label property (see `setlabelprop(property)`_ above) Usually you can get away without specifying setorderprop explicitly. .. index:: triple: schema; class method; create create(information) ::::::::::::::::::: Create an item in the database. This is used to create items in the :term:`definitional class` like "priority" and "status". .. index:: triple: schema; class property; messages triple: schema; class property; files triple: schema; class property; nosy triple: schema; class property; superseder IssueClass ~~~~~~~~~~ IssueClass automatically includes 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 to tell about 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. It is better described in the `original document `_. They also have the default "creation", "activity" and "creator" properties. The value of the "creation" property is the date when an item was created. 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. .. index:: triple: schema; class property; content triple: schema; class property; type 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 makes databases more efficient. Also web servers, image processing applications, and command line tools can operate on the files. The content is stored in the ``files`` sub-directory of the ``'db'`` directory in your tracker. FileClasses also have a "type" attribute to store the file's MIME type. Roundup, by default, considers the contents of the file immutable. This assists in maintaining an accurate record of correspondence. The distributed tracker templates do not enforce this. If you have access to the Roundup tracker directory, you can edit the files (make sure to preserve mode, owner and group) to remove information. You may need to do this if somebody includes a password or you need to redact proprietary information. The journal for the message/file won't report that the file has changed. Best practice is to remove offending material and leave a placeholder. E.G. replace a password with the text:: [password has been deleted 2020-12-02 --myname] If you need to delete an entire file, replace the file contents with:: [file contents deleted due to spam 2020-10-21 --myname] rather than deleting the file. If you actually delete the file Roundup will report an error to the user and email the administrator. If you empty the file, a user downloading the file using the direct URL (e.g. ``tracker/msg22``) may be confused and think something is broken when they receive an empty file. Retiring a file/msg does not prevent access to the file using the direct URL. Retiring an item only removes it when requesting a list of all items in the class. If you are replacing the contents, you probably want to change the content type of the file. E.G. from ``image/jpeg`` to ``text/plain``. You can do this easily through the web interface, or using the ``roundup-admin`` command line interface. You can also change the contents of a file or message using the REST interface. Note that this will NOT result in an entry in the journal, so again it allows a silent change. To do this you need to make two rest requests. An example using curl is:: $ curl -u demo:demo -s -H "X-requested-with: rest" \ -H "Referer: https://tracker.example.com/demo/" \ -X GET \ https://tracker.example.com/demo/rest/data/file/30/content { "data": { "id": "30", "type": "", "link": "https://tracker.example.com/demo/rest/data/file/30/content", "data": "hello3", "@etag": "\"3f2f8063dbce5b6bd43567e6f4f3c671\"" } } using the etag, overwrite the content with:: $ curl -u demo:demo -s -H "X-requested-with: rest" \ -H "Referer: https://tracker.example.com/demo/" \ -H 'If-Match: "3f2f8063dbce5b6bd43567e6f4f3c671"' \ -X PUT \ -F "data=@hello" \ https://tracker.example.com/demo/rest/data/file/30/content where ``hello`` is a file on local disk. You can enforce immutability in your tracker by adding an auditor (see detectors_) for the file/msg class that rejects changes to the content property. The auditor could also add a journal entry so that a change via the Roundup mechanism is reported. Using a mixin (see: https://wiki.roundup-tracker.org/MixinClassFileClass) to augment the file class allows for other possibilities including: * signing the file, * recording a checksum in the database and validating the file contents at the time it gets read. This allows detection of changes done on the filesystem outside of the Roundup mechanism. * keeping multiple revisions of the file. .. index:: schema; item ordering A note about ordering ~~~~~~~~~~~~~~~~~~~~~ When we sort items in the hyperdb, we use one of three methods, depending on the property type: 1. String, Integer, Number, Date or Interval property, sort the scalar value of the property. Strings sort case-sensitively. 2. a Link property, sort by either the linked item's "order" property (if it has one) or the linked item's "id". 3. Mulitlinks sort similar to #2, starting with the first Multilink list item, and if they are the same, sort by the second item, and so on. Note that if an "order" property is defined for a class, all items of that Class *must* have a value for the "order" property, or sorting will result in random ordering. Examples of adding to your schema --------------------------------- See :ref:`CustomExamples` for examples. The Roundup wiki CategorySchema`_ provides a list of additional examples of how to customize schemas to add new functionality. .. _Roundup wiki CategorySchema: https://wiki.roundup-tracker.org/CategorySchema .. index:: !detectors .. _detectors: .. _Auditors and reactors: Schema Integrity ---------------- There is a table in all SQL based schemas called ``schema``. It contains a representation of the current schema and the current Roundup schema version. Roundup will exit if the version is not supported by the release. E.G. Roundup 2.1.0 will not work with a database created by 2.3.0 as db version 8 used by 2.3.0 is not supported by 2.1.0. The current schema representation is automatically updated whenever a change is made to the schema via ``schema.py``. The schema version is upgraded when running ``roundup-admin migrate`` although it can be upgraded automatically in some cases by run a Roundup process (mailgw, web interface). This information is kept in one large blob in the table. To view this in a more understandable format, you can use the commands below (requires the jq command): Postgres .. code:: psql -tq -d 'roundup_db' -U roundup_user -c \ 'select schema from schema;' | \ python3 -c 'import json, sys; d = eval(sys.stdin.read()); \ print(json.dumps(d, indent=2));' | jq . | less replace ``roundup_db``, ``roundup_user`` with the values from ``config.ini`` and use a ``~/.pgpass`` file or type the database password when prompted. SQLite .. code:: sqlite3 demo/db/db 'select schema from schema;' | \ python3 -c 'import json, sys; d = eval(sys.stdin.read()); \ print(json.dumps(d, indent=2));' | jq . | less Something similar for MySQL can be generated as well. Replacing ``jq .`` with ``jq .version`` will display the schema version. Detectors - adding behaviour to your tracker ============================================ Detectors are Python modules that sit in your tracker's ``detectors`` directory. You are free to add and remove them any time, even after the database is initialised via the ``roundup-admin initialise`` command. Detectors in your tracker are run *before* (**auditors**) and *after* (**reactors**) changes to the contents of your database. 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: .. index:: detectors; installed **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 are 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 .. index:: detectors; writing api Detector API ------------ .. index:: pair: detectors; auditors single: auditors; function signature single: auditors; defining single: auditors; arguments 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 the initial property values that will be used to create the item 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. .. index:: pair: detectors; reactor single: reactors; function signature single: reactors; defining single: reactors; arguments 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. .. index:: detectors; additional 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: **irker.py** This detector sends notification on IRC through an irker daemon (http://www.catb.org/esr/irker/) when issues are created or messages are added. To use it you need to install irker, start the irkerd daemon, and add an ``[irker]`` section in ``detectors/config.ini`` that contains a comma-separated list of channels where the messages should be sent, e.g. ``channels = irc://chat.freenode.net/channelname``. **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** When the status is set to "resolved" this auditor checks the user performing the action. If the user is not the creator, it sets 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, 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 lengthy explanation. .. index:: auditors; rules for use single: reactors; rules for use Auditor or Reactor? ------------------- Generally speaking, you should observe the following rules: **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, use:: raise Reject('Description of error') Error messages raised with ``Reject`` automatically have any HTML content escaped before being displayed to the user. To display an error message to the user without performing any HTML escaping the ``RejectRaw`` should be used. All security implications should be carefully considering before using ``RejectRaw``. Generating email from Roundup ----------------------------- The module ``roundup.mailer`` contains most of the nuts-n-bolts required to generate email messages from Roundup. Also, the ``IssueClass`` methods ``nosymessage()`` and ``send_message()`` generate nosy messages, and may generate messages which only consist of a change note (i.e. the message id parameter is not required - this is referred to as a "System Message" because it comes from "the system" and not a user). .. index:: extensions .. index:: extensions; add python functions to tracker .. _extensions: .. _actions: Extensions - adding capabilities to your tracker ================================================ While detectors_ add new behavior by reacting to changes in tracked objects, `extensions` add new actions and utilities to Roundup, which are mostly used to enhance the web interface. You can create an extension by creating Python file in your tracker ``extensions`` directory. The tracker loads all the files from this directory, at which point it calls ``init(instance)`` from each file supplying itself as a first argument. Note that at this point web interface is not loaded, but extensions still can register actions for it in the tracker instance. This may be fixed in Roundup 1.6 by introducing ``init_web(client)`` callback or a more flexible extension point mechanism. * ``instance.registerUtil`` is used for adding `templating utilities`_ (see `adding a time log to your issues `_ for an example) * ``instance.registerUtilMethod`` is also used for adding `templating utilities`_, and provides a TemplatingUtils instance by default to the function. This makes more complex templating actions easier to use. (see :ref:`dynamic_csp` for an example) * ``instance.registerAction`` is used to add more actions to the instance and to web interface. See `Defining new web actions`_ for details. Generic action can be added by inheriting from ``action.Action`` instead of ``cgi.action.Action``. .. _interfaces.py: .. _modifying the core of Roundup: .. index:: single: interfaces.py; hooking into the roundup core interfaces.py - hooking into the core of Roundup ================================================ There is a magic trick for hooking into the core of Roundup. Using this you can: * modify class data structures * monkey patch core code to add new functionality * modify the email gateway * add new rest endpoints * enable experimental or future features but with great power comes great responsibility. Interfaces.py has existed since the earliest releases of Roundup and was the main way to get a lot of customisation done. In modern Roundup, the extensions_ mechanism is used to `add actions <#defining-new-web-actions>`_ and `templating utilities`_. But there are places where interfaces.py is still useful. Note that the tracker directories are not on the Python system path when interfaces.py is evaluated. You need to add library directories explicitly by modifying sys.path. Interfaces.py allows you to interact with any part of Roundup's internals. These internals are not as stable as defined interfaces (e.g. extensions. detectors, schema). So the code in interfaces.py is more likely to need modification when upgrading from version to version. While the developers attempt to keep the examples working, it may make more sense to change the internals to make the code clearer, add more features etc. See `Changing How the Core Code Works `_ for examples of using interfaces.py. Database Content ================ .. note:: If you modify the content of a :term:`definitional class`, you will need to edit the tracker `detectors`_ if they reference a value of a definitional class. (E.g. if a detector checks to see if an issue has a status of "open", and you change the "open" definition to be "working", you need to change the check.) Customisation of the special :term:`definitional classes ` (e.g. 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 initial_data.py module in your tracker to alter the items created 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. For each Class defined in the tracker schema, the following permissions are defined: - Create (everything) - Edit (everything) - Search (everything) - (used if View does not permit access) - Retire (everything) - Restore (everything) - View (everything) All of these are assigned to the "Admin" Role by default for every class. They allow a user to do anything. The web and email interfaces also define: Email Access If defined, the user may use the email interface. Used by default to deny Anonymous users access to the email interface. When granted to the Anonymous user, they will be automatically registered by the email interface (see also the ``new_email_user_roles`` configuration option). Web Access If defined, the user may use the web interface. This is assigned to the Anonymous role to allow authorized users to access the form based login. If your tracker uses some other authorization mode (basic auth, Single Sign On (SSO), etc.) Web Access can be removed from the Anonymous user. Web Roles Controls user access to editing the "roles" property of the "user" class. TODO: deprecate in favour of a property-based control. Rest Access |br| Xmlrpc Access These control access to the Rest and Xmlrpc endpoints. The Admin and User roles have these by default in the classic tracker. See the `directions in the rest interface documentation`_ and the `xmlrpc interface documentation`_. Register This enables automatic user registration by email or web. It is assigned to the anonymous user. These are assigned into the default Roles: - Admin (Create, Edit, Retire, Restore, Search, View for everything; Web Roles) - User (Web Access; Email Access) - Anonymous (Web Access) Finally, the "admin" user gets the "Admin" Role, and the "anonymous" user gets the "Anonymous" Role. The "Admin" and "Anonymous" roles are created when the tracker is initialized. For the "User" Role, the "classic" tracker defines: - Create, Edit and View issue, file, msg, query, keyword - View priority, status - View user (limited properties) - View their own user record - Edit their own user record - Search queries And the "Anonymous" Role has the following permissions: - Web interface access - Register user (for registration) - View issue, file, msg, query, keyword, priority, status Put together, these settings appear in the tracker's ``schema.py`` file:: # # TRACKER SECURITY SETTINGS # # See the configuration and customisation document for information # about security setup. # # REGULAR USERS # # Give the regular users access to the web and email interface db.security.addPermissionToRole('User', 'Web Access') db.security.addPermissionToRole('User', 'Email Access') db.security.addPermissionToRole('User', 'Rest Access') db.security.addPermissionToRole('User', 'Xmlrpc Access') # Assign the access and edit Permissions for issue, file and message # to regular users now for cl in 'issue', 'file', 'msg', 'keyword': db.security.addPermissionToRole('User', 'View', cl) db.security.addPermissionToRole('User', 'Edit', cl) db.security.addPermissionToRole('User', 'Create', cl) for cl in 'priority', 'status': db.security.addPermissionToRole('User', 'View', cl) # May users view other user information? Comment these lines out # if you don't want them to p = db.security.addPermission(name='View', klass='user', properties=('id', 'organisation', 'phone', 'realname', 'timezone', 'username')) db.security.addPermissionToRole('User', p) # Users should be able to edit their own details -- this permission is # limited to only the situation where the Viewed or Edited item is their own. def own_record(db, userid, itemid, **ctx): '''Determine whether the userid matches the item being accessed.''' return userid == itemid p = db.security.addPermission(name='View', klass='user', check=own_record, description="User is allowed to view their own user details") db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Edit', klass='user', check=own_record, properties=('username', 'password', 'address', 'realname', 'phone', 'organisation', 'alternate_addresses', 'queries', 'timezone'), description="User is allowed to edit their own user details") db.security.addPermissionToRole('User', p) # Users should be able to edit and view their own queries. They should also # be able to view any marked as not private. They should not be able to # edit others' queries, even if they're not private def view_query(db, userid, itemid): private_for = db.query.get(itemid, 'private_for') if not private_for: return True return userid == private_for def edit_query(db, userid, itemid): return userid == db.query.get(itemid, 'creator') p = db.security.addPermission(name='View', klass='query', check=view_query, description="User is allowed to view their own and public queries") db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Search', klass='query') db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Edit', klass='query', check=edit_query, description="User is allowed to edit their queries") db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Retire', klass='query', check=edit_query, description="User is allowed to retire their queries") db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Restore', klass='query', check=edit_query, description="User is allowed to restore their queries") db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Create', klass='query', description="User is allowed to create queries") db.security.addPermissionToRole('User', p) # # ANONYMOUS USER PERMISSIONS # # Let anonymous users access the web interface. Note that almost all # trackers will need this Permission. The only situation where it's not # required is in a tracker that uses an HTTP Basic Authenticated front-end. db.security.addPermissionToRole('Anonymous', 'Web Access') # Let anonymous users access the email interface (note that this implies # that they will be registered automatically, hence they will need the # "Create" user Permission below) # This is disabled by default to stop spam from auto-registering users on # public trackers. #db.security.addPermissionToRole('Anonymous', 'Email Access') # Assign the appropriate permissions to the anonymous user's Anonymous # Role. Choices here are: # - Allow anonymous users to register db.security.addPermissionToRole('Anonymous', 'Register', 'user') # Allow anonymous users access to view issues (and the related, linked # information) for cl in 'issue', 'file', 'msg', 'keyword', 'priority', 'status': db.security.addPermissionToRole('Anonymous', 'View', cl) # Allow the anonymous user to use the "Show Unassigned" search. # It acts like "Show Open" if this permission is not available. # If you are running a tracker that does not allow read access for # anonymous, you should remove this entry as it can be used to perform # a username guessing attack against a roundup install. p = db.security.addPermission(name='Search', klass='user') db.security.addPermissionToRole ('Anonymous', p) # [OPTIONAL] # Allow anonymous users access to create or edit "issue" items (and the # related file and message items) #for cl in 'issue', 'file', 'msg': # db.security.addPermissionToRole('Anonymous', 'Create', cl) # db.security.addPermissionToRole('Anonymous', 'Edit', cl) .. index:: single: roundup-admin; view class permissions You can use ``roundup-admin security`` to verify the permissions defined in the schema. It also verifies that properties specified in permissions are valid for the class. This helps detect typos that can cause baffling permission issues. Automatic Permission Checks --------------------------- Permissions are automatically checked when rendering information through the web. This includes: 1. View checks for properties when rendered via the ``plain()`` or similar methods. If the check fails, the text "[hidden]" is displayed. 2. Edit checks for properties when the edit field is rendered via the ``field()`` or similar methods. If the check fails, the property is rendered via the ``plain()`` method (see point 1. for subsequent checking performed) 3. View checks are performed in index pages for each item being displayed such that if the user does not have permission, the row is not rendered. 4. View checks are performed at the top of item pages for the Item being displayed. If the user does not have permission, the text "You are not allowed to view this page." is displayed. 5. View checks are performed at the top of index pages for the Class being displayed. If the user does not have permission, the text "You are not allowed to view this page." is displayed. New User Roles -------------- New users are assigned the Roles defined in the config file as: - NEW_WEB_USER_ROLES - NEW_EMAIL_USER_ROLES The `users may only edit their issues `_ example shows customisation of these parameters. 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 need to: 1. create it in your tracker's ``schema.py`` using ``security.addPermission``. For example:: db.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. check it in the relevant HTML interface templates 4. check it in the appropriate hasPermission methods in your tracker's extensions/detectors/interfaces.py modules The ``addPermission`` method takes a four optional parameters: **check** A function to be executed which returns boolean determining whether the Permission is allowed. If it returns True, the permission is allowed, if it returns False the permission is denied. The function can have one of two signatures:: check(db, userid, itemid) or:: check(db, userid, itemid, **ctx) where ``db`` is a handle on the open database, ``userid`` is the user attempting access and ``itemid`` is the specific item being accessed. If the second form is used the ``ctx`` dictionary is defined with the following values:: ctx['property'] the name of the property being checked or None if it's a class check. ctx['classname'] the name of the class that is being checked (issue, query ....). ctx['permission'] the name of the permission (e.g. View, Edit...). The second form is preferred as it makes it easier to implement more complex permission schemes. An `example in upgrading.html `_ shows the use of ``ctx``. Note that the check option is not supported for the Search permission. When searching there is no item defined, so a check function does not make any sense. **filter** This optional function returns parameters for the ``filter`` method when getting ``Class`` items (users, issues etc.) from the database. It filters items at the database level (using SQL where possible). This pre-filters the number of items returned from the database when displaying results in an ``index`` template. This filtering is usually faster than calling a ``check`` method (see previous argument) on *each individual result*. The ``filter`` method has the signature:: filter(db, userid, klass) where ``db`` is the database handle, ``userid`` is the user attempting access and ``klass`` is the ``Class`` in the schema. The ``filter`` function must return a *list* of dictionaries of parameters of the `Class.filter `_ call. This includes filterspec, retired and exact_match_specs. Note that sort and group parameters of the filter call should not be set by filter method (they will be overwritten) and the parameter search_matches must not be set. The query executed by an index template is modified by the parameters computed by the ``filter`` function. An empty list of filter parameters (``[]``) indicates no access. When using a filter, a check function is still needed to test each individual item for visibility. When the filter function is defined but a check function is not defined, a check function is manufactured automatically from the ``filter`` function. Note that the filter option is not supported for the Search permission. Since the filter function is called *after* the search was already performed a filter function does not make any sense. An example ``filter`` function for the ``view_query`` check function in the query checks above would look like:: def filter_query(db, userid, klass): return [{'filterspec': { 'private_for': ['-1', userid] }}] This would be called by the framework for all queries found when displaying queries. It filters for all queries where the ``private_for`` field is the userid or empty. This matches the definition of the ``view_query`` function above where permission is granted if the ``private_for`` field indicates the query is owned by the user, or the ``private_for`` field is empty indicating that the query is public. If we want to modify the check to also allow acess if the user is the ``creator`` of a query we would change the filter function to:: def filter_query(db, userid, klass): f1 = {'filterspec': {'private_for': ['-1', userid]}} f2 = {'filterspec': {'creator': userid}} return [f1, f2] This is an example where we need multiple filter calls to model an "or" condition, the user has access if either the ``private_for`` check passes *or* the user is the creator of the query. Consider an example where we have a class structure where both the ``issue`` class and the ``user`` class include a reference to an ``organization`` class. Users are permitted to view only those issues that are associated with their respective organizations. A check function or this could look like:: def view_issue(db, userid, itemid): user = db.user.getnode(userid) if not user.organisation: return False issue = db.issue.getnode(itemid) if user.organisation == issue.organisation: return True The corresponding ``filter`` function:: def filter_issue(db, userid, klass): user = db.user.getnode(userid) if not user.organisation: return [] return [{'filterspec': { 'organisation': user.organisation }}] This filters for all issues where the organisation is the same as the organisation of the user. Note how the filter fails early returning an empty list (meaning "no access") if the user happens to not have an organisation. **properties** A sequence of property names that are the only properties to apply the new Permission to (eg. ``... klass='user', properties=('name', 'email') ...``) **props_only** A boolean value (set to false by default) that is a new feature in Roundup 1.6. A permission defined using: ``properties=('list', 'of', 'property', 'names')`` determines access for things other than just those properties. For example a check for View permission on the issue class or an issue item can use any View permission for the issue class even if that permission has a property list. This makes sense if you understand that a user can't access the properties of a class if they can't access the class. The ability to access class properties implies class access. This eliminates the need to create a duplicate View permission without properties to allow access to the View properties permission. Even though it makes sense, it can be confusing and surprising. You would think that a permission including properties would be used only for determining the access permission when checking properties. But that is not the case. Setting ``props_only=True`` will prevent the permission from being used unless the check include properties. If you use a lot of permissions with property checks, it can be difficult to change all of them. Calling the function: db.security.set_props_only_default(True) at the top of ``schema.py`` will make every permission creation behave as though props_only is True. Note that you may need to add new View permissions without properties to allow property only checks to take effect. ``roundup-admin security`` will report invalid properties for the class. For example a permission with an invalid summary property is presented as:: Allowed to see content of object regardless of spam status (View for "file": ('content', 'summary') only) **Invalid properties for file: ['summary'] Example Scenarios ~~~~~~~~~~~~~~~~~ See the `examples `_ section for longer examples of customisation. **anonymous access through the e-mail gateway** Give the "anonymous" user the "Email Access", ("Edit", "issue") and ("Create", "msg") Permissions but do not not give them the ("Create", "user") Permission. 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 ("Create", "user") Permission, 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*. **automatic registration of users in the e-mail gateway** By giving the "anonymous" user the ("Register", "user") Permission, 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). By default new Roundup trackers don't enable "Email Access" for "anonymous" as it opens them up to spam. It may be enabled by uncommenting the appropriate addPermissionToRole in your tracker's ``schema.py`` file. The new user is given the Roles list defined in the "new_email_user_roles" config variable. **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 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, Roundup determines which tracker is accessed (the first part of the URL path inside the scope of the CGI handler) and pass control on to the :py:class:`roundup.cgi.client.Client` class - 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 changing links, 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) the URL to redirect to is the first argument of the exception. - 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 Roundup URL design ------------------ Each tracker has several hardcoded URLs. These three are equivalent and lead to the main tracker page: 1. ``/`` 2. ``/index`` 3. ``/home`` The following prefix accesses static resources: 4. ``/@@file/`` Two url's are used for the API's. The `REST api`_ is accessed via: 5. ``/rest/`` .. _`REST api`: rest.html and the `XMLRPC api`_ is available at: 6. ``/xmlrpc`` .. _`XMLRPC api`: xmlrpc.html All other URLs depend on the classes configured in Roundup database. Each class receives two URLs - one for the class itself and another for specific items of that class. Example for class URL: 7. ``/issue`` Shows a listings of class items, usually in a table. The URL for for specific object of issue class with id 1 will look like: 8. ``/issue1`` .. _strip_zeros: Note that Roundup strips a leading string of 0's from the id part of the object :term:`designator` in the URL. E.G. ``/issue001`` is the same as ``/issue1``. Similarly for ``/file01`` etc. However you should generate URL's without the extra zeros. Determining web context ----------------------- To determine the "context" of a request (what request is for), Roundup looks at the URL path after the tracker root and at ``@template`` request parameter. Typical URL paths look like: 1. ``/tracker/`` 2. ``/tracker/issue`` 3. ``/tracker/issue1`` 4. ``/tracker/@@file/style.css`` 5. ``/cgi-bin/roundup.cgi/tracker/file1`` 6. ``/cgi-bin/roundup.cgi/tracker/file1/kitten.png`` where tracker root is ``/tracker/`` or ``/cgi-bin/roundup.cgi/tracker/`` We're looking at "issue", "issue1", "@@file/style.css", "file1" and "file1/kitten.png" in the cases above. 1. with no path Roundup is in the "home" context. See `the "home" context`_ below for details. "index" or "home" paths may also be used to switch into "home" context. 2. if there is something in the path (as in example 2, "issue"), it identifies the tracker class to display. 3. if the path is an item designator (as in examples 3 and 5, "issue1" and "file1"), then we're to display a specific item. :ref:`Note. ` 4. for paths starting with "@@file" the additional path entry ("style.css" in the example above) specifies the static file to be served from the tracker TEMPLATES directory (or STATIC_FILES, if configured). The TEMPLATES directory is usually the tracker's "html" directory. Internally this works by raising SendStaticFile exception. 5. A file can have additional path components (as in example 6). Without the additional components, the metadata for the file is displayed. 6. 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. Neither 4. or 6. use templates and stop before the template is determined. For other contexts the template used is specified by the ``@template`` variable, which defaults to: - only classname supplied: "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 (e.g. 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. These files are served without any permission checks. Any user on the internet with the url can download the file. This is rarely an issue since the html templates are just source code and much of it can be found in the Roundup repository. Other decoration (logos, stylesheets) are similarly not security sensitive. You can use the static_files setting in config.ini to eliminate access to the templates directory if desired. If a file resolves to a symbolic link, it is not served. 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. Also you can set the ``__redirect_to`` form variable to the URL to display after the edit is successfully completed. If you wanted to edit a sequence of issues, users etc. this could be used to display the next item in the sequence to the user. **new** Add a new item to the database. You may use the same `special form variables`_ as in the "edit" action. Also you can set the ``__redirect_to`` form variable to the URL to display after the new item is created. This is useful if you want to create another item rather than edit the newly created item. **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 are 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``. 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 for each action are: **login** Determine whether the user has the "Web Access" Permission. **logout** No permission checks are made. **register** Determine whether the user has the ("Create", "user") Permission. **edit** Determine whether the user has permission to edit this item. 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 this item. No additional property checks are made. Additionally, new user items may be created if the user has the ("Create", "user") Permission. **editCSV** Determine whether the user has permission to edit this class. **search** Determine whether the user has permission to view this class. Protecting users from web application attacks --------------------------------------------- There is a class of attacks known as Cross Site Request Forgeries (CSRF). Malicious code running in the browser can making a request to Roundup while you are logged into Roundup. The malicious code piggy backs on your existing Roundup session to make changes without your knowledge. Roundup 1.6 has support for defending against this by analyzing the * Referer, * Origin, and * Host or * X-Forwarded-Host HTTP headers. It compares the headers to the value of the web setting in the [tracker] section of the tracker's ``config.ini``. Also a per form token (also called a nonce) can be enabled for the tracker using the ``csrf_enforce_token`` option in config.ini. When enabled, Roundup will check a hidden form field called ``@csrf``. If the field's value matches a token in the database, the validation passes and the token is deleted. If the validation fails because the token is not found (e.g. if the token is used more than once) the request is rejected. The ``@csrf`` input field is added automatically when calling the ``submit`` function/path. It can also be added manually by calling anti_csrf_nonce() directly. For example:: By default a nonce lifetime is 2 weeks. However the lifetime (in minutes) can be set by passing a lifetime argument as shown above. The example above makes the nonce lifetime 10 minutes. Search for @csrf in this document for more examples. More examples and information is provided in ``upgrading.txt``. The token protects you because malicious code supplied by another site is unable to obtain the token. Thus any attempt they make to submit a request is rejected. The protection on the xmlrpc interface is untested, but is based on a valid header check against the Roundup URL and the presence of the ``X-REQUESTED-WITH`` header. Work to improve this is a future project after the 1.6 release. The enforcement levels can be modified in ``config.ini``. Refer to that file for details. 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. - Redirect to a different page after creating a new item (new action only, not edit action). Usually you end up on the page for the created item. - Set up user interface locale. These operations will only take place if the form action (the ``@action`` variable) is "edit" or "new". In the following, values are variable, "@" may be either ":" or "@", and other text "required" is fixed. .. index:: single: i18n; set from web interface single: internationalization; set from web interface single: language; set from web interface Two special form variables are used to specify user language preferences: ``@language`` value may be locale name or ``none``. If this variable is set to locale name, web interface language is changed to given value (if the appropriate translation is available). The value is stored in a browser cookie and is used for all following requests. If value is ``none`` the cookie is removed and the language is changed to the tracker default, set up in the tracker configuration or OS environment. ``@charset`` value may be character set name or ``none``. Character set name is stored in a browser cookie and sets output encoding for all HTML pages generated by Roundup. If value is ``none`` the cookie is removed and HTML output is reset to Roundup internal encoding (UTF-8). This is unlikely to be needed with modern web browsers and is left over from the early days of the web. It will be removed at some future date. 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 check 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 (i.e. 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 (or id number) for 'klass', where the key field is specified in schema.py. For a Multilink('klass') property, the form value is a comma-separated list of keys (or id nummber) for 'klass', where the key field is specified in schema.py. Note that for simple-form-variables specifying 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 defined for the class). Otherwise, the property is set to the form value. For Date(), Interval(), Boolean(), Integer() and Number() properties, the form value is converted to the appropriate value. Any of the form variables may be prefixed with a classname or designator. Setting the form variable: ``__redirect_to=`` to a url when ``@action=new`` redirects the user to the specified url after successfully creating the new item. This is useful if you want the user to create another item rather than edit the newly created item. Note that the url assigned to ``__redirect_to`` must be url encoded/quoted and be under the tracker's base url. If the base_url uses http, you can set the url to https. Two special form values are supported for backwards compatibility: @note This is equivalent to:: @link@messages=msg-1 msg-1@content=value which is equivalent to the html:: 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 by adding the HTML:: The String content value is handled as described above for file uploads. If both the "@note" and "@file" form variables are specified, the action:: msg-1@link@files=file-1 is also performed. This would be expressed in HTML with:: 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. Support for xhtml is due to be phased out so leave the ``html_version`` configuration variable in ``config.ini`` as ``'html'`` instead of ``'xhtml'``. 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 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. This page also defines macros for use in search pages. * th_label - defines a label for a search field * search_input - defines a text input field * search_date - defines a text input field with popup calendar link * search_popup - defines a text input with popup classhelper link * search_select - defines a select/dropdown element for selecting a single item from a class * search_select_keywords - defines a dropdown with a keyword search expression builder link * search_select_translated - like search_Select but it translates the items in the dropdown * search_multiselect - text input with multiselect classhelper popup link * search_checkboxes - display selection items as checkbox items * column_input - a checkbox element used to select an element for display in a search result (sets the @columns property) * sort_input - a radiobutton element used to select sorting * group_input - a radiobutton element used to select grouping and the user.item.html page: * user_src_input - takes a long name and splits it into parts (first/last) * user_normal_input - takes a name without splitting it for reuse * user_pw_input - a password input for the user * user_confirm_input - a password input marked so the back end confirms it against the password submitted through the user_pw_input **home.html** the default page displayed when in `the "home" context`_ and no other page is requested using the ``@template`` parameter **home.classlist.html** a special version of the default page that lists the classes in the tracker. It is requested in the "home" context using ``@template=classlist`` **classname.item.html** displays an item of the *classname* class given a :term:`designator` **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 when there is no ``*classname*.index`` available **_generic.help.html** used to display a "class help" page when there is no ``*classname*.help`` **user.register.html** a special page just for the user class, that renders the registration page **style.css** a static file that is served up as-is The *classic* template has a number of additional templates. 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.html" template to "issue.test" (or "issue.test.html"), 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. You can also put templates into a subdirectory of the template directory. So if you specify:: http://your.tracker.example/tracker/issue?@template=test/item you will use the template at: ``test/issue.item.html``. If that template doesn't exit it will try to use ``test/_generic.item.html``. If that template doesn't exist it will return an error. Implementing Modal Editing Using @template ------------------------------------------ Many item templates allow you to edit the item. They contain code that renders edit boxes if the user has edit permissions. Otherwise the template will just display the item information. However, you may want a modal edit. A modal edit requires the user to take some action (click a button or follow a link) to shift from display mode to edit mode. Submitting the changes ends edit mode and the user returns to display mode. To build a modal edit for an item, move the (editable) issue.item.html template to issue.item_edit.html. Then create a new issue.item.html template that only displays information. Add an edit link that calls the display url, but adds ``@template=item_edit`` to the link. This will now display the edit page. On the edit page you want to add a hidden text field to your form named ``@template`` with the value: ``item|item_edit``. When the form is submitted, it is validated. If the form is correct the user will see the item rendered using the item template. If there is an error (validation failed) the item will be rendered using the ``item_edit`` template. The rendered ``item_edit`` template will display all the changes that the user made to the form before it was submitted. The user can correct the error and resubmit the changes until the form validates. If the form failed to validate but the ``@template`` field had the value ``item`` the user would still see the error, but all of the data the user entered would be discarded. The user would have to redo all the edits again. In general, modal workflows are not implemented by the default templates because they slow down the edit cycle. For some specific workflows a modal edit is useful. For example, a batch edit mode allows the user to edit multiple issues in one form. It can result in a modal workflow of: * search for issues to modify * switch to edit mode and change values * exit back to the results of the search How the templates work ---------------------- Templating engines ~~~~~~~~~~~~~~~~~~ Since version 1.4.20 Roundup supports two templating engines: * the original `Template Attribute Language`_ (TAL) engine from Zope * the standalone Chameleon templating engine. Chameleon is intended as a replacement for the original TAL engine, and supports the same syntax, but they are not 100% compatible. The major (and most likely the only) incompatibility is the default expression type of ``python:`` instead of ``path:``. See also "Incompatibilities and differences" section of `Chameleon documentation`__. Version 1.5.0 added support for the `jinja2`_ templating language. You must install the `jinja2`_ module to use it. The ``jinja2`` template supplied with Roundup has the templates rewritten to use ``jinja2`` rather than TAL. A number of trackers are running using ``jinja2`` templating so it is less experimental than Chameleon templating. .. _jinja2: https://palletsprojects.com/projects/jinja/ **NOTE1**: For historical reasons, examples given below assumes path expression as default expression type. With Chameleon you have to manually resolve the path expressions. A Chameleon-based, z3c.pt, that is fully compatible with the old TAL implementation, is planned for a future release. **NOTE2**: As of 1.4.20 Chameleon support is highly experimental and **not** recommended for production use. .. _Chameleon: https://pypi.org/project/Chameleon/ .. _z3c.pt: https://pypi.org/project/z3c.pt/ __ https://chameleon.readthedocs.io/en/latest/reference.html?highlight=differences#incompatibilities-and-differences .. _TAL: .. _Template Attribute Language: https://pagetemplates.readthedocs.io/en/latest/history/TALSpecification14.html 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 local variable for this tag and its contents. For example:: In this example, the variable "title" is defined by the expression "request/description". The "tal:content" command inside the tag may then use the "title" variable. **tal:condition="expression"** 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 displayed only 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 example would iterate over the sequence of users returned by "user/list" and define the local variable "u" for each entry. Using the repeat command creates a new variable called "repeat" which you may access to gather information about the iteration. See the section below on `the repeat variable`_. **tal:replace="expression"** Replace this tag with the result of the expression. For example:: The example would replace the tag and its contents with the user's id. If the user's id was "3" the resulting output would be "3". You need to be a little careful with ``tal:replace``. Unlike ``tal:content``, it doesn't always escape the output. For example if you used:: it would replace the contents with the value of the user's realname. The realname is something the user can control. The user could include something like:: Bruce This would result in an alert box popping up when the page was loaded. Attackers could use this `XSS exploit`_ for malicious purposes. Generally you would use tal:replace when calling a utility function using a :ref:`Python expression ` that generates trusted HTML. If you are inserting untrusted content, it is better to use ``tal:content`` with tags that disappear as described below. .. _`XSS exploit`: https://owasp.org/www-community/attacks/xss/ **tal:content="expression"** Replace the contents of this tag (but not the tag itself) with the result of the expression. For example:: user's name appears here This example would replace the contents of the ```` tag with the user's realname. If the user's realname was "Bruce" then the output will be ``Bruce``. ``tal:content`` replaces special HTML claracters like ``<`` with an HTML entitity ``<``. This makes it safer to use when inserting untrusted data. To have ``tal:content`` insert unescaped HTML, you need to use the `structure modifier`_. If the tag is an unknown ``tal:`` tag, TAL removes the tag. So evaulating: results in ``Bruce``. **tal:attributes="attribute expression; attribute expression; ..."** Set attributes on this tag to the results of expressions. For example:: My Details In the example, the "href" attribute of the ```` tag is set to the value of the expression "string:user${request/user/id}", which will look like "user123". **tal:omit-tag="expression"** Remove this tag (but not its contents) if the expression is true. For example:: Hello, world! would result in output of:: Hello, world! Note that TAL evaluates the commands on a given tag in the order above. *define* is evaluated before *condition*, and so on. Additionally, you may include tags such as , which are removed from output. Its content is kept, but the tag itself is not (so don't go using any "tal:attributes" commands on it). This is useful for making arbitrary blocks of HTML conditional or repeatable (very handy for repeating multiple table rows, which would otherwise require an illegal tag placement to effect the repeat). Templating Expressions ~~~~~~~~~~~~~~~~~~~~~~ Templating Expressions are covered by `Template Attribute Language Expression Syntax`_ (TALES). The expressions you use in attribute values may be one of the following forms: **Path Expressions** - e.g. ``item/status/checklist`` These are object attribute / item accesses. Roughly speaking, the path ``item/status/checklist`` is broken into parts ``item``, ``status`` and ``checklist``. The ``item`` part is the root of the expression. It then looks for a ``status`` attribute on ``item``, or failing that, a ``status`` item (as in ``item['status']``). If that fails, the path expression fails. When we get to the end, the object we're left with is evaluated to get a string - if it is a method, it is called; if it is an object, it is stringified. Path expressions may have an optional ``path:`` prefix, but path is the default expression type for TAL. In Chameleon you must include the ``path:`` prefix. If an element in the path may not exist, you can use the ``|`` operator in the expression to provide an alternative. The expression ``request/form/foo/value | default`` would simply leave the current HTML in place if the "foo" form variable doesn't exist. If an expression evaluates to ``default``, then the expression is "cancelled" - whatever HTML already exists in the template will remain (tag content in the case of ``tal:content``, attributes in the case of ``tal:attributes``). If an expression evaluates to ``nothing`` then the target of the expression is removed (tag content in the case of ``tal:content``, attributes in the case of ``tal:attributes`` and the tag itself in the case of ``tal:replace``). You may use the python function ``path``, as in ``path("item/status")``, to embed path expressions in Python expressions. **String Expressions** - e.g. ``string:hello ${user/name}`` These expressions are string interpolations - though they can be just plain strings with no interpolation if you want. The expression in the interpolation decorator ``${ ... }`` is a path expression as above. .. _`python expression`: **Python Expressions** - e.g. ``python: 1+1`` These expressions give the full power of Python. All the "root level" variables are available, so ``python:item.status.checklist()`` is the same as ``item/status/checklist``, assuming that ``checklist`` is a method. Modifiers: .. _`structure modifier`: **structure** - e.g. ``structure python:msg.content.plain(hyperlink=1)`` The result of expressions are *escaped* to be safe for HTML display (all "<", ">" and "&" are replaced with entities (e.g. ``<``). The ``structure`` expression modifier turns off this escaping - the result of the expression is now assumed to be HTML, which is passed to the web browser for rendering. **not:** - eg. ``not:python:1=1`` This inverts the logical true/false value of another expression. .. _TALES: .. _Template Attribute Language Expression Syntax: https://pagetemplates.readthedocs.io/en/latest/history/TALESSpecification13.html Template Macros ~~~~~~~~~~~~~~~ Roundup uses macros to save us from repeating the same common page structures over and over. The most common (and probably only) macro you'll use is the "icing" macro defined in the "page" template. Macros are generated and used inside your templates using special attributes similar to the `basic templating actions`_. In this case, though, the attributes belong to the `Macro Expansion Template Attribute Language`_, (METAL). The macro commands are: **metal:define-macro="macro name"** Define that the tag and its contents are now a macro that may be inserted into other templates using the *use-macro* command. For example:: ... defines a macro called "page" using the ```` tag and its contents. Once defined, macros are stored in the ``macros`` attribute of the template they are defined on. You can access them later on through the ``templates`` variable. Use the path expression ``templates/page/macros/icing`` to access the "icing" macro defined in the "page.html" template. **metal:use-macro="path expression"** Use a macro, identified by the path expression. This replaces the current tag with the identified macro contents. For example:: ... will replace the tag and its contents with the "icing" macro from the "page" template. **metal:define-slot="slot name"** and **metal:fill-slot="slot name"** To define *dynamic* parts of the macro, you define "slots" which are filled when the macro is used with a *use-macro* command. For example, the ``templates/page/macros/icing`` macro defines a ``head_title`` slot like so:: title goes here In your *use-macro* command, you may now use a *fill-slot* command like this:: My Title where the tag that fills the slot completely replaces the one defined as the slot in the macro. Note that you may not mix `METAL`_ and `TAL`_ commands on the same tag. But TAL commands can be used freely inside METAL-using tags (so your *fill-slots* tags may have all manner of TAL inside them). .. _METAL: .. _Macro Expansion Template Attribute Language: https://pagetemplates.readthedocs.io/en/latest/history/TALESSpecification13.html Information available to templates ---------------------------------- This is implemented by ``roundup.cgi.templating.RoundupPageTemplate``. Documentation in the installed file ``roundup/cgi/templating.py`` supplements this documentation. The following variables are available to templates. **context** The current context. This is either None, a `hyperdb class wrapper`_ or a `hyperdb item wrapper`_ **request** Includes information about the current request, including: - the current index information (``filterspec``, ``filter`` arguments, ``properties``, etc) parsed out of the form. - methods for filterspec link generation (indexargs_url) - "form" The current CGI form information as a mapping of form argument name to value (specifically a cgi.FieldStorage) - "env" the CGI environment variables - "base" the base URL of this instance - "user" a HTMLItem instance for the current user - "language" as determined by the browser or configuration - "classname" the current classname (possibly None) - "template" the current template (e.g. for the ``issue.item.html`` template the template would be the ``item`` suffix on the classname. It can also be the empty string (e.g. with the ``home.html`` template). **config** This variable holds all the values defined in the tracker config.ini file (e.g. TRACKER_NAME, etc.) **db** The current database, used to access arbitrary database items. **templates** Access to all the tracker templates by name. Used mainly in *use-macro* commands. **utils** This variable makes available some utility functions like batching. **nothing** This is a special variable - if an expression evaluates to this, then the tag (when used with ``tal:replace``), its contents (in the case of ``tal:content``) or some attributes (when used with ``tal:attributes``) will not appear in the output. For example:: Hello, World! would result in:: Hello, World! **default** Also a special variable - if an expression evaluates to this, then the existing HTML in the template will not be replaced or removed, it will remain. So:: Hello, World! would result in:: Hello, World! and:: H when ``nope`` is not defined results in:: H **true**, **false** Boolean constants that may be used in `templating expressions`_ instead of ``python:1`` and ``python:0``. **i18n** Internationalization service, providing two string translation methods: **gettext** (*message*) Return the localized translation of message **ngettext** (*singular*, *plural*, *number*) Like ``gettext()``, but consider plural forms. If a translation is found, apply the plural formula to *number*, and return the resulting message (some languages have more than two plural forms). If no translation is found, return singular if *number* is 1; return plural otherwise. The context variable ~~~~~~~~~~~~~~~~~~~~ The *context* variable can contain one of three things based on the current context (see `determining web context`_ for how Roundup figures this out). If Roundup is: 1. at a "home" page, then it's None 2. at a specific hyperdb class, it's a `hyperdb class wrapper`_. 3. at a specific hyperdb item, it's a `hyperdb item wrapper`_. If the context is not None, you can access the properties of the class or item. The only real difference between cases 2 and 3 are: 1. the properties may have a real value behind them, and this will appear if the property is displayed through ``context/property`` or ``context/property/field``. 2. the context's "id" property will be a false value in case 2, but a real, or true value in case 3. Thus we can determine whether we're looking at a real item from the hyperdb by testing "context/id". Hyperdb class wrapper ::::::::::::::::::::: This is implemented by the ``roundup.cgi.templating.HTMLClass`` class. This wrapper object provides access to a hyperdb class. It is used primarily in both index view and new item views, but it is usable anywhere else that you wish to access information about a class, or the items of a class, when you don't have a specific item of that class in mind. We allow access to properties. There will be no "id" property. The value accessed through the property will be the current value of the same name from the CGI form. There are several methods available on these wrapper objects: .. table:: :class: valign-top =========== ============================================================= Method Description =========== ============================================================= properties return a `hyperdb property wrapper`_ for all of this class's properties that are searchable by the user. You can use the argument cansearch=False to get all properties. list lists all of the active (not retired) items in the class. csv return the items of this class as a chunk of CSV text. propnames lists the names of the properties of this class. filter lists of items from this class, filtered and sorted. Two options are available for sorting: 1. by the current *request* filterspec/filter/sort/group args 2. by the "filterspec", "sort" and "group" keyword args. "filterspec" is ``{propname: value(s)}``. "sort" and "group" are an optionally empty list ``[(dir, prop)]`` where dir is '+', '-' or None and prop is a prop name or None. The propname in filterspec and prop in a sort/group spec may be transitive, i.e., it may contain properties of the form link.link.link.name. e.g. All issues with a priority of "1" with messages added in the last week, sorted by activity date: ``issue.filter(filterspec={"priority": "1", 'messages.creation' : '.-1w;'}, sort=[('activity', '+')])`` Note that when searching for Link and Multilink values, the special value '-1' searches for empty Link or Multilink values. For both Links and Multilinks, multiple values given in a filter call are combined with 'OR' by default. Both Link and Multilinks support a postfix expression syntax using negative ID numbers (as strings) as operators. Each non-negative number (or '-1') is pushed on an operand stack. A negative number pops the required number of arguments from the stack, applies the operator, and pushes the result. The following operators are supported: - '-2' stands for 'NOT' and takes one argument - '-3' stands for 'AND' and takes two arguments - '-4' stands for 'OR' and takes two arguments Note that this special handling of ID arguments is applied only when a negative number smaller than -1 is encountered as an ID in the filter call. Otherwise the implicit OR default applies. Examples of using Multilink expressions would be - '1', '2', '-4', '3', '4', '-4', '-3' would search for IDs (1 or 2) and (3 or 4) - '-1' '-2' would search for all non-empty Multilinks - The URL fragment ``filter=assignedto&assignedto=-1,-2`` would find all issues that are assigned (where the assignedto field is not empty). Note that 'NOT', (``-2``) is the only useful operand for links. By default, a multi-value search uses 'OR', so '-4' is redundant. Since a link only has a single value, the 'AND' operand will return an empty result. filter_sql **Only in SQL backends** Lists the items that match the SQL provided. The SQL is a complete "select" statement. The SQL select must include the item id as the first column. This function **does not** filter out retired items, add on a where clause "__retired__ <> 1" if you don't want retired nodes. classhelp display a link to a JavaScript popup containing this class' "help" template. This generates a link to a popup window which displays the properties indicated by "properties" of the class named by "classname". The "properties" should be a comma-separated list (e.g. 'id,name,description'). Properties defaults to all the properties of a class (excluding id, creator, created and activity). You may optionally override the "label" displayed, the "width", the "height", the number of items per page ("pagesize") and the field on which the list is sorted ("sort"). With the "filter" arg it is possible to specify a filter for which items are supposed to be displayed. It has to be of the format "=;=;...". The popup window is resizable and scrollable. If the "property" arg is given, it's passed through to the JavaScript help_window function. This allows updating of a property in the calling HTML page. "property" is optional. If not provided, the resulting window will be read only. This is useful for Link properties where selection can be done by drop-down, but descriptions of the values can be seen in the popup. Note that some tracker templates may generate an error if the property is missing. Version 2.4.0 of Roundup fixed these templates. If the "form" arg is given, it's passed through to the JavaScript help_window function - it's the name of the form the "property" belongs to. submit generate a submit button (and action and @csrf hidden elements) renderWith render this class with the given template. history returns 'New node - no history' :) is_edit_ok is the user allowed to Edit the current class? is_view_ok is the user allowed to View the current class? =========== ============================================================= Note that if you have a property of the same name as one of the above methods, you'll need to access it using a python "item access" expression. For example:: python:context['list'] will access the "list" property, rather than the list method. Hyperdb item wrapper :::::::::::::::::::: This is implemented by the ``roundup.cgi.templating.HTMLItem`` class. This wrapper object provides access to a hyperdb item. We allow access to properties. There will be no "id" property. The value accessed through the property will be the current value of the same name from the CGI form. There are several methods available on these wrapper objects: .. table:: :class: valign-top =============== ======================================================== Method Description =============== ======================================================== submit generate a submit button (and action and @csrf hidden elements) journal return the journal of the current item (**not implemented**) history render the journal of the current item as HTML. By default properties marked as "quiet" (see `design documentation`_) are not shown unless the function is called with the ``showall=True`` parameter. Properties that are not Viewable to the user are not shown. renderQueryForm specific to the "query" class - render the search form for the query hasPermission specific to the "user" class - determine whether the user has a Permission. The signature is:: hasPermission(self, permission, [classname=], [property=], [itemid=]) where the classname defaults to the current context. hasRole specific to the "user" class - determine whether the user has a Role. The signature is:: hasRole(self, rolename) is_edit_ok is the user allowed to Edit the current item? is_view_ok is the user allowed to View the current item? is_retired is the item retired? download_url generate a url-quoted link for download of FileClass item contents (ie. file/) copy_url generate a url-quoted link for creating a copy of this item. By default, the copy will acquire all properties of the current item except for ``messages`` and ``files``. This can be overridden by passing ``exclude`` argument which contains a list (or any iterable) of property names that shall not be copied. Database-driven properties like ``id`` or ``activity`` cannot be copied. =============== ======================================================== Note that if you have a property of the same name as one of the above methods, you'll need to access it using a python "item access" expression. For example:: python:context['journal'] will access the "journal" property, rather than the journal method. Hyperdb property wrapper :::::::::::::::::::::::: This is implemented by subclasses of the ``roundup.cgi.templating.HTMLProperty`` class (``HTMLStringProperty``, ``HTMLNumberProperty``, and so on). This wrapper object provides access to a single property of a class. Its value may be either: 1. if accessed through a `hyperdb item wrapper`_, then it is a value from the hyperdb 2. if access through a `hyperdb class wrapper`_, then it is a value from the CGI form The property wrapper has some useful attributes: .. table:: :class: valign-top =============== ======================================================== Attribute Description =============== ======================================================== _name the name of the property _value the value of the property if any - this is the actual value retrieved from the hyperdb for this property =============== ======================================================== There are several methods available on these wrapper objects: .. table:: :class: valign-top =========== ================================================================ Method Description =========== ================================================================ plain render a "plain" representation of the property. This method may take two arguments: escape If true, escape the text so it is HTML safe (default: no). The reason this defaults to off is that text is usually escaped at a later stage by the TAL commands, unless the "structure" option is used in the template. The following ``tal:content`` expressions are all equivalent:: "structure python:msg.content.plain(escape=1)" "python:msg.content.plain()" "msg/content/plain" "msg/content" Usually you'll only want to use the escape option in a complex expression. hyperlink If true, turn URLs, email addresses and hyperdb item designators in the text into hyperlinks (default: no). Note that you'll need to use the "structure" TAL option if you want to use this ``tal:content`` expression:: "structure python:msg.content.plain(hyperlink=1)" The text is automatically HTML-escaped before the hyperlinking transformation done in the plain() method. hyperlinked The same as msg.content.plain(hyperlink=1), but nicer:: "structure msg/content/hyperlinked" wrapped Wraps long lines on the nearest whitespace. Like plain(), it takes ``escape`` and ``hyperlink`` arguments. However, the defaults are to enable both escape and hyperlinks. It also takes a ``columns`` argument set by default to 80. field render an appropriate form edit field for the property - for most types this is a text entry box, but for Booleans it is a tri-state yes/no/neither selection. This method may take some arguments: display_time (Date properties only) By default this uses the display_time paramter of the Date property (which by default is True) and displays date and time for Date properties. You can set this to False for displaying only the date. form (Date properties only) When using a popup calendar (see popcal below) and the enclosing form name is different from "itemSynopsis", the form name must be specified for the field. format (Date properties only) Sets the format of the date in the field - uses the same format string argument as supplied to the ``pretty`` method below. If you use this, it will prevent the use of browser native date inputs. It is useful if you want partial dates. For example using ``format="%Y-%m"`` with ``type="text"`` will display a text edit box with the year and month part of your date. labelfirst (Boolean properties only) place the labels before the radio buttons popcal (Date properties only) Include a link to the JavaScript-based popup calendar for date selection. Defaults to off/False when browser native dates are in use and on/True otherwise because browser native dates support a date popup on most browsers. size (default 30) Sets the width in characters of the edit field type (depends on property type) Sets the type property of the input. To change a date property field from a native date input to a text input you would use ``type="text"``. For Date properties the type cannot be set by the user and is enforced via the configuration (if browser native date input should be used). y_label, n_label, u_label (Boolean properties only) Set the labels for the true/false/undefined states. If u_label is defined, it produces a tri-state radio button selector. Otherwise, it allows selection of true/yes or false/no only. Other arguments are added as properties directly on the input tag. For example:: field(size=30, id='myid', required=None) produces:: Note that using ``None`` as the value results in an attribute without a value. This is useful for boolean properties like ``required``. rst only on String properties - render the value of the property as ReStructuredText (requires the :ref:`Docutils module to be installed separately`). stext only on String properties - render the value of the property as StructuredText (requires the StructureText module to be installed separately) (deprecated, to be removed use rst or markdown instead). markdown only on String properties - render the value of the property as Markdown (requires a :ref:`Markdown module to be installed separately`). multiline only on String properties - render a multiline form edit field for the property email only on String properties - render the value of the property as an obscured email address url_quote only on String properties. It quotes any characters in the string so it is safe to use in a url. E.G. a space is replaced with %20. confirm only on Password properties - render a second form edit field for the property, used for confirmation that the user typed the password correctly. Generates a field with name "name:confirm". now only on Date properties - return the current date as a new property reldate only on Date properties - render the interval between the date and now local only on Date properties - return this date as a new property with some timezone offset, for example:: python:context.creation.local(10) will render the date with a +10 hour offset. pretty Date properties - render the date as "dd Mon YYYY" (eg. "19 Mar 2004"). Takes an optional format argument, for example:: python:context.activity.pretty('%Y-%m-%d') Will format as "2004-03-19" instead. Interval properties - render the interval in a pretty format (e.g. "yesterday"). The format arguments are those used in the standard ``strftime`` call (see the `Python Library Reference: time module`__) Number properties - takes a printf style format argument (default: '%0.3f') and formats the number accordingly. If the value can't be converted, '' is returned if the value is ``None`` otherwise it is converted to a string. popcal This is deprecated with Roundup 2.5 which either uses the native HTML5 date input or can generate a date popup with the popcal option of the ``field`` method. The native date input includes a calendar popup on modern broswers. Generate a link to a popup calendar which may be used to edit the date field, for example:: you still need to include the ``field`` for the property, so typically you'd have:: Since the ``field`` by default already produces a popup calendar this use is deprecated. menu only on Link and Multilink properties - render a form select list for this property. Takes a number of optional arguments size is used to limit the length of the list labels height is used to set the File   submit button will go here When a change is submitted, the system automatically generates a message describing the changed properties. As shown in the example, the editor template can use the "@note" and "@file" fields, which are added to the standard changenote message generated by Roundup. Form values ::::::::::: We have a number of ways to pull properties out of the form in order to meet the various needs of: 1. editing the current item (perhaps an issue item) 2. editing information related to the current item (e.g. messages or attached files) 3. creating new information to be linked to the current item (e.g. time spent on an issue) In the following, ```` values are variable, ":" may be one of ":" or "@", and other text ("required") is fixed. Properties are specified as form variables: ```` property on the current context item ``:`` property on the indicated item (for editing related information) ``-:`` property on the Nth new item of classname (generally for creating new items to attach to the current item) Once we have determined the "propname", check to see if it is one of the special form values: ``@required`` The named property values must be supplied or a ValueError will be raised. ``@remove@=id(s)`` The ids will be removed from the multilink property. ``:add:=id(s)`` The ids will be added to the multilink property. ``:link:=`` Used to add a link to new items created during edit. These are collected and returned in ``all_links``. This will result in an additional linking operation (either Link set or Multilink append) after the edit/create is done using ``all_props`` in ``_editnodes``. The on the current item will be set/appended the id of the newly created item of class (where must be -). Any of the form variables may be prefixed with a classname or designator. Two special form values are supported for backwards compatibility: ``:note`` create a message (with content, author and date), linked to the context item. This is ALWAYS designated "msg-1". ``:file`` create a file, attached to the current item and any message created by :note. This is ALWAYS designated "file-1". Spool Section ~~~~~~~~~~~~~ The spool section lists related information like the messages and files of an issue. TODO History Section ~~~~~~~~~~~~~~~ The final section displayed is the history of the item - its database journal. This is generally generated with the template:: or:: if you want to show history entries for quiet properties. *To be done:* *The actual history entries of the item may be accessed for manual templating through the "journal" method of the item*:: a journal entry *where each journal entry is an HTMLJournalEntry.* Defining new web actions ------------------------ You may define new actions triggered by the ``@action`` form variable. These defined in the tracker's ``extensions`` directory and registered using ``instance.registerAction``. All the pre-existing Actions are defined in ``roundup.cgi.actions``. Adding action classes takes three steps; first you `define the new action class`_, then you `register the action class`_ with the cgi interface so it can be triggered by the ``@action`` form variable. Finally you `use the new action`_ in your HTML form. See `setting up a "wizard" (or "druid") for controlled adding of issues `_ for an example. Define the new action class ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Create a new action class in your tracker's ``extensions`` directory, for example ``myaction.py``:: from roundup.cgi.actions import Action class MyAction(Action): def handle(self): ''' Perform some action. No return value is required. ''' The *self.client* attribute is an instance of ``roundup.cgi.client.Client``. See the :class:`docstring of that class ` for details of what it can do. The method will typically check the ``self.form`` variable's contents. It may then: - add information to ``self.client._ok_message`` or ``self.client._error_message`` (by using ``self.client.add_ok_message`` or ``self.client.add_error_message``, respectively) - change the ``self.client.template`` variable to alter what the user will see next - raise Unauthorised, SendStaticFile, SendFile, NotFound or Redirect exceptions (import them from roundup.cgi.exceptions) Register the action class ~~~~~~~~~~~~~~~~~~~~~~~~~~ The class is now written, but isn't available to the user until you register it with the following code appended to your ``myaction.py`` file:: def init(instance): instance.registerAction('myaction', myActionClass) This maps the action name "myaction" to the action class we defined. Use the new action ~~~~~~~~~~~~~~~~~~ In your HTML form, add a hidden form element like so:: where "myaction" is the name you registered in the previous step. Actions may return content to the user ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Actions generally perform some database manipulation and then pass control on to the rendering of a template in the current context (see `Determining web context`_ for how that works.) Some actions will want to generate the actual content returned to the user. Action methods may return their own content string to be displayed to the user, overriding the templating step. In this situation, we assume that the content is HTML by default. You may override the content type indicated to the user by calling ``setHeader``:: self.client.setHeader('Content-Type', 'text/csv') This example indicates that the value sent back to the user is actually comma-separated value content (i.e. something to load into a spreadsheet or database). CSS for the web interface ------------------------- The web interface can be completely redesigned by the admin, However some parts of Roundup use classes or set attributes that can be selected by css to change the look of the element. The ``datecopy.js`` module used to allow editing a date value with a text input assigns the ``mode_textdate`` class to the input when it is in text mode. The class is removed when it is not in text mode. 8-bit character set support in Web interface -------------------------------------------- The web interface uses UTF-8 default. It may be overridden in both forms and a browser cookie. In general, the UTF-8 standard should work with all modern browsers. You shouldn't have to make any modifications from this section. - In forms, use the ``@charset`` variable. - To use the cookie override, have the ``roundup_charset`` cookie set. In both cases, the value is a valid charset name (eg. ``utf-8`` or ``kio8-r``). Inside Roundup, all strings are stored and processed in utf-8. Unfortunately, some older browsers do not work properly with utf-8-encoded pages (e.g. Netscape Navigator 4 displays wrong characters in form fields). Roundup allows one to change the character set for http transfers. To do so, you may add the following code to your ``page.html`` template:: utf-8 koi8-r (substitute ``koi8-r`` with appropriate charset for your language). Charset preference is kept in the browser cookie ``roundup_charset``. ``meta http-equiv`` lines added to the tracker templates in version 0.6.0 should be changed to include actual character set name:: The charset is also sent in the http header. Debugging Trackers ================== There are three switches in tracker configs that turn on debugging in Roundup: 1. web :: debug 2. mail :: debug 3. logging :: level See the config.ini file or the `tracker configuration`_ section for more information. Additionally, the ``roundup-server.py`` script has its own debugging mode in which it reloads edited templates immediately when they are changed, rather than requiring a web server restart. .. _`design documentation`: design.html .. _change the rate limiting method: rest.html#creating-custom-rate-limits .. _`directions in the rest interface documentation`: rest.html#enabling-the-rest-api .. _`xmlrpc interface documentation`: xmlrpc.html#through-roundup .. allow line breaks in term definitions. .. |br| raw:: html
code-001c16ac87ec/doc/requirements.pip0000644000000000000000000000001415046233326015722 0ustar 00000000000000sphinx-tabs code-001c16ac87ec/doc/rest.txt0000644000000000000000000026164515046233326014226 0ustar 00000000000000.. meta:: :description: Documentation on the RESTful interface to the Roundup Issue Tracker. Enable REST access, endpoints, methods, authentication, discovery. .. index:: pair: api; Representational state transfer pair: api; rest ==================== REST API for Roundup ==================== .. contents:: :local: :depth: 3 Introduction ============ After the 1.6.0 Release, a REST-API developed in 2015 during a Google Summer of Code (GSOC) by Chau Nguyen, supervised by Ezio Melotti was integrated. The code was updated by Ralf Schlatterbeck and John Rouillard to address some limitations and incorporate essential features for a single page web application, such as etag support, pagination, and field embedding, among others. Enabling the REST API ===================== The REST API can be disabled in the ``[web]`` section of ``config.ini`` via the variable ``enable_rest`` which is ``yes`` by default. Users have to be authorized to use the rest api. The user must have "Rest Access" permission. To add this to the "User" role change schema.py to add:: db.security.addPermissionToRole('User', 'Rest Access') This is usually included near where other permissions like "Web Access" or "Email Access" are assigned. You could also create a new role "rest" and assign the "Rest Access" permission to that role and then just add the "rest" role to those users who should have access. The REST api is reached via the ``/rest/`` endpoint of the tracker URL. Partial URLs paths below (not starting with https) will have /rest removed for brevity. Make sure that the ``secret_key`` option is defined in the ``[web]`` section of your tracker's ``config.ini``. Following the `upgrading directions`_ using ``roundup-admin ... updateconfig ...`` will generate the ``secret_key`` comments and setting. Then you can merge this into your ``config.ini``. If you are installing a new tracker with ``roundup-admin ... install`` the ``secret_key`` value is automatically set to some random value. If ``secret_key`` is not set, the etag value returned by a REST call will changed on every call even though the item has not changed. This means users will be unable to submit changes using the rest interface. (Note, if you run roundup in a persistent mode: server, wsgi, mod_python, the etag will change on every restart if not explicitly set.) .. _upgrading directions: upgrading.html Preventing CSRF Attacks ----------------------- Clients should set the header ``X-REQUESTED-WITH`` to any value and the tracker's config.ini should have ``csrf_enforce_header_x-requested-with = yes`` or ``required``. If you want to allow Roundup's api to be accessed by an application that is not hosted at the same origin as Roundup, you must permit the origin using the ``allowed_api_origins`` setting in ``config.ini``. If you access the REST interface with a method other than ``GET``, you must also supply an origin header with a value that is either the default origin (the URL of the tracker without the path component set in the config file as ``web`` in section ``[tracker]``) or one that is permitted by ``allowed_api_origins``. Rate Limiting API Failed Logins ------------------------------- To make brute force password guessing harder, the REST API has an invalid login rate limiter. This feature restricts the number of failed login attempts made with an invalid user or password. Successful login attempts are limited by the normal API rate limiter. The rate limiter is a GCRA leaky bucket variant, which is shared by all API (REST/XMLRPC) endpoints. However it is important to note that the rate limiter for the HTML/web interface is not shared by the API failed login rate limiter. It is configured through the settings in config.ini. By setting the value of ``api_failed_login_limit`` to a non-zero value, the limiter is enabled. Setting it to 0 will disables the limiter (although this is not recommended). If a user fails to log in more than ``api_failed_login_limit`` times in ``api_failed_login_interval_in_sec`` seconds, a 429 HTTP error will be returned. The error message also tells the user how long to wait before trying to log in again. When a 429 error is returned, the associated account will be temporarily locked until sufficient time has elapsed to generate an additional login token. This time period is determined by the values of the ``api_failed_login_interval_in_sec`` and ``api_failed_login_limit`` parameters. Any login attempts made during this lockout period will be unsuccessful, even if the correct password is provided. This effectively prevents brute force attacks from attempting more than one password every ``api_failed_login_interval_in_sec/api_failed_login_limit`` seconds on average. The system's default settings permit a maximum of four login attempts, after which the user will experience a delay of 2.5 minutes (150 seconds). Currently, there is no established procedure for resetting the rate limiter. Rate Limiting the API --------------------- Roundup includes Rate Limiting for the API, which is distinct from rate limiting login attempts on the web interface. This feature can be enabled by setting the ``api_calls_per_interval`` and ``api_interval_in_sec`` configuration parameters in the ``[web]`` section of the ``config.ini`` file. Details for these settings are documented in the same file. If ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 60`` the user can make 60 calls in a minute. They can use them all up in the first second and then get one call back every second. With ``api_calls_per_interval = 60`` and ``api_interval_in_sec = 3600`` (1 hour) they can use all 60 calls in the first second and they get one additional call every 10 seconds. ``api_calls_per_interval`` is the burst rate that you are willing to allow within ``api_interval_in_sec`` seconds. The average rate of use is the ratio of ``api_calls_per_interval/api_interval_in_sec``. So you can have many values that permit one call per second on average: 1/1, 60/60, 3600/3600, but they all have a different maximum burst rates: 1/sec, 60/sec and 3600/sec. In practice, a single page app may require 20 or 30 API calls to populate the page with data, followed by a few seconds of waiting for the user to select an issue. When displaying the issue, another 20 or more calls may be needed to populate status dropdowns, retrieve the first 10 messages in the issue, and so on. Therefore, controlling both the burst rate and the average rate is a tuning exercise that is left to the tracker admin. It is worth noting that the rate limit feature may be slightly lossy, meaning that under heavy load, it may miscount and allow more than the burst count. On slower hardware, errors of up to 10% have been observed. Using redis, PostgreSQL, or MySQL for storing ephemeral data minimizes the loss. Limit Size of Returned Data --------------------------- When selecting from the database, you can limit the number of rows returned by adding the following to `interfaces.py`_:: from roundup.rest import RestfulInstance RestfulInstance.max_response_row_size = 26 This will limit the setting of ``@page_size`` to 25 (one less than the value). If the url includes a ``@page_size`` pagination value greater than or equal to the ``max_response_row_size`` you will receive an error like:: { "error": { "status": 400, "msg": "Page size 30 must be less than admin limit on query result size: 26." } } The default value is 10 million and one rows. Client API ========== The top-level REST url ``/rest/`` will display the current version of the REST API (Version 1 as of this writing) and some links to relevant endpoints of the API. In the following the ``/rest`` prefix is omitted from relative REST-API links for brevity. Headers ------- If rate limiting is enabled there are 3 "standard" headers: **X-RateLimit-Limit**: Calls allowed per period. **X-RateLimit-Remaining**: Calls available to be completed in this window. **X-RateLimit-Reset**: window ends in this many seconds. (Note, not an epoch timestamp). After this time, all X-RateLimit-Limit calls are available again. and one helpful header to report the period that is missing from other lists of rate limit headers: **X-RateLimit-Limit-Period**: Defines period in seconds for X-RateLimit-Limit. Also if the user has exceeded the rate limit, this header is added: **Retry-After**: The number of second to wait until 1 api call will succeed. If the client has requested a deprecated API endpoint, the header: **Sunset**: an http date after which the end point will not be available. This is not returned by current code, but can be used when `Programming the REST API`_. It should be used as a hint that the REST endpoint will be going away. See https://www.rfc-editor.org/rfc/rfc8594 for details on this header and the sunset link type. Hyperdb Stats ------------- Adding ``@stats=true`` as a GET query parameter or POST data item will augment the response with an ``@stats`` dictionary. Any value other than ``true`` (any case) will disable the ``@stats`` dictionary. When stats are enabled the response includes an ``@stats`` member and looks like:: { "data": { ... "@stats": { "cache_hits": 3, "cache_misses": 1, "get_items": 0.0009722709655761719, "filtering": 0, "elapsed": 0.04731464385986328 } } } These are the same values returned in the html interface by setting the ``CGI_SHOW_TIMING`` environment variable. By default performance stats are not shown. The fields are subject to change. An understanding of the code is recommended if you are going to use this info. Versioning ---------- Currently there is only one version of the API. Versions are simple integers. The current version is ``1``. Version selection is implemented in the server using one of four methods (in priority order, highest first): 1. Explicit version param in accept header: ``application/json; version=1`` 2. Version suffix in vendor accept header: ``application/vnd.json.test-v1+json`` 3. Adding ``@apiver: 1`` in the input data wrapper (for POST, PUT) 4. Adding version specifier in query string: ``@apiver=1`` (for GET). The highest priority version method will be used if multiple methods are used. If an explicit version is not provided, the server default is used. The server default is reported by querying the ``/rest/`` endpoint as described above. Input Formats ------------- For a GET or OPTIONS request, the Content-Type header should not be sent. Otherwise Content-Type is allowed to be ``application/json`` or ``application/x-www-form-urlencoded``. Any other value returns error code 415. CORS preflight requests ~~~~~~~~~~~~~~~~~~~~~~~ CORS preflight requests are done using the OPTIONS method. They require that REST be enabled. These requests do not make any changes or get any information from the database. As a result they are available to the anonymous user and any authenticated user. The user does not need to have ``Rest Access`` permissions. Also these requests bypass CSRF checks except for the Origin header check which is always run for preflight requests. You can permit only allowed ORIGINS by setting ``allowed_api_origins`` in ``config.ini`` to the list of origins permitted to access your api. By default only your tracker's origin is allowed. If a preflight request fails, the api request will be stopped by the browser. The following CORS preflight headers are usually added automatically by the browser and must all be present: * ``Access-Control-Request-Headers`` * ``Access-Control-Request-Method`` * ``Origin`` The headers of the 204 response depend on the ``allowed_api_origins`` setting. If a ``*`` is included as the first element, any client can read the data but they can not provide authentication. This limits the available data to what the anonymous user can see in the web interface. All 204 responses will include the headers: * ``Access-Control-Allow-Origin`` * ``Access-Control-Allow-Headers`` * ``Access-Control-Allow-Methods`` * ``Access-Control-Max-Age: 86400`` If the client's ORIGIN header matches an entry besides ``*`` in the ``allowed_api_origins`` it will also include: * ``Access-Control-Allow-Credentials: true`` permitting the client to log in and perform authenticated operations. If the endpoint accepts the PATCH verb the header ``Accept-Patch`` with valid mime types (usually `application/x-www-form-urlencoded, multipart/form-data`) will be included. It will also include rate limit headers since the request is included in the rate limit for the URL. The results from the CORS preflight should be cached for a day so preflight requests are not expected to cause a problem. If it is an issue, you can see `Creating Custom Rate Limits`_ and craft a rate limiter that ignores anonymous OPTIONS requests. Response Formats ---------------- The default response format is json. If you add the ``dicttoxml2.py`` module you can request XML formatted data using the header ``Accept: application/xml`` in your request. Both output formats are similar in structure. ``dicttoxml2.py`` should be installed in the Python install directory, or the file can be added to the Roundup installation directory along side ``rest.py``. It can also be enabled on a per tracker basis by adding ``dicttoxml2.py`` to the lib directory in your tracker home (you may need to create the directory). Then this can be added to `interfaces.py`_ to enable xml:: from roundup import rest from dicttoxml import dicttoxml as dtox # from tracker_root/lib directory rest.dicttoxml = dtox .. _interfaces.py: reference.html#interfaces-py-hooking-into-the-core-of-roundup The rest interface accepts the http accept header and can include ``q`` values to specify the preferred mechanism. This is the preferred way to specify alternate acceptable response formats. To make testing from the browser easier, you can also append the extension ``.json`` or ``.xml`` to the path component of the url. This will force json or xml (if supported) output. If you use an extension it takes priority over any accept headers. Note the extension does not work for the ``/rest`` or ``/rest/data`` paths. In these cases it returns a 404 error. Adding the header ``Accept: application/xml`` allows these paths to return xml data. The rest interface returns status 406 if you use an unrecognized extension. You will also get a 406 status if none of the entries in the accept header are available or if the accept header is invalid. Note: ``dicttoxml2.py`` is an updated version of ``dicttoxml.py`` and should be used for Roundup running on Python 3.7 or newer. Also the ``/binary_content`` attribute endpoint can be used to retrieve raw file data in many formats. General Guidelines ------------------ Performing a ``GET`` on an item or property of an item will return an ETag header or an @etag property. This needs to be submitted with ``DELETE``, ``PUT`` and ``PATCH`` operations on the item using an ``If-Match`` header or an ``"@etag`` property in the data payload if the method supports a payload. The ETag header value will include a suffix (starting with '-') indicating the Content-Encoding used to respond to the request. If the response was uncompressed, there will be no suffix. The ``@etag`` property never includes the suffix. Any ETag value suffixed or not can be sent in an ``If-Match`` header as the suffix is ignored during comparison. The exact details of returned data is determined by the value of the ``@verbose`` query parameter. The various supported values and their effects are described in the following sections. All output is wrapped in an envelope called ``data``. The output format is described in `Response Formats`_ above. When using collection endpoints (think list of issues, users ...), the ``data`` envelope contains metadata (e.g. total number of items) as well as a ``collections`` list of objects:: { "data": { "meta data field1": "value", "meta data field2": "value", "collection": [ { "link": "url to item", "id": "internal identifier for item" }, { "link": "url to second item", "id": "id item 2" }, ... ] "@links": { "relation": [ { "rel": "relation/subrelation", "uri": "uri to use to implement relation" }, ... ], "relation2": [ {...} ], ... } } } available meta data is described in the documentation for the collections endpoint. The ``link`` fields implement `HATEOS`_ by supplying a url for the resource represented by that object. The "link" parameter with the value of a url is a special case of the @links parameter. .. _HATEOS: https://en.wikipedia.org/wiki/HATEOAS In the @links object, each relationship is a list of full link json objects. These include rel (relationship) and uri properties. In the future this may be extended to include other data like content-type. However including a full @links object for every item includes a lot of overhead since in most cases only the self relationship needs to be represented. Because every object, link and multilink ends up getting a url, the shorter 'link' representation is used for this special case. The ``link`` property expresses the ``self`` relationship and its value is the uri property of the full link object. In collections, properties from each item can be embedded in the returned data (see ``@fields`` below). This can not be done if the property is called link as that conflicts with the self url. When using an item endpoint (think an individual issue), metadata is included in the ``data`` envelope. Inside of the envelope, the ``attributes`` object contains the data for the field/properties of the issue. Example:: { "data": { "meta data field1": "value", "type": "type of item, issue, user ..." "link": "link to retrieve item", "attributes": { "title": "title of issue", "nosy": [ { "link": "url for user4", "id": "4" } ], ... } } } Using a property endpoint (e.g. title or nosy list for an issue) the ``data`` wrapper has a ``data`` subfield that represents the value of the property. This ``data`` subfield may be a simple string (all types except multilink) or a list of strings (multilink properties). Example:: { "data": { "type": "description of class", "@etag": "\"f15e6942f00a41960de45f9413684591\"", "link": "link to retrieve property", "id": "id for object with this property", "data": "value of property" } } Special Endpoints ----------------- There are a few special endpoints that provide some additional data. Tracker administrators can add new endpoints. See "Programming the REST API"_ below. /summary ~~~~~~~~ A Summary page can be reached via ``/summary`` via the ``GET`` method. This is currently hard-coded for the standard tracker schema shipped with roundup and will display a summary of open issues. /data ~~~~~ This is the primary entry point for data from the tracker. The ``/data`` link will display a set of classes of the tracker. All classes can be reached via ``/data/`` where ```` is replace with the name of the class to query, e.g. ``/data/issue``. Individual items of a class (e.g. a single issue) can be queried by giving the issue-id, e.g., ``/data/issue/42``. Individual properties of an item can be queried by appending the property, e.g., ``/data/issue/42/title``. All the links mentioned in the following support the http method ``GET``. Results of a ``GET`` request will always return the results as a dictionary with the entry ``data`` referring to the returned data. Details are in the sections below. /data/\ *class* Collection -------------------------- When you use the ``GET`` method on a class (like ``/data/issue``), the ``data`` will include the number of available items in ``@total_size``. If the size exceeds the administrative limit (which is 10 million by default), ``@total_size`` will be set to ``-1``. To navigate to the last page of results, you can use the ``next`` links or increment ``@page_index`` until the result does not include a ``next`` ``@link`` or ``@total_size`` is not ``-1``. The value of the HTTP header ``X-Count-Total`` is the same as ``@total_size``. A ``collection`` list contains the id and link to the respective item. For example a get on https://.../rest/data/issue returns:: { "data": { "collection": [ { "id": "1", "link": "https://.../rest/data/issue/1" }, { "id": "100", "link": "https://.../rest/data/issue/100" } ... ], "@total_size": 171 } } Collection endpoints support a number of features as seen in the next sections. Having an empty ``collection`` does not mean next next link will not return more data. The row limit is applied when the query is made to the database. The result set is then filtered, removing rows that the user does not have permission to access. So it is possible to have no data items on a page because the user does not have access to them. If you use ``@page_size`` near the administrative limit, you may receive fewer rows than requested. However, this does not mean you are out of data. All clients must be programmed to expect pagination decorations in the response. See the section on pagination below for details. Searching ~~~~~~~~~ Searching is done by adding roundup field names and values as query parameters. Using: https://.../rest/data/issue you can search using: .. list-table:: Query Parameters Examples :header-rows: 1 :widths: 20 20 80 :class: valign-top * - Query parameter - Field type - Explanation * - ``title=foo`` - String - perform a substring search and find any issue with the word foo in the title. * - ``status=2`` - Link - find any issue whose status link is set to the id 2. * - ``status=open`` - Link - find any issue where the name of the status is open. Note this is not a string match so using status=ope will fail. * - ``nosy=1`` - MultiLink - find any issue where the multilink nosy includes the id 1. * - ``nosy=admin`` - MultiLink - find any issue where the multilink nosy includes the user admin. Note this is not a string match so using nosy=admi will fail. * - ``booleanfield=1`` - also values: true, TRUE, yes, YES etc. Other values match false. - Boolean - find an issue with the boolean field set to true. As seen above, Links and Multilinks can be specified numerically or symbolically, e.g., searching for issues in status ``closed`` can be achieved by searching for ``status=closed`` or ``status=3`` (provided the ``closed`` status has ID 3). Note that even though the symbolic name is a string, in this case it is also a key value. As a result it only does an exact match. Searching for strings (e.g. the issue title, or a keyword name) performs a case-insensitive substring search. Searching for ``title=Something`` (or in long form title~=Something) will find all issues with "Something" or "someThing", etc. in the title. Changing the search to ``title:=Something`` (note the ``:``) performs an exact case-sensitive string match for exactly one word ``Something`` with a capital ``S``. Another example is: ``title:=test+that+nosy+actually+works.`` where the + signs are spaces in the string. Replacing ``+`` with the `URL encoding`_ for space ``%20`` will also work. Note that you must match the spaces when performing exact matches. So ``title:=test++that+nosy+actually+works.`` matches the word ``test`` with two spaces between ``test`` and ``that`` in the title. To make this clear, searching ``https://.../rest/data/issue?keyword=Foo`` will not work unless there is a keyword with a (case sensitive) name field of ``Foo`` which is the key field of the keyword. However searching the text property ``name`` using ``https://.../rest/data/keyword?name=Foo`` (note searching keyword class not issue class) will return matches for ``Foo``, ``foobar``, ``foo taz`` etc. In all cases the field ``@total_size`` is reported which is the total number of items available if you were to retrieve all of them. See more details in the parent section about ``@total_size`` and when it can return ``-1``. Other data types: Date, Interval, Integer, Number need examples and may need work to allow range searches. Full text search (e.g. over the body of a msg) is a work in progress. .. _URL Encoding: https://en.wikipedia.org/wiki/Percent-encoding Transitive Searching ^^^^^^^^^^^^^^^^^^^^ In addition to searching an issue by its properties, you can search for issues where linked items have a certain property. For example using ``/issues?messages.author=1`` will find all issues that include (link to) a message created by the admin user. This can also be done using: ``/issues?messages.author=admin``. Note that this requires search permission for messages.author, user.id, and users.username (to perform search with ``admin``. If these search permissions are not present, the search will silently drop the attribute. Similarly you can find all issues where the nosy list includes James Bond with: ``issue?nosy.realname=james+bond``. The alternate way to perform this is to query the user class for the realname: ``user?realname=james+bond`` and retrieve the id. Then you can execute a second rest call ``issue?nosy=7`` to retrieve issues with id 7. Make sure that search access to the class/properties are granted to the user. Note that users can search a field even if they can't view it. However they may be able to use searches to discover the value of the field even if they can't view it. Sorting ~~~~~~~ Collection endpoints support sorting. This is controlled by specifying a ``@sort`` parameter with a list of properties of the searched class. Optionally properties can include a sign ('+' or '-') to specify ascending or descending sort, respectively. If no sign is given, ascending sort is selected for this property. The following example would sort by status (in ascending order of the status.order property) and then by id of an issue:: @sort=status,-id Grouping ~~~~~~~~ Collection endpoints support grouping. This is controlled by specifying a ``@group`` parameter with a list of properties of the searched class. Optionally properties can include a sign ('+' or '-') to specify the groups are sorted in ascending or descending order, respectively. If no sign is given, the groups are returned in ascending order. The following example would return the issues grouped by status (in order from unread->reolved) then within each status, by priority in descending order (wish -> critical):: @group=status,-priority Adding ``@fields=status,priority`` to the query will allow you to see the status and priority values change so you can identify the items in each group. If combined with ``@sort=-id`` within each group he items would be sorted in descending order by id. This is useful for select elements that use optgroup. Pagination ~~~~~~~~~~ Collection endpoints support pagination. This is controlled by query parameters ``@page_size`` and ``@page_index`` (Note the use of the leading ``@`` to make the parameters distinguishable from field names.) .. list-table:: Query Parameters Examples :header-rows: 1 :widths: 20 80 :class: valign-top * - Query parameter - Explanation * - ``@page_size`` - specifies how many items are displayed at once. If no ``@page_size`` is specified, all matching items are returned. * - ``@page_index`` - (which defaults to 1 if not given) specifies which page number of ``@page_size`` items is displayed. Also when pagination is enabled the returned data include pagination links along side the collection data. This looks like:: { "data": { "collection": { ... }, "@total_size": 222, "@links": { "self": [ { "uri": "https://.../rest/data/issue?@page_index=1&@fields=status&@page_size=5", "rel": "self" } ], "next": [ { "uri": "https://.../rest/data/issue?@page_index=2&@fields=status&@page_size=5", "rel": "next" } ] } } } The ``@links`` parameter is a dictionary indexed by relationships. Each relationship is a list of one or more full link json objects. Above we have link relations to move to the next page. If we weren't at the first page, there would be a ``prev`` relation to move to the previous page. Also we have a self relation (which is missing the @page_index, hence we are at page 1) that can be used to get the same page again. Note that the server may choose to limit the number of returned entries in the collection as a DOS prevention measure. As a result clients must be prepared to handle the incomplete response and request the next URL to retrieve all of the entries. Field embedding and verbose output ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ In collections, you can specify what fields should be embedded in the returned data. There are some shortcuts provided using the ``@verbose`` parameter. All the examples in this section are for a GET operation on ``https://.../rest/data/issue``. .. list-table:: Query Parameters Examples :header-rows: 1 :widths: 20 80 :class: valign-top * - Query parameter - Explanation * - ``@verbose=0`` - each item in the collection has its "id" property displayed and a link with the URL to retrieve the item. * - ``@verbose=1`` - for collections this output is the same as ``@verbose=0``. This is the default. * - ``@verbose=2`` - each item in the collection includes the "label" property in addition to "id" property and a link for the item. This is useful as documented below in `Searches and selection`_. * - ``@verbose=3`` - will display the content property of messages and files. Note warnings about this below. Using this for collections is discouraged as it is slow and produces a lot of data. * - ``@fields=status,title`` - will return the ``status`` and ``title`` fields for the displayed issues. It is added to the fields returned by the @verbose parameter. Protected properties can be included in the list and will be returned. In addition collections support the ``@fields`` parameter which is a colon or comma separated list of fields to embed in the response. For example ``https://.../rest/data/issue?@verbose=2`` is the same as: ``https://.../rest/data/issue?@fields=title`` since the label property for an issue is its title. The @fields option supports transitive properties, e.g. ``status.name``. The transitive property may not include multilinks in the path except for the last component. So ``messages.author`` is not allowed because ``messages`` is a multilink while ``messages`` alone would be allowed. You can use both ``@verbose`` and ``@fields`` to get additional info. For example ``https://.../rest/data/issue?@verbose=2&@fields=status`` returns:: { "data": { "collection": [ { "link": "https://.../rest/data/issue/1", "title": "Welcome to the tracker START HERE", "id": "1", "status": { "link": "https://.../rest/data/status/1", "id": "1", "name": "new" } }, ... } the format of the status field (included because of ``@fields=status``) includes the label for the status. This is due to inclusion of ``@verbose=2``. Without verbose you would see:: { "data": { "collection": [ { "link": "https://.../rest/data/issue/1", "id": "1", "status": { "link": "https://.../rest/data/status/1", "id": "1" } }, ... } Note that the ``link`` field that is returned doesn't exist in the database. It is a construct of the rest interface. This means that you can not set ``@fields=link`` and get the link property included in the output. Also using ``@fields=@etag`` will not work to retrieve the etag for items in the collection. See the `Searches and selection`_ section for the use cases supported by these features. Getting Message and Files Content ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ You can retreive a message with a url like ``https://.../demo/rest/data/msg/11``. This returns something like:: { "data": { "id": "11", "type": "msg", "link": "https://.../demo/rest/data/msg/11", "attributes": { "author": { "id": "5", "link": "https://.../demo/rest/data/user/5" }, "content": { "link": "https://.../demo/msg11/" }, "date": "2017-10-30.00:53:15", "files": [], "inreplyto": null, "messageid": "<1509324807.14.0.296813919751.issue3@localhost>", "messagetype": { "id": "1", "link": "https://.../demo/rest/data/msgtype/1" }, "recipients": [ { "id": "1", "link": "https://.../demo/rest/data/user/1" }, { "id": "3", "link": "https://.../demo/rest/data/user/3" }, { "id": "4", "link": "https://.../demo/rest/data/user/4" } ], "subject": null, "summary": "of has to who. or of account give because the", }, "@etag": "\"584f82231079e349031bbb853747df1c\"" } } With Roundup 2.5 you can retrieve the data directly from the rest interface using the ``Accept`` header value to select a structured (json or optional xml) representation (as above) or a stream with just the content data. Using the wildcard type ``*/*`` in the ``Accept`` header with the url ``.../binary_content`` will return the raw data and the recorded mime type of the the data as the ``Content-Type``. Using ``*/*`` with another end point will return ``json`` data. An ``Accept`` value of ``application/octet-stream`` matches any mime type and retrieves the raw data as ``Content-Type: application/octet-stream``. To access the contents of a PNG image file (in file23), you use the following link: ``https://.../demo/rest/data/file/23/binary_content``. To find out the mime type, you can check this URL: ``https://.../demo/rest/data/file/23/type``. By setting the header to ``Accept: application/octet-stream; q=1.0, application/json; q=0.5``, you will receive the binary PNG file with the header ``Content-Type: application/octet-stream``. If you switch the ``q`` values, you will receive the encoded JSON version:: { "data": { "id": "23", "type": "", "link": "https://.../demo/rest/data/file/23/binary_content", "data": "b'\\x89PNG\\r\\n\\x1a\\n\\x00[...]0\\x00\\x00\\x00IEND\\xaeB`\\x82'", "@etag": "\"db6adc1b09d95b0388d79c7905bc7982\"" } } with ``Content-Type: application/json`` and a (4x larger) json encoded representation of the binary data. If you want it returned with a ``Content-Type: image/png`` header, you can use ``image/png`` or ``*/*`` in the Accept header. For message files, you can use ``https://.../demo/rest/data/msg/23/binary_content`` with ``Accept: application/octet-stream; q=0.5, application/json; q=0.4, image/png; q=0.495, text/*``. It will return the plain text of the message. Most message files are not stored with a mime type. Getting ``https://.../demo/rest/data/msg/23/type`` returns:: { "data": { "id": "23", "type": "", "link": "https://.../demo/rest/data/msg/23/type", "data": null, "@etag": "\"ba98927a8bb4c56f6cfc31a36f94ad16\"" } } The data attribute will usually be null/empty. As a result, mime type matching for an item without a mime type is forgiving. Messages are meant to be human readable, so the mime type ``text/*`` can be used to access any text style mime type (``text/plain``, ``text/x-rst``, ``text/markdown``, ``text/html``, ...) or an empty mime type. If the item's type is not empty, it will be used as the Content-Type (similar to ``*/*``). Otherwise ``text/*`` will be the Content-Type. If your tracker supports markup languages (e.g. markdown), you should set the mime type (e.g. ``text/markdown``) when storing your message. Note that the header ``X-Content-Type-Options: nosniff`` is returned with a non javascript or xml binary_content response to prevent the browser from trying to interpret the returned data. Legacy Method (HTML interface) ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ With the addition of file binary content streaming in the rest interface to Roundup 2.5.0, this method (using the html interface) is considered legacy but still works. To retreive the content, you can use the content link property: ``https://.../demo/msg11/``. The trailing / is required. Without the /, you get a web page that includes metadata about the message. With the slash you get a text/plain (in most cases) data stream. Also you can use the url: ``https://.../demo/rest/data/msg/11?@verbose=3`` and the content property (if the data is utf-8 compatible) now looks like:: ... "author": { "id": "5", "link": "https://.../demo/rest/data/user/5" }, "content": "of has to who pleasure. or of account give because the reprehenderit\neu to quisquam velit, passage, was or toil BC quis denouncing quia\nexercise, veritatis et used voluptas I elit, a The...", "date": "2017-10-30.00:53:15", ... Lines are wrapped for display, content value is one really long line. If the data is not utf-8 compatible, you will get a link. Retrieving the contents of a file is similar. Performing a get on ``https://.../demo/rest/data/file/11`` returns:: { "data": { "id": "11", "type": "file", "link": "https://.../demo/rest/data/file/11", "attributes": { "acl": null, "content": { "link": "https://.../demo/file11/" }, "name": "afile", "status": { "id": "1", "link": "https://.../demo/rest/data/filestatus/1" }, "type": "image/vnd.microsoft.icon" }, "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\"" } } To download the file contents for this example you would perform an http GET using: ``https://.../demo/file11/``. The trailing / is required. You will receive a response of type application/octet-stream. If you perform a get on ``https://.../demo/rest/data/file/11?@verbose=3`` the content field above is displayed as (wrapped for display):: "content": "file11 is not text, retrieve using binary_content property. mdsum: bd990c0f8833dd991daf610b81b62316", You can use the `binary_content property`_ described below to retrieve an encoded copy of the data. Other query params ~~~~~~~~~~~~~~~~~~ This table lists other supported parameters: .. list-table:: Query Parameters Examples :header-rows: 1 :widths: 20 80 :class: valign-top * - Query parameter - Explanation * - ``@pretty=false`` - by default json data is pretty printed to make it readable to humans. This eases testing and with compression enabled the extra whitespace doesn't bloat the returned payload excessively. You can disable pretty printing by using this query parameter. Note the default is true, so @pretty=true is not supported at this time. Using the POST method ~~~~~~~~~~~~~~~~~~~~~ Only class links support the ``POST`` method for creation of new items of a class, e.g., a new issue via the ``/data/issue`` link. The post gets a dictionary of keys/values for the new item. It returns the same parameters as the GET method after successful creation. If you perform a get on an item with ``@verbose=0``, it is in the correct form to use as the payload of a post. Safely Re-sending POST ^^^^^^^^^^^^^^^^^^^^^^ POST is used to create new object in a class. E.G. a new issue. One problem is that a POST may time out. Because it is not idempotent like a PUT or DELETE, retrying the interrupted POST may result in the creation of a duplicate issue. To solve this problem, a two step process inspired by the POE - Post Once Exactly spec: https://datatracker.ietf.org/doc/html/draft-nottingham-http-poe-00 is provided. This mechanism returns a single use URL. POSTing to the URL creates a new object in the class. First we get the URL. Here is an example using curl:: curl -u demo:demo -s -X POST -H "Referer: https://.../demo/" \ -H "X-requested-with: rest" \ -H "Content-Type: application/json" \ --data '' \ https://.../demo/rest/data/issue/@poe This will return a json payload like:: { "data": { "expires": 1555266310.4457426, "link": "https://.../demo/rest/data/issue/@poe/vizl713xHtIzANRW9jPb3bWXePRzmehdmSXzEta1" } } The value of expires is a Unix timestamp in seconds. In this case it has the default lifetime of 30 minutes after the current time. Using the link more than 30 minutes into the future will cause a 400 error. Within 30 minutes, the link can be used to post an issue with the same payload that would normally be sent to: ``https://.../demo/rest/data/issue``. For example:: curl -u demo:demo -s -X POST \ -H "Referer: https://.../demo/" \ -H "X-requested-with: rest" \ -H "Content-Type: application/json" \ --data-binary '{ "title": "a problem" }' \ https://.../demo/rest/data/issue/@poe/vizl713xHtIzANRW9jPb3bWXePRzmehdmSXzEta1 returns:: { "data": { "link": "https://.../demo/rest/data/issue/2280", "id": "2280" } } Once the @poe link is used and creates an issue, it becomes invalid and can't be used again. Posting to it after the issue, or other object, is created, results in a 400 error [#poe_retry]_. Note that POE links are restricted to the class that was used to get the link. So you can only create an issue using the link returned from ``rest/data/issue/@poe``. You can create a generic POE link by adding the "generic" field to the post payload:: curl -u demo:demo -s -X POST -H "Referer: https://.../demo/" \ -H "X-requested-with: rest" \ --data 'lifetime=900&generic=1' \ https://.../demo/rest/data/issue/@poe This will return a link under: ``https://.../demo/rest/data/issue/@poe``:: { "data": { "expires": 1555268640.9606116, "link": "https://.../demo/rest/data/issue/@poe/slPrzmEq6Q9BTjvcKhfxMNZL4uHXjbHCidY1ludZ" } } You could use the link and change 'issue' to 'user' and it would work to create a user. Creating generic POE tokens is *not* recommended, but is available if a use case requires it. This example also changes the lifetime of the POE url. This link has a lifetime of 15 minutes (900 seconds). Using it after 16 minutes will result in a 400 error. A lifetime up to 3600 seconds (1 hour) can be specified. POE url's are an optional mechanism. If: * you do not expect your client to retry a failed post, * a failed post is unlikely (e.g. you are running over a local lan), * there is a human using the client and who can intervene if a post fails you can use the url ``https://.../demo/data/``. However if you are using this mechanism to automate creation of objects and will automatically retry a post until it succeeds, please use the POE mechanism. .. [#poe_retry] As a future enhancement, performing a POST to the POE link soon after it has been used to create an object will change. It will not return a 400 error. It will will trigger a 301 redirect to the url for the created object. After some period of time (maybe a week) the POE link will be removed and return a 400 error. This is meant to allow the client (a time limited way) to retrieve the created resource if the response was lost. Other Supported Methods for Collections ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Supports the ``OPTIONS`` method for determining which methods are allowed on a given endpoint. Does not support PUT, DELETE or PATCH. /data/user/roles endpoint ------------------------- The list of valid roles for a user is not an actual class in the hyperdb. This endpoint returns a list of all defined roles if the user has the ``Admin`` role. Otherwise it returns a 403 - not authorized error. The output from this endpoint looks like:: { "data": { "collection": [ { "id": "user", "name": "user" }, { "id": "admin", "name": "admin" }, { "id": "anonymous", "name": "anonymous" } ] } } to mimic a class collection. Unlike a real class collection endpoint, ``@total_size`` is not returned. Also it does not support and ignores any query options like: filtering, ``@sort``, ``@group``, ``@verbose`` etc. Note that the ``id`` property is not numeric. This endpoint was introduced in release 2.4.0 to support a roles select/dropdown in the web component classhelper. This lets the web component helper implement the same function in the classic user class classhelper. /data/\ *class*/\ *id* item --------------------------- When you use the ``GET`` method on an item (e.g. ``/data/issue/42``), a ``link`` attribute contains the link to the item, ``id`` contains the id, ``type`` contains the class name (e.g. ``issue`` in the example) and an ``etag`` property can be used to detect modifications since the last query. Individual properties of the item are returned in an ``attributes`` dictionary. The properties returned depend on the permissions of the account used for the query. By default all (visible to the current user) attributes/properties are returned. You can limit this by using the ``@fields`` query parameter similar to how it is used in collections. This way you can only return the fields you are interested in reducing network load as well as memory and parsing time on the client side. Or you can add additional transitive properties. By default protected properties (read only in the database) are not listed. This makes it easier to submit the attributes from a ``@verbose=0`` query using PUT. To include protected properties in the output of a GET add the query parameter ``@protected=true`` to the query and attributes like: actor, created, creator and activity will be include in the result. Link and Multilink properties are displayed as a dictionary with a ``link`` and an ``id`` property by default. This is controlled by the ``@verbose`` attribute which is set to 1 by default. If set to 0, only the id is shown for Link and Multilink attributes. In this form, the data can be modified and sent back using ``PUT`` to change the item. If set to 2, the label property (usually ``name`` e.g. for status) is also put into the dictionary. Content properties of message and file object are by default also shown as a dictionary with a sole link attribute. The link is the download link for the file or message. If @verbose is >= 3, the content property is shown in json as a (possibly very long) string. Currently the json serializer cannot handle files not properly utf-8 encoded, so specifying @verbose=3 for files is currently discouraged. An example of returned values:: { "data": { "type": "issue", "@etag": "\"f15e6942f00a41960de45f9413684591\"", "link": "https://.../rest/data/issue/23", "attributes": { "keyword": [], "messages": [ { "link": "https://.../rest/data/msg/375", "id": "375" }, { "link": "https://.../rest/data/msg/376", "id": "376" }, ... ], "files": [], "status": { "link": "https://.../rest/data/status/2", "id": "2" }, "title": "This is a title title", "superseder": [], "nosy": [ { "link": "https://.../rest/data/user/4", "id": "4" }, { "link": "https://.../rest/data/user/5", "id": "5" } ], "assignedto": null, }, "id": "23" } } Retrieve item using key value ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If the class has a key attribute, e.g. the 'status' class in the classic tracker, it can be used to retrieve the item. You can get an individual status by specifying the key-attribute value e.g. ``/data/status/name=closed``. Note that ``name`` in this example must be the key-attribute of the class. A short-form (which might not be supported in future version of the API) is to specify only the value, e.g. ``/data/status/closed``. This short-form only works when you're sure that the key of the class is not numeric. E.G. if the name was "7", /data/status/7 would return the status with id 7 not the status with name "7". To get the status with name 7, you must use the long form /data/status/name=7 The long-form (with ``=``) is different from a query-parameter like ``/data/status?name=closed`` which would find all stati (statuses) that have ``closed`` as a substring. Dealing with Messages and Files ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Using the requests library you can upload a file using:: d = dict (name = filename, content = content, type = content_type) j = self.post ('file', data = d) Instead of specifying json = dictionary we specify data = dictionary as shown above. (We believe) this encodes the contents using application/x-www-form-urlencoded which is not optimal for large files due to the encoding overhead. The requests library can use multipart/form-data which is more efficient for large files. To do this specify both, files= *and* data= parameters, e.g.:: # A binary string that can't be decoded as unicode url = 'https://.../demo/rest/data/' content = open ('random-junk', 'rb').read () fname = 'a-bigger-testfile' d = dict(name = fname, type='application/octet-stream') c = dict (content = content) r = session.post (url + 'file', files = c, data = d) Curl can be used to post a file using multipart/form-data with:: curl -u demo:demo -s -X POST -H "Referer: https://.../demo/" \ -H "X-requested-with: rest" \ -F "name=afile" -F "type=image/vnd.microsoft.icon" \ -F "content=@doc/roundup-favicon.ico" \ https://.../demo/rest/data/file the file is located at doc/roundup-favicon.ico. These calls will return something like:: { "data": { "id": "12", "link": "https://.../demo/rest/data/file/12" } } Other Supported Methods for Items ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The method ``PUT`` is allowed on individual items, e.g. ``/data/issue/42`` On success it returns a data structure similar to the respective ``GET`` method. However it is only concerned with the changes that have occurred. Since it is not a full ``GET`` request, it doesn't include an etag or unchanged attributes. Note that for ``PUT`` an Etag has to be supplied, either in the request header or as an @etag parameter. An example:: curl -u admin:admin -X PUT \ --header 'Referer: https://example.com/demo/' \ --header 'X-Requested-With: rest' \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --header 'If-Match: "dd41f02d6f8b4c34b439fc712b522fb3"' \ --data '{ "nosy": [ "1", "5" ] }' \ "https://example.com/demo/rest/data/issue/23" { "data": { "attribute": { "nosy": [ "1", "5" ] }, "type": "issue", "link": "https://example.com/demo/rest/data/issue/23", "id": "23" } } If the above command is repeated with the data attribute:: --data '{ "nosy": [ "1", "5" ], "title": "This is now my title" }' this is returned:: { "data": { "attribute": { "title": "This is now my title" }, "type": "issue", "link": "https://.../demo/rest/data/issue/23", "id": "23" } } Note that nosy is not in the attributes returned. It is the same as before, so no change has happened and it is not reported. Changing both nosy and title:: curl -u admin:admin -X PUT \ --header 'Referer: https://.../' \ --header 'X-Requested-With: rest' \ --header "Content-Type: application/json" \ --header "Accept: application/json" \ --header 'If-Match: "8209add59a79713d64f4d1a072aef740"' \ --data '{ "nosy": [ "4", "5" ], "title": "This is now my new title" }' \ "https://.../demo/rest/data/issue/23" which returns both title and nosy attributes:: { "data": { "attribute": { "title": "This is now my new title", "nosy": [ "4", "5" ] }, "type": "issue", "link": "https://.../demo/rest/data/issue/23", "id": "23" } } Note that mixing url query parameters with payload submission doesn't work. So using:: https://.../rest/data/issue/23?@pretty=false doesn't have the desired effect. However it can be put in the data payload:: curl -u admin:admin ... --data '{ "nosy": [ "4", "5" ], "title": "...", "@pretty": "false" }' produces:: {"data": {"attribute": {...}, "type": "issue", "link": "https://...", "id": "23"}} the lines are wrapped for display purposes, in real life it's one long line. The method ``DELETE`` is allowed on items, e.g., ``/data/issue/42`` and will retire (mark as deleted) the respective item. On success it will only return a status code. The item is still available if accessed directly by its item url. The item will not show up in searches where it would have been matched if not retired. Finally the ``PATCH`` method can be applied to individual items, e.g., ``/data/issue/42``. This method gets an operator ``@op=`` where ```` is one of ``add``, ``replace``, ``remove``. For items, an additional operator ``action`` is supported. If no operator is specified, the default is ``replace``. The first three operators are self explanatory. For an ``action`` operator an ``@action_name`` and optional ``@action_argsXXX`` parameters have to be supplied. Currently there are only two actions, neither has args, namely ``retire`` and ``restore``. The ``retire`` action on an item is the same as a ``DELETE`` method, it retires the item. The ``restore`` action is the inverse of ``retire``, the item is again visible. On success the returned value is the same as the respective ``GET`` method. An example to add a user to the nosy list of an item is:: curl -u admin:admin -p -X PATCH \ --header "Content-Type: application/x-www-form-urlencoded" \ --header "Accept: application/json" \ --header 'If-Match: "c6e2d81019acff1da7a2da45f93939bd"' \ --data-urlencode '@op=add' \ --data 'nosy=3' \ "https://.../rest/data/issue/23" which returns:: { "data": { "attribute": { "nosy": [ "3", "4" ] }, "type": "issue", "link": "https://.../rest/data/issue/23", "id": "23" } } Note that the changed values are returned so you can update internal state in your app with the new data. The ``GET`` method on an item (e.g. ``/data/issue/43``) returns an ETag in the http header *and* the ``@etag`` value in the json payload. When modifying a property via ``PUT`` or ``PATCH`` or ``DELETE`` the etag value for the item must be supplied using an ``If-Match`` header. If you are using ``PUT`` or ``PATCH`` an ``@etag`` value can be supplied in the payload in place of the ``If-Match`` header. /data/\ *class*/\ *id*/\ *property* field ----------------------------------------- A ``GET`` method on a property (e.g. ``/data/issue/42/title``) returns the link, an ``@etag``, the type of the property (e.g. "") the id of the item and the content of the property in ``data``. For example:: { "data": { "link": "https://.../rest/data/issue/22/title", "data": "I need Broken PC", "type": "", "id": "22", "@etag": "\"370510512b2d8fc3f98aac3d762cc7b1\"" } } All endpoints support an ``OPTIONS`` method for determining which methods are allowed on a given endpoint. Message and File Content ~~~~~~~~~~~~~~~~~~~~~~~~ Messages and files have content properties. If the data is utf-8 compatible (e.g. an email message) you can retrieve it with rest/data/msg/11/content to obtain:: { "data": { "id": "11", "type": "", "link": "https://.../demo/rest/data/msg/11/content", "data": "of has to who pleasure. or of account give because the reprehenderit\neu to quisquam velit, passage, was or...", "@etag": "\"584f82231079e349031bbb853747df1c\"" } } (the content property is wrapped for display, it is one long line.) .. _binary_content property: If the data is not representable in utf-8, you need to use the binary_content property. E.G. ``https://.../demo/rest/data/file/11/binary_content`` returns:: { "data": { "id": "11", "type": "", "link": "https://.../demo/rest/data/file/11/binary_content", "data": "b'\\x00\\x00\\x01\\x00\\x01...\\xec?\\x00\\x00'", "@etag": "\"74276f75ef71a30a0cce62dc6a8aa1bb\"" } } (data field elided for display). You can also receive the file content as a data stream rather than encoded. See `Getting Message and Files Content`_. The data is a json encoded hexidecimal representation of the data. Other Supported Methods for fields ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The method ``PUT`` is allowed on a property e.g., ``/data/issue/42/title``. On success it returns the same parameters as the respective ``PUT`` method on the item. For example:: { "data": { "id": "42", "type": "issue", "link": "https://.../demo/rest/data/issue/42", "attribute": { "title": "this is a new title" } } } If the new value for the title was the same as on the server, the attribute property would be empty since the value was not changed. Note that for ``PUT`` an Etag has to be supplied, either in the request header or as an @etag parameter. Example using multipart/form-data rather than json:: curl -vs -u provisional:provisional -X PUT \ --header "Accept: application/json" \ --data "data=Provisional" \ --header "If-Match: 079eba599152f3eed00567e23258fecf" \ --data-urlencode "@etag=079eba599152f3eed00567e23258fecf" \ "https://.../rest/data/user/5/realname" This example updates a leadtime field that is declared as an interval type:: curl -vs -u demo:demo -X PUT \ --header "Accept: application/json" \ --header 'Content-Type: application/json' \ --header "Referer: https://.../" \ --header "x-requested-with: rest" \ --header 'If-Match: "e2e6cc43c3475a4a3d9e5343617c11c3"' \ --data '{"leadtime": "2d" }' \ "https://.../rest/data/issue/10" It is also possible to call ``DELETE`` on a property of an item, e.g., ``/data/issue/42/nosy`` to delete the nosy list. The same effect can be achieved with a ``PUT`` request and an empty new value. This may fail if the property is required. The ``PATCH`` method can be applied to properties, e.g., ``/data/issue/42/title``. This method gets an operator ``@op=`` where ```` is one of ``add``, ``replace``, ``remove``. If no operator is specified, the default is ``replace`` which is the same as performing a PUT on the field url. ``add`` and ``remove`` allow adding and removing values from MultiLink properties. This is easier than having to rewrite the entire value for the field using the ``replace`` operator or doing a PUT to the field. On success the returned value is the same as the respective ``GET`` method. The ``GET`` method on an item (e.g. ``/data/issue/43``) returns an ETag in the http header *and* the ``@etag`` value in the json payload. When modifying a property via ``PUT`` or ``PATCH`` or ``DELETE`` the etag value for the item must be supplied using an ``If-Match`` header. If you are using ``PUT`` or ``PATCH`` an ``@etag`` value can be supplied in the payload in place of the ``If-Match`` header. Tunneling Methods via POST -------------------------- If you are working through a proxy and unable to use http methods like PUT, PATCH, or DELETE, you can use POST to perform the action. To tunnel an action through POST, send the ``X-HTTP-METHOD-OVERRIDE`` header with a value of DELETE or other capitalized HTTP verb. The body of the POST should be what you would send if you were using the method without tunneling. Examples and Use Cases ====================== sample python client -------------------- The client uses the python ``requests`` library for easier interaction with a REST API supporting JSON encoding:: >>> import requests >>> u = 'http://user:password@tracker.example.com/demo/rest/data/' >>> s = requests.session() >>> session.auth = ('admin', 'admin') >>> r = s.get(u + 'issue/42/title') >>> if r.status_code != 200: ... print("Failed: %s: %s" % (r.status_code, r.reason)) ... exit(1) >>> print (r.json() ['data']['data'] TEST Title >>> h = {'X-Requested-With': 'rest', 'Referer': 'http://tracker.example.com/demo/'} >>> r = s.post (u + 'issue', data = dict (title = 'TEST Issue'), headers=h) >>> if not 200 <= r.status_code <= 201: ... print("Failed: %s: %s" % (r.status_code, r.reason)) ... exit(1) >>> print(r.json()) Retire/Restore:: >>> r = s.delete (u + 'issue/42') >>> print (r.json()) >>> r = s.get (u + 'issue/42') >>> etag = r.headers['ETag'] >>> print("ETag: %s" % etag) >>> etag = r.json()['data']['@etag'] >>> print("@etag: %s" % etag) >>> h = {'If-Match': etag, ... 'X-Requested-With': 'rest', ... 'Referer': 'http://tracker.example.com/demo/'} >>> d = {'@op:'action', '@action_name':'retire'} >>> r = s.patch(u + 'issue/42', data = d, headers = h) >>> print(r.json()) >>> d = {'@op:'action', '@action_name':'restore'} >>> r = s.patch(u + 'issue/42', data = d, headers = h) >>> print(r.json()) Note the addition of headers for: x-requested-with and referer. This allows the request to pass the CSRF protection mechanism. You may need to add an Origin header if this check is enabled in your tracker's config.ini (look for csrf_enforce_header_origin). (Note the Origin header check may have to be disabled if an application is making a CORS request to the Roundup server. If you have this issue, please contact the Roundup team using the mailing lists as this is a bug.) A similar curl based retire example is to use:: curl -s -u admin:admin \ -H "Referer: https://tracker.example.com/demo/" \ -H "X-requested-with: rest" \ -H "Content-Type: application/json" \ https://tracker.example.com/demo/rest/data/status/1 to get the etag manually. Then insert the etag in the If-Match header for this retire example:: curl -s -u admin:admin \ -H "Referer: https://tracker.example.com/demo/" \ -H "X-requested-with: rest" \ -H "Content-Type: application/json" \ -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \ --data-raw '{ "@op":"action", "@action_name": "retire" }'\ -X PATCH \ https://tracker.example.com/demo/rest/data/status/1 and restore:: curl -s -u admin:admin \ -H "Referer: https://tracker.example.com/demo/" \ -H "X-requested-with: rest" \ -H "Content-Type: application/json" \ -H 'If-Match: "a502faf4d6b8e3897c4ecd66b5597571"' \ --data-raw '{ "@op":"action", "@action_name": "restore" }'\ -X PATCH \ https://tracker.example.com/demo/rest/data/status/1 Searches and selection ---------------------- One difficult interface issue is selection of items from a long list. Using multi-item selects requires loading a lot of data (e.g. consider a selection tool to select one or more issues as in the classic superseder field). This can be made easier using javascript selection tools like select2, selectize.js, chosen etc. These tools can query a remote data provider to get a list of items for the user to select from. Consider a multi-select box for the superseder property. Using selectize.js (and jquery) code similar to:: $('#superseder').selectize({ valueField: 'id', labelField: 'title', searchField: 'title', ... load: function(query, callback) { if (!query.length) return callback(); $.ajax({ url: '.../rest/data/issue?@verbose=2&title=' + encodeURIComponent(query), type: 'GET', error: function() {callback();}, success: function(res) { callback(res.data.collection);} Sets up a box that a user can type the word "request" into. Then selectize.js will use that word to generate an ajax request with the url: ``.../rest/data/issue?@verbose=2&title=request`` This will return data like:: { "data": { "@total_size": 440, "collection": [ { "link": ".../rest/data/issue/8", "id": "8", "title": "Request for Power plugs" }, { "link": ".../rest/data/issue/27", "id": "27", "title": "Request for foo" }, ... selectize.js will look at these objects (as passed to callback(res.data.collection)) and create a select list from the each object showing the user the labelField (title) for each object and associating each title with the corresponding valueField (id). The example above has 440 issues returned from a total of 2000 issues. Only 440 had the word "request" somewhere in the title greatly reducing the amount of data that needed to be transferred. Similar code can be set up to search a large list of keywords using:: .../rest/data/keyword?@verbose=2&name=some which would return: "some keyword" "awesome" "somebody" making selections for links and multilinks much easier. A get on a collection endpoint can include other properties. Why do we want this? Selectize.js can set up option groups (optgroups) in the select pulldown. So by including status in the returned data using a url like ``https://.../rest/data/issue?@verbose=2&@fields=status`` we get:: { "link": "https://.../rest/data/issue/1001", "title": "Request for Broken PC", "id": "1001", "status": { "link": "https://.../rest/data/status/6", "id": "6", "name": "resolved" } } a select widget like:: === New === A request === Open === Request for bar Request for foo etc. can be generated. Also depending on the javascript library, other fields can be used for subsearch and sorting. Programming the REST API ======================== You can extend the rest api for a tracker. This describes how to add new rest end points. At some point it will also describe the rest.py structure and implementation. Adding new rest endpoints ------------------------- Add or edit the file `interfaces.py`_ at the root of the tracker directory. In that file add:: from roundup.rest import Routing, RestfulInstance, _data_decorator from roundup.exceptions import Unauthorised class RestfulInstance: @Routing.route("/summary2") @_data_decorator def summary2(self, input): result = { "hello": "world" } return 200, result will make a new endpoint .../rest/summary2 that you can test with:: $ curl -X GET .../rest/summary2 { "data": { "hello": "world" } } Similarly appending this to interfaces.py after summary2:: # handle more endpoints @Routing.route("/data/<:class_name>/@schema", 'GET') def get_element_schema(self, class_name, input): result = { "schema": {} } uid = self.db.getuid () if not self.db.security.hasPermission('View', uid, class_name) : raise Unauthorised('Permission to view %s denied' % class_name) class_obj = self.db.getclass(class_name) props = class_obj.getprops(protected=False) schema = result['schema'] for prop in props: schema[prop] = { "type": repr(class_obj.properties[prop]) } return result .. the # comment in the example is needed to preserve indention under Class. returns some data about the class:: $ curl -X GET .../rest/data/issue/@schema { "schema": { "keyword": { "type": "" }, "title": { "type": "" }, "files": { "type": "" }, "status": { "type": "" }, ... } } Adding other endpoints (e.g. to allow an OPTIONS query against ``/data/issue/@schema``) is left as an exercise for the reader. Redefine/move rest endpoints ---------------------------- In addition to adding new endpoints, you can redefine existing endpoints. Adding this as described above:: @Routing.route("/summary") @_data_decorator def summary2(self, input): result = { "hello": "world" } return 200, result will return:: { "data": { "hello": "world" } } In addition to overriding existing endpoints, you can move existing endpoints to new locations. Adding:: @Routing.route("/data2/<:classname>") def get_collection2(self, classname, input): """ Remap existing function in rest.py to a new endpoint Existing function is decorated with: @Routing.route("/data/<:classname>") @_data_decorator so we need to drop @_data_decorator from this function since we can't apply @_data_decorator twice. """ return self.get_collection(classname, input) will make the response at /rest/data2/ be the same as what is normally at /rest/data/. Controlling Access to Backend Data ---------------------------------- Roundup's schema is the primary access control mechanism. Roles and Permissions provide the ability to carefully control what data can be seen. However the templating system can access the hyperdb directly which allows filtering to happen with admin privs escaping the standard permissions scheme. For example access to a user's roles should be limited to the user (read only) and an admin. If you have customised your schema to implement `Restricting the list of users that are assignable to a task `__ so that only users with a Developer role are allowed to be assigned to an issue, a rest end point must be added to provide a view that exposes users with this permission. Using the normal ``/data/user?roles=Developer`` will return all the users in the system unless you are an admin user because most users can't see the roles. Building on the `Adding new rest endpoints`_ section this code adds a new endpoint ``/data/@permission/Developer`` that returns a list of users with the developer role:: from roundup.rest import Routing, RestfulInstance from roundup.anypy.cgi_ import MiniFieldStorage class RestfulInstance(object): @Routing.route("/data/@permission/Developer") def get_role_Developer(self, input): '''An endpoint to return a list of users with Developer role who can be assigned to an issue. It ignores attempt to search by any property except username and realname. It also ignores the whole @fields specification if it specifies a property the user can't view. Other @ query params (e.g. @page... and @verbose) are supported. It assumes admin access rights so that the roles property of the user can be searched. This is needed if the roles property is not searchable/viewable by normal users. A user who can search roles can identify users with the admin role. So it does not respond the same as a rest/data/users search by a non-admin user. ''' # get real user id realuid=self.db.getuid() def allowed_field(fs): if fs.name in ['username', 'realname' ]: # only allow search matches for these fields return True elif fs.name in [ '@fields' ]: for prop in fs.value.split(','): # if any property is unviewable to user, remove # @field entry. If they can't see it for the admin # user, don't let them see it for any user. if not self.db.security.hasPermission( 'View', realuid, 'user', property=prop, itemid='1'): return False return True elif fs.name.startswith("@"): # allow @page..., @verbose etc. return True # deny all other url parmeters return False # Cleanup input.list to prevent user from probing roles # or viewing things the user should not be able to view. input.list[:] = [ fs for fs in input.list if allowed_field(fs) ] # Add the role filter required to implement the permission # search input.list.append(MiniFieldStorage("roles", "Developer")) # change user to acquire permission to search roles self.db.setCurrentUser('admin') # Once we have cleaned up the request, pass it to # get_collection as though /rest/data/users?... has been called # to get @verbose and other args supported. return self.get_collection('user', input) Calling this with:: curl 'http://example.com/demo/rest/data/@permission/Developer?@fields=realname&roles=Users&@verbose=2' produces output similar to:: { "data": { "collection": [ { "username": "agent", "link": http://example.com/demo/rest/data/user/4", "realname": "James Bond", "id": "4" } ], "@total_size": 1 } } assuming user 4 is the only user with the Developer role. Note that the url passes the ``roles=User`` filter option which is silently ignored. Changing Access Roles with JSON Web Tokens ------------------------------------------ As discussed above Roundup's schema is the access control mechanism. However you may want to integrate a third party system with roundup. E.G. suppose you use a time tracking service that takes an issue id and keeps a running count of how much time was spent on it. Then with a single button push it can add the recorded time to the roundup issue. You probably don't want to give this third party service your roundup username and credentials. Especially if your roundup instance is under your company's single sign on infrastructure. So what we need is a way for this third party service to impersonate you and have access to create a roundup timelog entry (see ``_). Then add it to the associated issue. This should happen without sharing passwords and without allowing the third party service to see the issue (except the ``times`` property), user, or other information in the tracker. Enter the use of a JSON web token. Roundup has rudimentary ability to manage JWTs and use them for authentication and authorization. There are 5 steps to set this up: 1. install pyjwt library using pip or pip3. If roundup can't find the jwt module you will see the error ``Support for jwt disabled.`` 2. create a new role that allows Create access to timelog and edit/view access to an issues' ``times`` property. 3. add support for issuing (and validating) JWTs to the rest interface. This uses the `Adding new rest endpoints`_ mechanism. 4. configure roundup's config.ini [web] jwt_secret with at least 32 random characters of data. (You will get a message ``Support for jwt disabled by admin.`` if it's not long enough.) If you have openssl installed, you can use the output of ``openssl rand -base64 32``. 5. add an auditor to make sure that users with this role are appending timelog links to the ``times`` property of the issue. Create role ~~~~~~~~~~~ Adding this snippet of code to the tracker's ``schema.py`` should create a role with the proper authorization:: db.security.addRole(name="User:timelog", description="allow a user to create and append timelogs") db.security.addPermissionToRole('User:timelog', 'Rest Access') perm = db.security.addPermission(name='Create', klass='timelog', description="Allow timelog creation", props_only=False) db.security.addPermissionToRole("User:timelog", perm) perm = db.security.addPermission(name='View', klass='issue', properties=('id', 'times'), description="Allow retrieving issue etag or timelog issue", props_only=False) db.security.addPermissionToRole("User:timelog", perm) perm = db.security.addPermission(name='Edit', klass='issue', properties=('id', 'times'), description="Allow editing timelog for issue", props_only=False) db.security.addPermissionToRole("User:timelog", perm) The role is named to work with the /rest/jwt/issue rest endpoint defined below. Starting the role name with ``User:`` allows the jwt issue code to create a token with this role if the user requesting the role has the User role. The role *must* have access to the issue ``id`` to retrieve the etag for the issue. The etag is passed in the ``If-Match`` HTTP header when you make a call to patch or update the ``times`` property of the issue. If you use a PATCH rest call with "@op=add" to append the new timelog, you don't need View access to the ``times`` property. If you replace the ``times`` value, you need to read the current value of ``times`` (using View permission), append the newly created timelog id to the (array) value, and replace the ``times`` value. Note that the json returned after the operation will include the new value of the ``times`` value so your code can verify that it worked. This leaks info about the previous id's in the field. Create rest endpoints ~~~~~~~~~~~~~~~~~~~~~ Here is code to add to your tracker's ``interfaces.py`` (note code has only been tested with python3):: from roundup.rest import Routing, RestfulInstance, _data_decorator class RestfulInstance(object): @Routing.route("/jwt/issue", 'POST') @_data_decorator def generate_jwt(self, input): """Create a JSON Web Token (jwt) """ import datetime import jwt from roundup.anypy.datetime_ import utcnow from roundup.anypy.strings import b2s # require basic auth to generate a token # At some point we can support a refresh token. # maybe a jwt with the "refresh": True claim generated # using: "refresh": True in the json request payload. denialmsg='Token creation requires login with basic auth.' if 'HTTP_AUTHORIZATION' in self.client.env: try: auth = self.client.env['HTTP_AUTHORIZATION'] scheme, challenge = auth.split(' ', 1) except (ValueError, AttributeError): # bad format for header raise Unauthorised(denialmsg) if scheme.lower() != 'basic': raise Unauthorised(denialmsg) else: raise Unauthorised(denialmsg) # verify we have input data. if not input: raise UsageError("Missing data payload. " "Verify Content-Type is sent") # If we reach this point we have validated that the user has # logged in with a password using basic auth. all_roles = list(self.db.security.role.items()) rolenames = [] for role in all_roles: rolenames.append(role[0]) user_roles = list(self.db.user.get_roles(self.db.getuid())) claim= { 'sub': self.db.getuid(), 'iss': self.db.config.TRACKER_WEB, 'aud': self.db.config.TRACKER_WEB, 'iat': utcnow(), } lifetime = 0 if 'lifetime' in input: if input['lifetime'].value != 'unlimited': try: lifetime = datetime.timedelta(seconds=int(input['lifetime'].value)) except ValueError: raise UsageError("Value 'lifetime' must be 'unlimited' or an integer to specify" + " lifetime in seconds. Got %s."%input['lifetime'].value) else: lifetime = datetime.timedelta(seconds=86400) # 1 day by default if lifetime: # if lifetime = 0 make unlimited by omitting exp claim claim['exp'] = utcnow() + lifetime newroles = [] if 'roles' in input: for role in [ r.lower() for r in input['roles'].value ]: if role not in rolenames: raise UsageError("Role %s is not valid."%role) if role in user_roles: newroles.append(role) continue parentrole = role.split(':', 1)[0] if parentrole in user_roles: newroles.append(role) continue raise UsageError("Role %s is not permitted."%role) claim['roles'] = newroles else: claim['roles'] = user_roles # Sign with newest/first secret. secret = self.db.config.WEB_JWT_SECRET[0] myjwt = jwt.encode(claim, secret, algorithm='HS256') # if jwt.__version__ >= 2.0.0 jwt.encode() returns string # not byte. So do not use b2s() with newer versions of pyjwt. result = {"jwt": b2s(myjwt), } return 200, result @Routing.route("/jwt/validate", 'GET') @_data_decorator def validate_jwt(self,input): import jwt if not 'jwt' in input: raise UsageError("jwt key must be specified") myjwt = input['jwt'].value secret = self.db.config.WEB_JWT_SECRET[0] # only return decoded result if the newest signing key # is used. Have older keys report an invalid signature. try: result = jwt.decode(myjwt, secret, algorithms=['HS256'], audience=self.db.config.TRACKER_WEB, issuer=self.db.config.TRACKER_WEB, ) except jwt.exceptions.InvalidTokenError as err: return 401, str(err) return 200, result **Note this is sample code. Use at your own risk.** It breaks a few rules about JWTs (e.g. it allows you to make unlimited lifetime JWTs). If you subscribe to the concept of JWT refresh tokens, this code will have to be changed as it will only generate JWTs with username/password authentication. Currently use of JWTs an experiment. If this appeals to you consider providing patches to existing code to: 1. create long lived refresh tokens 2. record all refresh tokens created by a user 3. using the record to allow refresh tokens to be revoked and ignored by the roundup core 4. provide a UI page for managing/revoking refresh tokens 5. provide a rest api for revoking refresh tokens These end points can be used like:: curl -u demo -s -X POST -H "Referer: https://.../demo/" \ -H "X-requested-with: rest" \ -H "Content-Type: application/json" \ --data '{"lifetime": "3600", "roles": [ "user:timelog" ] }' \ https://.../demo/rest/JWT/issue (note roles is a json array/list of strings not a string) to get:: { "data": { "JWT": "eyJ0eXAiOiJK......XxMDb-Q3oCnMpyhxPXMAk" } } The JWT is shortened in the example since it's large. You can validate a JWT to see if it's still valid using:: curl -s -H "Referer: https://.../demo/" \ -H "X-requested-with: rest" \ https://.../demo/rest/JWT/validate?JWT=eyJ0eXAiOiJK...XxMDb-Q3oCnMpyhxPXMAk (note no login is required) which returns:: { "data": { "user": "3", "roles": [ "user:timelog" ], "iss": "https://.../demo/", "aud": "https://.../demo/", "iat": 1569542404, "exp": 1569546004 } } There is an issue for `thoughts on JWT credentials`_ that you can view for ideas or add your own. .. _thoughts on JWT credentials: https://issues.roundup-tracker.org/issue2551064 Final steps ~~~~~~~~~~~ See the `upgrading directions`_ on how to use the ``updateconfig`` command to generate an updated copy of config.ini using roundup-admin. Then set the ``JWT_secret`` to at least 32 characters (more is better up to 512 bits). The output of ``openssl rand -base64 32`` will fulfill the minimum requirements. Writing an auditor that uses "db.user.get_roles" to see if the user making the change has the ``user:timelog`` role, and then comparing the original ``times`` list to the new list to verify that it is being added to and not changed otherwise is left as an exercise for the reader. (If you develop one, please contribute via the tracker: https://issues.roundup-tracker.org/.) Lastly you can create a JWT using the end point above and make a rest call to create a new timelog entry and another call to update the issues times property. If you have other ideas on how JWTs can be used, please share on the roundup mailing lists. See: https://sourceforge.net/p/roundup/mailman/ for directions on subscribing and for archives of the lists. Creating Custom Rate Limits --------------------------- You can replace the default rate limiter that is configured using the tracker's ``config.ini``. You can return different rate limits based on the user, time of day, phase of moon, request method (via self.client.request.command) etc. Assume you add two integer valued properties to the user object. Let's call them ``rate_limit_interval`` and ``rate_limit_calls``. Add code similar to this to interfaces.py to override the default rate limiter code:: from roundup.rest import RestfulInstance, RateLimit from datetime import timedelta def grl(self): calls = self.db.config.WEB_API_CALLS_PER_INTERVAL interval = self.db.config.WEB_API_INTERVAL_IN_SEC if calls and interval: # use to disable all rate limits uid = self.db.getuid() class_obj = self.db.getclass('user') node = class_obj.getnode(uid) # set value to 0 to use WEB_API_CALLS_PER_INTERVAL user_calls = node.__getattr__('rate_limit_calls') # set to 0 to use WEB_API_INTERVAL_IN_SEC user_interval = node.__getattr__('rate_limit_interval') return RateLimit(user_calls or calls, timedelta(seconds=(user_interval or interval))) else: # disable rate limiting if either parameter is 0 return None RestfulInstance.getRateLimit = grl this should replace the default getRateLimit with the new grl function. This new function uses values for the number of calls and period that are specific to a user. If either is set to 0, the defaults from ``config.ini`` file are used. Test Examples ~~~~~~~~~~~~~ Rate limit tests:: seq 1 300 | xargs -P 20 -n 1 curl --head -u user:password -si \ https://.../rest/data/status/new | grep Remaining will show you the number of remaining requests to the REST interface for the user identified by password. Notes V2 API ~~~~~~~~~~~~ These may never be implemented but, some nits to consider. The shape of a GET and PUT/PATCH responses are different. "attributes" is used for GET and "attribute" is used with PATCH/PUT. A PATCH or a PUT can update multiple properties when used with an item endpoint. "attribute" kind of makes sense when used with a property endpoint but.... Maybe standardize on one shape so the client doesn't have to special case? code-001c16ac87ec/doc/roundup-favicon.ico0000644000000000000000000000257615046233326016317 0ustar 00000000000000h( +++ttt )))rrrccc'''RRRnnn{{{lllNNN===...YYYHHHUUU ```QQQ$$$"""B .B+ 6BBBBBBBBBH /CHB14B%BBBB9 #BBB8:3GBBBF B05/%ABBBBK'7 -! BBBBBF"MBBBBBBBBIDMG2 2,BBBBBBBB(B5BBBBBBBBB&H6BBBBBBBBBBBBB*LEI+BBBBBBBBBIN*)BHJ0BBBBBBB5BH5NBBBBBB?????code-001c16ac87ec/doc/roundup-server.ini.example0000644000000000000000000000663515046233326017637 0ustar 00000000000000; This is a sample configuration file for roundup-server. See the ; admin_guide for information about its contents. [main] # Host name of the Roundup web server instance. # If left unconfigured (no 'host' setting) the default # will be used. # If empty, listen on all network interfaces. # If you want to explicitly listen on all # network interfaces, the address 0.0.0.0 is a more # explicit way to achieve this, the use of an empty # string for this purpose is deprecated and will go away # in a future release. # Default: localhost host = localhost # Port to listen on. # Default: 8080 port = 8017 # Path to favicon.ico image file. If unset, built-in favicon.ico is used. # The path may be either absolute or relative # to the directory containing this config file. # Default: favicon.ico favicon = favicon.ico # User ID as which the server will answer requests. # In order to use this option, the server must be run initially as root. # Availability: Unix. # Default: user = roundup # Group ID as which the server will answer requests. # In order to use this option, the server must be run initially as root. # Availability: Unix. # Default: group = # don't fork (this overrides the pidfile mechanism)' # Allowed values: yes, no # Default: no nodaemon = no # Log client machine names instead of IP addresses (much slower) # Allowed values: yes, no # Default: no log_hostnames = no # Have http(s) request logging done via python logger module. # If set to yes the python logging module is used with qualname # 'roundup.http'. Otherwise logging is done to stderr or the file # specified using the -l/logfile option. # Allowed values: yes, no # Default: no loghttpvialogger = no # File to which the server records the process id of the daemon. # If this option is not set, the server will run in foreground # # The path may be either absolute or relative # to the directory containing this config file. # Default: pidfile = # Log file path. If unset, log to stderr. # The path may be either absolute or relative # to the directory containing this config file. # Default: logfile = # Set processing of each request in separate subprocess. # Allowed values: debug, none, thread, fork. # Default: fork multiprocess = fork # Tracker index template. If unset, built-in will be used. # The path may be either absolute or relative # to the directory containing this config file. # Default: template = # Enable SSL support (requires pyopenssl) # Allowed values: yes, no # Default: no ssl = no # PEM file used for SSL. A temporary self-signed certificate # will be used if left blank. # The path may be either absolute or relative # to the directory containing this config file. # Default: pem = # Comma separated list of extra headers that should # be copied into the CGI environment. # E.G. if you want to access the REMOTE_USER and # X-Proxy-User headers in the back end, # set to the value REMOTE_USER,X-Proxy-User. # Allowed values: comma-separated list of words # Default: include_headers = # Change to HTTP/1.0 if needed. This disables keepalive. # Default: HTTP/1.1 http_version = HTTP/1.1 # Roundup trackers to serve. # Each option in this section defines single Roundup tracker. # Option name identifies the tracker and will appear in the URL. # Option value is tracker home directory path. # The path may be either absolute or relative # to the directory containing this config file. [trackers] demo = /trackers/demo sysadmin = /trackers/sysadmin code-001c16ac87ec/doc/sc.txt0000644000000000000000000000203015046233326013633 0ustar 00000000000000.. meta:: :description: Original documentation of the Roundup Issue tracker. Includes historic Software Carpentry submissions and a short paper. =================================== Software Carpentry and Short Papers =================================== These papers are the original artifacts of Roundup. They can't be included easily in the table of contents for the documentation, so they are referenced here. All of these were written by Ka-Ping Yee, the original architect of Roundup.. A few of the pages have been updated to correct links. However you may still have to use the `wayback machine `_ to access some of the links on these pages. The papers in chronological order are: * `A short paper explaining Roundup `_ * `The original overview document for Roundup submitted to the Software Carpentry competition `_ * `The original specification document for Roundup submitted to the Software Carpentry competition `_ code-001c16ac87ec/doc/security-history.txt0000644000000000000000000001215015046233326016600 0ustar 00000000000000.. meta:: :description: Security mechanism implementation document for historical purposes. :orphan: ============================= Old Security Mechanisms Notes ============================= Current situation ================= Current logical controls: ANONYMOUS_ACCESS = 'deny' Deny or allow anonymous access to the web interface ANONYMOUS_REGISTER = 'deny' Deny or allow anonymous users to register through the web interface ANONYMOUS_REGISTER_MAIL = 'deny' Deny or allow anonymous users to register through the mail interface Current user interface authentication and controls: - command-line tool access controlled with passwords, but no logical controls - CGI access is by username and password and has some logical controls - mailgw access is through identification using sender email address, with limited functionality available The web interface implements has specific logical controls, preventing non-admin users from accessing: - other user's details pages - listing the base classes (not issues or their user page) - editing base classes Issues ====== 1. The current implementation is ad-hoc, and not complete for all use cases. 2. Currently it is not possible to allow submission of issues through email but restrict those users from accessing the web interface. 3. Only one user may perform admin functions. 4. There is no verification of users in the mail gateway by any means other than the From address. Support for strong identification through digital signatures should be added. 5. The command-line tool has no logical controls. 6. The anonymous control needs revising - there should only be one way to be an anonymous user, not two (currently there is user==None and user=='anonymous'). Possible approaches =================== Security controls in Roundup could be approached in three ways: 1) at the hyperdb level, with read/write/modify permissions on classes, items and item properties for all or specific transitions. 2) at the user interface level, with access permissions on CGI interface methods, mailgw methods, roundup-admin methods, and so on. 3) at a logical permission level, checked as needed. In all cases, the security built into roundup assumes restricted access to the hyperdatabase itself, through operating-system controls such as user or group permissions. Hyperdb-level control --------------------- Control is implemented at the Class.get, Class.set and Class.create level. All other methods must access items through these methods. Since all accesses go through the database, we can implement deny by default. Pros: - easier to implement as it only affects one module - smaller number of permissions to worry about Cons: - harder to determine the relationship between user interaction and hyperdb permission. - a lot of work to define - must special-case to handle by-item permissions (editing user details, having private messages) User-interface control ---------------------- The user interfaces would have an extra layer between that which parses the request to determine action and the action method. This layer controls access. Since it is possible to require methods be registered with the security mechanisms to be accessed by the user, deny by default is possible. Pros: - much more obvious at the user level what the controls are Cons: - much more work to implement - most user interfaces have multiple uses which can't be covered by a single permission Logical control --------------- At each point that requires an action to be performed, the security mechanisms are asked if the current user has permission. Since code must call the check function to raise a denial, there is no possibility to have automatic default of deny in this situation. Pros: - quite obvious what is going on - is very similar to the current system Cons: - large number of possible permissions that may be defined, possibly mirroring actual user interface controls. - access to the hyperdb must be strictly controlled through program code that implements the logical controls. Action ====== The CGI interface must be changed to: - authenticate over a secure connection - use unique tokens as a result of authentication, rather than pass the user's real credentials (username/password) around for each request (this means sessions and hence a session database) - use the new logical control mechanisms - implement the permission module - implement a Role editing interface for users - implement htmltemplate tests on permissions - switch all code over from using config vars for permission checks to using permissions - change all explicit admin user checks for Role checks - include config vars for initial Roles for anonymous web, new web and new email users The mail gateway must be changed to: - use digital signatures - use the new logical control mechanisms - switch all code over from using config vars for permission checks to using permissions The command-line tool must be changed to: - use the new logical control mechanisms (only allowing write access by admin users, and read-only by everyone else) code-001c16ac87ec/doc/security.txt0000644000000000000000000001514715046233326015112 0ustar 00000000000000.. meta:: :description: Documentation on how to report security issues with Roundup. Index to recent security related (CVE) descriptions in other Roundup documentation. How to verify distribution using gpg. .. index:: single: Reporting Security Issues single: CVE announcements single: Security Issues, Reporting single: Security Issues, Remediation single: Security Issues, CVE announcements ======================= Roundup Security Issues ======================= This page documents CVE's fixed starting with version 2.4.0, how to report security issues, and verify the signatures for Roundup source release tarballs. .. contents:: :local: :depth: 2 CVE Announcements ----------------- * `CVE-2025-53865`_ - :ref:`XSS security issue with devel or responsive templates `. Fixed in release 2.5.0, directions available for fixing trackers based on these templates. * `CVE-2024-39124`_ - :ref:`classhelpers (_generic.help.html) are vulnerable to an XSS attack. ` Requires fixing tracker homes. * `CVE-2024-39125`_ - :ref:`if Referer header is set to a script tag, it will be executed. ` Fixed in release 2.4.0, directions available for fixing in prior versions. * `CVE-2024-39126`_ - :ref:`PDF, XML and SVG files downloaded from an issue can contain embedded JavaScript which is executed. ` Fixed in release 2.4.0, directions available for fixing in prior versions. .. _CVE-2025-53865: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2025-53865 .. _CVE-2024-39124: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-39124 .. _CVE-2024-39125: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-39125 .. _CVE-2024-39126: https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2024-39126 Reporting Security Issues ------------------------- Security issues with Roundup should be reported by email to: rouilj@users.sourceforge.net (John Rouillard) rsc@runtux.com (Ralf Schlatterbeck) If these fail, you can find rouilj on irc in channel #roundup at irc.oftc.net (see Contact_ for more directions and web interface). Methods listed at Contact_ are all public, so they should be used to contact somebody with the Roundup project for establishing a proper method of reporting the security issue. .. _Contact: https://www.roundup-tracker.org/contact.html Verify Source Tarball --------------------- .. index:: single: Distribution, verify with gpg single: Signature, verify If you download the source tarball using ``python3 -m pip download roundup`` or from https://pypi.org/project/roundup/#files you can verify the file using gpg. This is the information on the public PGP/GPG key used to sign Roundup distributions. It is used to sign the 1.6.0, 2.2.0, and newer releases. (Note that the @ sign in email addresses have been replaced with the word "at" to reduce spam directed at the mailing list.):: Key info: Roundup Team (signing key for roundup releases) Expires: 2028-07-17 Key fingerprint = 411E 354B 5D1A F261 25D6 2122 1F2D D0CB 756A 76D8 Releases 1.6.1, 2.0.0 and 2.1.0 were accidentally signed with this key [1]_:: Key info: John Rouillard (Roundup Release Key) Expires: 2023-07-09 Key fingerprint = A1E6 364E 9429 E9D8 2B3B 2373 DB05 ADC4 2330 5876 .. [1] Use gpg to import this key from the keyserver pgp.mit.edu if you need to verify one of these releases. Use the gpg pgp.mit.edu keyserver example replacing the key fingerprint with the one starting A1E6. Importing the Public Key ~~~~~~~~~~~~~~~~~~~~~~~~ This only has to be added to your keyring once. You can import a key from pgp.mit.edu using:: gpg --keyserver pgp.mit.edu --receive-keys 411E354B5D1AF26125D621221F2DD0CB756A76D8 where the fingerprint (without spaces) is used to identify which key to receive. You can also extract and import the file ``tools/roundup.public.pgp.key`` from the download source tarball using:: tar -xzvf roundup-2.2.0.tar.gz -O \ roundup-2.2.0/tools/roundup.public.pgp.key > pub.key gpg --import pub.key Once you have loaded the public key, you need a detached signature for your release. Download Detached Signature and Verify ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This needs to be done once for each release you wish to verify. The Python Package Index (PyPI) used to support uploading gpg detached signatures. However that is no longer supported and downloading existing signatures may not work in the future. As a result, the signatures for all Roundup final releases starting with 1.6.0 have been moved and are linked below: .. rst-class:: multicol * `2.5.0 <../signatures/roundup-2.5.0.tar.gz.asc>`_ * `2.4.0 <../signatures/roundup-2.4.0.tar.gz.asc>`_ * `2.4.0b2 <../signatures/roundup-2.4.0b2.tar.gz.asc>`_ * `2.3.0 <../signatures/roundup-2.3.0.tar.gz.asc>`_ * `2.3.0b2 <../signatures/roundup-2.3.0b2.tar.gz.asc>`_ * `2.2.0 <../signatures/roundup-2.2.0.tar.gz.asc>`_ * `2.1.0 <../signatures/roundup-2.1.0.tar.gz.asc>`_ * `2.0.0 <../signatures/roundup-2.0.0.tar.gz.asc>`_ * `1.6.1 <../signatures/roundup-1.6.1.tar.gz.asc>`_ * `1.6.0 <../signatures/roundup-1.6.0.tar.gz.asc>`_ To use the signature, download the correct versioned link and verify it with (note 1.5.7 is a dummy version, use the correct version number):: gpg --verify roundup-1.5.7.tar.gz.asc roundup-1.5.7.tar.gz You should see:: gpg: Signature made Wed 13 Jul 2022 12:24:14 AM EDT gpg: using RSA key 411E354B5D1AF26125D621221F2DD0CB756A76D8 gpg: Good signature from "Roundup Team (signing key for roundup releases) " [unknown] gpg: WARNING: This key is not certified with a trusted signature! gpg: There is no indication that the signature belongs to the owner. Primary key fingerprint: 411E 354B 5D1A F261 25D6 2122 1F2D D0CB 756A 76D8 which verifies the tarball integrity. The WARNING is expected. The date should be close to the release date of the version of Roundup. As long as you see the output starting with "Good signature from" followed by the Key Info above, everything is OK. If something is wrong you will see:: gpg: Signature made Wed 13 Jul 2022 12:24:14 AM EDT gpg: using RSA key 411E354B5D1AF26125D621221F2DD0CB756A76D8 gpg: BAD signature from "Roundup Team (signing key for roundup releases) " **do not use** the tarball if the signature is BAD. Email the mailing list: roundup-devel at lists.sourceforge.net if you have this happen to you. code-001c16ac87ec/doc/tracker_config.txt0000644000000000000000000013165315046233326016224 0ustar 00000000000000 .. index:: config.ini; sections main .. _`config-ini-section-main`: .. code:: ini [main] # Database directory path. # The path may be either absolute or relative # to the directory containing this config file. # Default: db database = db # Templating engine to use. # Possible values are: # 'zopetal' for the old TAL engine ported from Zope, # 'chameleon' for Chameleon, # 'jinja2' for jinja2 templating. # Available found jinja2 module. # Default: zopetal template_engine = zopetal # Path to the HTML templates directory. # The path may be either absolute or relative # to the directory containing this config file. # Default: html templates = html # A list of space separated directory paths (or a single # directory). These directories hold additional public # static files available via Web UI. These directories # may contain sitewide images, CSS stylesheets etc. If a # '-' is included, the list processing ends and the # TEMPLATES directory is not searched after the specified # directories. If this option is not set, all static # files are taken from the TEMPLATES directory. Access to # these files is public, it is not checked against # registered users. So do not put any sensitive data in # the files in these directories. # The space separated paths may be either absolute # or relative to the directory containing this config file. # Default: static_files = # Email address that roundup will complain to if it runs # into trouble. # If no domain is specified then the config item # mail -> domain is added. # Default: roundup-admin admin_email = roundup-admin # The 'dispatcher' is a role that can get notified # when errors occur while sending email to a user. # It is used by the ERROR_MESSAGES_TO config setting. # If no domain is specified then the config item # mail -> domain is added. # Default: roundup-admin dispatcher_email = roundup-admin # 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" # Default: email_from_tag = # Roles that a user gets when they register # with Web User Interface. # This is a comma-separated string of role names # (e.g. 'Admin,User'). # Default: User new_web_user_roles = User # Roles that a user gets when they register # with Email Gateway. # This is a comma-separated string of role names # (e.g. 'Admin,User'). # Default: User new_email_user_roles = User # On schema changes, properties or classes in the history may # become obsolete. Since normal access permissions do not apply # (we don't know if a user should see such a property or class) # a list of roles is specified here that are allowed to see # these obsolete properties in the history. By default only the # admin role may see these history entries, you can make them # visible to all users by adding, e.g., the 'User' role here. # Default: Admin obsolete_history_roles = Admin # Send error message emails to the "dispatcher", "user", # or "both" (these are the three allowed values). # The dispatcher is configured using the DISPATCHER_EMAIL # setting. # Default: user error_messages_to = user # This setting should be left at the default value of html4. # Support for xhtml has been disabled. # HTML version to generate. The templates are html4 by default. # Allowed values: html4 # Default: html4 html_version = html4 # Default timezone offset, # applied when user's timezone is not set. # If pytz module is installed, value may be any valid # timezone specification (e.g. EET or Europe/Warsaw). # If pytz is not installed, value must be integer number # giving local timezone offset from UTC in hours. # Default: UTC timezone = UTC # Register new users instantly, or require confirmation via # email? # Allowed values: yes, no # Default: no instant_registration = no # Offer registration confirmation by email or only # through the web? # Allowed values: yes, no # Default: yes email_registration_confirmation = yes # Force Roundup to use a particular text indexer. # If no indexer is supplied, the first available indexer # will be used in the following order: # Possible values: xapian, whoosh, native (internal), native-fts. # Note 'native-fts' will only be used if set. # Allowed values: '', 'xapian', 'whoosh', 'native', 'native-fts' # Default: indexer = # Used to determine what language should be used by the # indexer above. Applies to Xapian and PostgreSQL native-fts # indexer. It sets the language for the stemmer, and PostgreSQL # native-fts stopwords and other dictionaries. # Possible values: must be a valid language for the indexer, # see indexer documentation for details. # Default: english indexer_language = english # Additional stop-words for the full-text indexer specific to # your tracker. See the indexer source for the default list of # stop-words (eg. A,AND,ARE,AS,AT,BE,BUT,BY, ...). This is # not used by the postgres native-fts indexer. But is used to # filter search terms with the sqlite native-fts indexer. # Allowed values: comma-separated list of words # Default: indexer_stopwords = # Defines the file creation mode mask. # Default: 0o2 umask = 0o2 # Maximum size of a csv-field during import. Roundups export # format is a csv (comma separated values) variant. The csv # reader has a limit on the size of individual fields # starting with python 2.5. Set this to a higher value if you # get the error 'Error: field larger than field limit' during # import. # Default: 131072 csv_field_size = 131072 # Sets the default number of rounds used when encoding passwords # using any PBKDF2 scheme. Set this to a higher value on faster # systems which want more security. Use a minimum of 250000 # for PBKDF2-SHA512 which is the default hash in Roundup 2.5. # PBKDF2 (Password-Based Key Derivation Function) is a # password hashing mechanism that derives hash from the # password and a random salt. For authentication this process # is repeated with the same salt as in the stored hash. # If both hashes match, the authentication succeeds. # PBKDF2 supports a variable 'rounds' parameter which varies # the time-cost of calculating the hash - doubling the number # of rounds doubles the cpu time required to calculate it. The # purpose of this is to periodically adjust the rounds as CPUs # become faster. The currently enforced minimum number of # rounds is 1000. # See: http://en.wikipedia.org/wiki/PBKDF2 and RFC2898 # Default: 250000 password_pbkdf2_default_rounds = 250000 .. index:: config.ini; sections tracker .. _`config-ini-section-tracker`: .. code:: ini [tracker] # A descriptive name for your roundup instance. # Default: Roundup issue tracker name = Roundup issue tracker # 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. # URL MUST start with http/https scheme and end with '/' # Default: NO DEFAULT #web = NO DEFAULT # Email address that mail to roundup should go to. # If no domain is specified then mail_domain is added. # Default: issue_tracker email = issue_tracker # Controls the reply-to header address used when sending # nosy messages. # If the value is unset (default) the roundup tracker's # email address (above) is used. # If set to "AUTHOR" then the primary email address of the # author of the change will be used as the reply-to # address. This allows email exchanges to occur outside of # the view of roundup and exposes the address of the person # who updated the issue, but it could be useful in some # unusual circumstances. # If set to some other value, the value is used as the reply-to # address. It must be a valid RFC2822 address or people will not # be able to reply. # Default: replyto_address = # Default locale name for this tracker. # If this option is not set, the language is determined # by OS environment variable LANGUAGE, LC_ALL, LC_MESSAGES, # or LANG, in that order of preference. # Default: language = .. index:: config.ini; sections web .. _`config-ini-section-web`: .. code:: ini [web] # Setting this option enables Roundup to serve uploaded HTML # file content *as HTML*. This is a potential security risk # and is therefore disabled by default. Set to 'yes' if you # trust *all* users uploading content to your tracker. # Allowed values: yes, no # Default: no allow_html_file = no # Whether to use HTTP Basic Authentication, if present. # Roundup will use either the REMOTE_USER (the value set # by http_auth_header) or HTTP_AUTHORIZATION # variables supplied by your web server (in that order). # Set this option to 'no' if you do not wish to use HTTP Basic # Authentication in your web interface. # Allowed values: yes, no # Default: yes http_auth = yes # The HTTP header that holds the user authentication information. # If empty (default) the REMOTE_USER header is used. # This is used when the upstream HTTP server authenticates # the user and passes the username using this HTTP header. # Default: http_auth_header = # Setting this option makes roundup look at the Accept-Encoding # header supplied by the client. It will compress the response # on the fly using a common encoding. Disable it if your # upstream server does compression of dynamic data. # Allowed values: yes, no # Default: yes dynamic_compression = yes # Setting this option enables Roundup to serve precompressed # static files. The admin must create the compressed files with # proper extension (.gzip, .br, .zstd) in the same directory as # the uncompressed file. If a precompressed file doesn't # exist, the uncompressed file will be served possibly with # dynamic compression. # Allowed values: yes, no # Default: no use_precompressed_files = no # If usernames consist of a name and a domain/realm part of # the form user@realm and we're using REMOTE_USER for # authentication (e.g. via Kerberos), convert the realm part # of the incoming REMOTE_USER to lowercase before matching # against the roundup username. This allows roundup usernames # to be lowercase (including the realm) and still follow the # Kerberos convention of using an uppercase realm. In # addition this is compatible with Active Directory which # stores the username with realm as UserPrincipalName in # lowercase. # Allowed values: yes, no # Default: no http_auth_convert_realm_to_lowercase = no # If the http_auth option is in effect (see above) # we're accepting a REMOTE_USER variable resulting from # an authentication mechanism implemented in the web-server, # e.g., Kerberos login or similar. To override the mechanism # provided by the web-server (e.g. for enabling sub-login as # another user) we tell roundup that the cookie takes # precedence over a REMOTE_USER or HTTP_AUTHORIZATION # variable. So if both, a cookie and a REMOTE_USER is # present, the cookie wins. # # Allowed values: yes, no # Default: no cookie_takes_precedence = no # Limit login attempts per user per minute to this number. # By default the 4th login attempt in a minute will notify # the user that they need to wait 20 seconds before trying to # log in again. This limits password guessing attacks and # shouldn't need to be changed. Rate limiting on login can # be disabled by setting the value to 0. # Default: 3 login_attempts_min = 3 # The number of seconds needed to complete the new user # registration form. This limits the rate at which bots # can attempt to sign up. Limit can be disabled by setting # the value to 0. # Default: 4 registration_delay = 4 # When registering a user, check that the username # is available before sending confirmation email. # Usually a username conflict is detected when # confirming the registration. Disabled by default as # it can be used for guessing existing usernames. # # Allowed values: yes, no # Default: no registration_prevalidate_username = no # Set the mode of the SameSite cookie option for # the session cookie. Choices are 'Lax' or # 'Strict'. 'None' can be used to suppress the # option. Strict mode provides additional security # against CSRF attacks, but may confuse users who # are logged into roundup and open a roundup link # from a source other than roundup (e.g. link in # email). # Allowed values: Strict, Lax, None # Default: Lax samesite_cookie_setting = Lax # Whether to enable the XMLRPC API in the roundup web # interface. By default the XMLRPC endpoint is the string # 'xmlrpc' after the roundup web url configured in the # 'tracker' section. If this variable is set to 'no', the # xmlrpc path has no special meaning and will yield an # error message. # Allowed values: yes, no # Default: yes enable_xmlrpc = yes # Whether to enable i18n for the xmlrpc endpoint. Enable it if # you want to enable translation based on browsers lang # (if enabled), trackers lang (if set) or environment. # Allowed values: yes, no # Default: no translate_xmlrpc = no # Whether to enable the REST API in the roundup web # interface. By default the REST endpoint is the string # 'rest' plus any additional REST-API parameters after the # roundup web url configured in the tracker section. If this # variable is set to 'no', the rest path has no special meaning # and will yield an error message. # Allowed values: yes, no # Default: yes enable_rest = yes # Whether to enable i18n for the rest endpoint. Enable it if # you want to enable translation based on browsers lang # (if enabled), trackers lang (if set) or environment. # Allowed values: yes, no # Default: no translate_rest = no # Log-Level for REST errors. # Allowed values: none, debug, info, warning, error, critical # Default: none rest_logging = none # Limit API calls per api_interval_in_sec seconds to # this number. # Determines the burst rate and the rate that new api # calls will be made available. If set to 360 and # api_intervals_in_sec is set to 3600, the 361st call in # 10 seconds results in a 429 error to the caller. It # tells them to wait 10 seconds (3600/360) before making # another api request. A value of 0 turns off rate # limiting in the API. Tune this as needed. See rest # documentation for more info. # # Default: 0 api_calls_per_interval = 0 # Defines the interval in seconds over which an api client can # make api_calls_per_interval api calls. Tune this as needed. # # Default: 3600 api_interval_in_sec = 3600 # Limit login failure to the API per api_failed_login_interval_in_sec # seconds. # A value of 0 turns off failed login rate # limiting in the API. You should not disable this. See rest # documentation for more info. # # Default: 4 api_failed_login_limit = 4 # Defines the interval in seconds over which api login failures # are recorded. It allows api_failed_login_limit login failures # in this time interval. Tune this as needed. # # Default: 600 api_failed_login_interval_in_sec = 600 # How do we deal with @csrf fields in posted forms. # Set this to 'required' to block the post and notify # the user if the field is missing or invalid. # Set this to 'yes' to block the post and notify the user # if the token is invalid, but accept the form if # the field is missing. # Set this to 'logfailure' to log a notice to the roundup # log if the field is invalid or missing, but accept # the post. # Set this to 'no' to ignore the field and accept the post. # # Allowed values: required, yes, logfailure, no # Default: yes csrf_enforce_token = yes # csrf_tokens have a limited lifetime. If they are not # used they are purged from the database after this # number of minutes. Default (20160) is 2 weeks. # Default: 20160 csrf_token_lifetime = 20160 # This is only used for xmlrpc and rest requests. This test is # done after Origin and Referer headers are checked. It only # verifies that the X-Requested-With header exists. The value # is ignored. # Set this to 'required' to block the post and notify # the user if the header is missing or invalid. # Set this to 'yes' is the same as required. # Set this to 'logfailure' is the same as 'no'. # Set this to 'no' to ignore the header and accept the post. # Allowed values: required, yes, logfailure, no # Default: yes csrf_enforce_header_x-requested-with = yes # Verify that the Referer http header matches the # tracker.web setting in config.ini. # Set this to 'required' to block the post and notify # the user if the header is missing or invalid. # Set this to 'yes' to block the post and notify the user # if the header is invalid, but accept the form if # the header is missing. # Set this to 'logfailure' to log a notice to the roundup # log if the header is invalid or missing, but accept # the post. # Set this to 'no' to ignore the header and accept the post. # Allowed values: required, yes, logfailure, no # Default: yes csrf_enforce_header_referer = yes # Verify that the Origin http header matches the # tracker.web setting in config.ini. # Set this to 'required' to block the post and notify # the user if the header is missing or invalid. # Set this to 'yes' to block the post and notify the user # if the header is invalid, but accept the form if # the header is missing. # Set this to 'logfailure' to log a notice to the roundup # log if the header is invalid or missing, but accept # the post. # Set this to 'no' to ignore the header and accept the post. # Allowed values: required, yes, logfailure, no # Default: yes csrf_enforce_header_origin = yes # A comma separated list of additonal valid Origin header # values used when enforcing the header origin. They are used # only for the api URL's (/rest and /xmlrpc). They are not # used for the usual html URL's. These strings must match the # value of the Origin header exactly. So 'https://bar.edu' and # 'https://Bar.edu' are two different Origin values. Note that # the origin value is scheme://host. There is no path # component. So 'https://bar.edu/' would never be valid. # The value '*' can be used to match any origin. It must be # first in the list if used. Note that this value allows # any web page on the internet to make anonymous requests # against your Roundup tracker. # # You need to set these if you have a web application on a # different origin accessing your Roundup instance. # # (The origin from the tracker.web setting in config.ini is # always valid and does not need to be specified.) # A list of space separated case sensitive # origin headers 'scheme://host'. # Default: allowed_api_origins = # Verify that the X-Forwarded-Host http header matches # the host part of the tracker.web setting in config.ini. # Set this to 'required' to block the post and notify # the user if the header is missing or invalid. # Set this to 'yes' to block the post and notify the user # if the header is invalid, but accept the form if # the header is missing. # Set this to 'logfailure' to log a notice to the roundup # log if the header is invalid or missing, but accept # the post. # Set this to 'no' to ignore the header and accept the post. # Allowed values: required, yes, logfailure, no # Default: yes csrf_enforce_header_x-forwarded-host = yes # "If there is no X-Forward-Host header, verify that # the Host http header matches the host part of the # tracker.web setting in config.ini. # Set this to 'required' to block the post and notify # the user if the header is missing or invalid. # Set this to 'yes' to block the post and notify the user # if the header is invalid, but accept the form if # the header is missing. # Set this to 'logfailure' to log a notice to the roundup # log if the header is invalid or missing, but accept # the post. # Set this to 'no' to ignore the header and accept the post. # Allowed values: required, yes, logfailure, no # Default: yes csrf_enforce_header_host = yes # Minimum number of header checks that must pass # to accept the request. Set to 0 to accept post # even if no header checks pass. Usually the Host header check # always passes, so setting it less than 1 is not recommended. # Default: 1 csrf_header_min_count = 1 # Whether to use HTTP Accept-Language, if present. # Browsers send a language-region preference list. # It's usually set in the client's browser or in their # Operating System. # Set this option to 'no' if you want to ignore it. # Allowed values: yes, no # Default: yes use_browser_language = yes # Setting this option makes Roundup display error tracebacks # in the user's browser rather than emailing them to the # tracker admin. # Allowed values: yes, no # Default: no debug = no # Setting this option to yes/true allows users with # an empty/blank password to login to the # web/http interfaces. # Allowed values: yes, no # Default: no login_empty_passwords = no # Setting this option makes Roundup migrate passwords with # an insecure password-scheme to a more secure scheme # when the user logs in via the web-interface. # Allowed values: yes, no # Default: yes migrate_passwords = yes # A per tracker secret used in etag calculations for # an object. It must not be empty. # It prevents reverse engineering hidden data in an object # by calculating the etag for a sample object. Then modifying # hidden properties until the sample object's etag matches # the one returned by roundup. # Changing this changes the etag and invalidates updates by # clients. It must be persistent across application restarts. # (Note the default value changes every time # roundup-admin updateconfig # is run, so it must be explicitly set to a non-empty string. # # A string that starts with 'file://' is interpreted # as a file path relative to the tracker home. Using # 'file:///' defines an absolute path. The first # line of the file will be used as the value. Any # string that does not start with 'file://' is used # as is. It removes any whitespace at the end of the # line, so a newline can be put in the file. # # Default: DWmbKgVUy6fF5D2Y5TD5Az+dnHhMYKCCpJzIY3H8nsU= secret_key = DWmbKgVUy6fF5D2Y5TD5Az+dnHhMYKCCpJzIY3H8nsU= # This is used to sign/validate json web tokens # (JWT). Even if you don't use JWTs it must not be # empty. You can use multiple secrets separated by a # comma ','. This allows for secret rotation. The newest # secret should be placed first and used for signing. The # rest of the secrets are used for validating an old JWT. # If the first secret is less than 256 bits (32 # characters) in length JWTs are disabled. If other secrets # are less than 32 chars, the application will exit. Removing # a secret from this list invalidates all JWTs signed with # the secret. JWT support is experimental and disabled by # default. The secrets must be persistent across # application restarts. # # A string that starts with 'file://' is interpreted # as a file path relative to the tracker home. Using # 'file:///' defines an absolute path. The first # line of the file will be used as the value. Any # string that does not start with 'file://' is used # as is. It removes any whitespace at the end of the # line, so a newline can be put in the file. # # Default: disabled jwt_secret = disabled # HTML input elements for Date properties: This determines # if we use the input type 'datetime-local' (or 'date') for # date input fields. If the option is turned off (the default), # the type is set to 'text'. Since the widgets generated by # browsers determine the date format from the language # setting (it is currently not possible to force the # international date format server-side) and some browsers # ignore the date format set by the operating system, the # default is 'no'. # Allowed values: yes, no # Default: no use_browser_date_input = no # HTML input elements for Number properties: This determines # if we use the input type 'number' for Number (and Integer) # properties. If set to 'no' we use input type 'text'. # Allowed values: yes, no # Default: no use_browser_number_input = no .. index:: config.ini; sections rdbms .. _`config-ini-section-rdbms`: .. code:: ini # Most settings in this section (except for backend and debug_filter) # are used by RDBMS backends only. [rdbms] # Database backend. # Available backends: anydbm, mysql, sqlite, postgresql # Default: NO DEFAULT #backend = NO DEFAULT # Filter debugging: Permissions can define additional filter # functions that are used when checking permissions on results # returned by the database. This is done to improve # performance since the filtering is done in the database # backend, not in python (at least for the SQL backends). The # user is responsible for making the filter return the same # set of results as the check function for a permission. So it # makes sense to aid in debugging (and performance # measurements) to allow turning off the usage of filter # functions using only the check functions. # Allowed values: yes, no # Default: no debug_filter = no # Name of the database to use. For Postgresql, this can # be database.schema to use a specific schema within # a Postgres database. # Default: roundup name = roundup # Database server host. # Default: localhost host = localhost # TCP port number of the database server. # Postgresql usually resides on port 5432 (if any), # for MySQL default port number is 3306. # Leave this option empty to use backend default # Default: port = # Database user name that Roundup should use. # Default: roundup user = roundup # Database user password. # A string that starts with 'file://' is interpreted # as a file path relative to the tracker home. Using # 'file:///' defines an absolute path. The first # line of the file will be used as the value. Any # string that does not start with 'file://' is used # as is. It removes any whitespace at the end of the # line, so a newline can be put in the file. # # Default: roundup password = roundup # Name of the PostgreSQL connection service for this Roundup # instance. Only used in Postgresql connections. You need to set # up a pg_service.conf file usable by psql use this option. # Default: service = # Name of the MySQL defaults file. # Only used in MySQL connections. # Default: ~/.my.cnf read_default_file = ~/.my.cnf # Name of the group to use in the MySQL defaults file (.my.cnf). # Only used in MySQL connections. # Default: roundup read_default_group = roundup # Charset to use for mysql connection and databases. # If set to 'default', no charset option is used when # creating the db connection and utf8mb4 is used for the # database charset. # Otherwise any permissible mysql charset is allowed here. # Only used in MySQL connections. # Default: utf8mb4 mysql_charset = utf8mb4 # Comparison/order to use for mysql database/table collations. # When upgrading, you can use 'utf8' to match the # depricated 'utf8mb3'. This must be compatible with the # mysql_charset setting above. Only used by MySQL. # Default: utf8mb4_unicode_ci mysql_collation = utf8mb4_unicode_ci # Comparison/order to use for mysql database/table collations # when matching case. When upgrading, you can use 'utf8_bin' # to match the depricated 'utf8mb3_bin' collation. This must # be compatible with the mysql_collation above. Only used # by MySQL. # Default: utf8mb4_0900_bin mysql_binary_collation = utf8mb4_0900_bin # Number of seconds to wait when the SQLite database is locked # Default: use a 30 second timeout (extraordinarily generous) # Only used in SQLite connections. # Default: 30 sqlite_timeout = 30 # Size of the node cache (in elements). Used to keep the # most recently used data in memory. # Default: 100 cache_size = 100 # Setting this option to 'no' protects the database against # table creations. # Allowed values: yes, no # Default: yes allow_create = yes # Setting this option to 'no' protects the database against # table alterations. # Allowed values: yes, no # Default: yes allow_alter = yes # Setting this option to 'no' protects the database against # table drops. # Allowed values: yes, no # Default: yes allow_drop = yes # Name of the PostgreSQL template for database creation. # For database creation the template used has to match # the character encoding used (UTF8), there are different # PostgreSQL installations using different templates with # different encodings. If you get an error: # new encoding (UTF8) is incompatible with the encoding of # the template database (SQL_ASCII) # HINT: Use the same encoding as in the template database, # or use template0 as template. # then set this option to the template name given in the # error message. # Default: template = # Database isolation level, currently supported for # PostgreSQL and mysql. See, e.g., # http://www.postgresql.org/docs/9.1/static/transaction-iso.html # Allowed values: 'read uncommitted', 'read committed', 'repeatable read', 'serializable' # Default: read committed isolation_level = read committed # Set the database cursor for filter queries to serverside # cursor, this avoids caching large amounts of data in the # client. This option only applies for the postgresql backend. # Allowed values: yes, no # Default: yes serverside_cursor = yes .. index:: config.ini; sections sessiondb .. _`config-ini-section-sessiondb`: .. code:: ini # Choose configuration for session and one time key storage. [sessiondb] # Set backend for storing one time key (otk) and session data. # Values have to be compatible with main backend. # main\/ session>| anydbm | sqlite | redis | mysql | postgresql | # anydbm | D | | X | | | # sqlite | X | D | X | | | # mysql | | | | D | | # postgresql | | | | | D | # -------------------------------------------------------------+ # D - default if unset, X - compatible choice # Default: backend = # URL used to connect to redis. Default uses unauthenticated # redis database 0 running on localhost with default port. # # A string that starts with 'file://' is interpreted # as a file path relative to the tracker home. Using # 'file:///' defines an absolute path. The first # line of the file will be used as the value. Any # string that does not start with 'file://' is used # as is. It removes any whitespace at the end of the # line, so a newline can be put in the file. # # Default: redis://localhost:6379/0?health_check_interval=2 redis_url = redis://localhost:6379/0?health_check_interval=2 .. index:: config.ini; sections logging .. _`config-ini-section-logging`: .. code:: ini [logging] # Path to configuration file for standard Python logging module. # If this option is set, logging configuration is loaded # from specified file; options 'filename' and 'level' # in this section are ignored. # The path may be either absolute or relative # to the directory containing this config file. # Default: config = # Log file name for minimal logging facility built into Roundup. # If no file name specified, log messages are written on stderr. # If above 'config' option is set, this option has no effect. # The path may be either absolute or relative # to the directory containing this config file. # Default: filename = # Minimal severity level of messages written to log file. # If above 'config' option is set, this option has no effect. # Allowed values: DEBUG, INFO, WARNING, ERROR # Default: ERROR level = ERROR # If set to yes, only the loggers configured in this section will # be used. Yes will disable gunicorn's --access-logfile. # # Allowed values: yes, no # Default: no disable_loggers = no .. index:: config.ini; sections mail .. _`config-ini-section-mail`: .. code:: ini # Outgoing email options. # Used for nosy messages, password reset and registration approval # requests. [mail] # The email domain that admin_email, issue_tracker and # dispatcher_email belong to. # This domain is added to those config items if they don't # explicitly include a domain. # Do not include the '@' symbol. # Default: NO DEFAULT #domain = NO DEFAULT # SMTP mail host that roundup will use to send mail # Default: NO DEFAULT #host = NO DEFAULT # SMTP login name. # Set this if your mail host requires authenticated access. # If username is not empty, password (below) MUST be set! # Default: username = # SMTP login password. # Set this if your mail host requires authenticated access. # A string that starts with 'file://' is interpreted # as a file path relative to the tracker home. Using # 'file:///' defines an absolute path. The first # line of the file will be used as the value. Any # string that does not start with 'file://' is used # as is. It removes any whitespace at the end of the # line, so a newline can be put in the file. # # Default: NO DEFAULT #password = NO DEFAULT # Default port to send SMTP on. # Set this if your mail server runs on a different port. # Default: 25 port = 25 # The (fully qualified) host/ domain name (FQDN) to use during # SMTP sessions. If left blank, the underlying SMTP library will # attempt to detect your FQDN. Set this if your mail server # requires something specific. # # Default: local_hostname = # If your SMTP mail host provides or requires TLS # (Transport Layer Security) then set this option to 'yes'. # Allowed values: yes, no # Default: no tls = no # If TLS is used, you may set this option to the name # of a PEM formatted file that contains your private key. # The path may be either absolute or relative # to the directory containing this config file. # Default: tls_keyfile = # If TLS is used, you may set this option to the name # of a PEM formatted certificate chain file. # The path may be either absolute or relative # to the directory containing this config file. # Default: tls_certfile = # 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: utf-8 charset = utf-8 # Setting this option makes Roundup write all outgoing email # messages to this file *instead* of sending them. # This option has the same effect as the environment variable # SENDMAILDEBUG. # Environment variable takes precedence. # The path may be either absolute or relative # to the directory containing this config file. # Default: debug = # Add a line with author information at top of all messages # sent by roundup # Allowed values: yes, no # Default: yes add_authorinfo = yes # Add the mail address of the author to the author information # at the top of all messages. # If this is false but add_authorinfo is true, only the name # of the actor is added which protects the mail address of the # actor from being exposed at mail archives, etc. # Allowed values: yes, no # Default: yes add_authoremail = yes .. index:: config.ini; sections mailgw .. _`config-ini-section-mailgw`: .. code:: ini # Roundup Mail Gateway options [mailgw] # Keep email citations when accepting messages. # Setting this to "no" strips out "quoted" text # from the message. Setting this to "new" keeps quoted # text only if a new issue is being created. # Signatures are also stripped. # Allowed values: yes, no, new # Default: yes keep_quoted_text = yes # Setting this to "yes" preserves the email body # as is - that is, keep the citations _and_ signatures. # Setting this to "new" keeps the body only if we are # creating a new issue. # Allowed values: yes, no, new # Default: no leave_body_unchanged = no # Default class to use in the mailgw # if one isn't supplied in email subjects. # To disable, leave the value blank. # Default: issue default_class = issue # Default locale name for the tracker mail gateway. # If this option is not set, mail gateway will use # the language of the tracker instance. # Default: language = # Controls the parsing of the [prefix] on subject # lines in incoming emails. "strict" will return an # error to the sender if the [prefix] is not recognised. # "loose" will attempt to parse the [prefix] but just # pass it through as part of the issue title if not # recognised. "none" will always pass any [prefix] # through as part of the issue title. # Default: strict subject_prefix_parsing = strict # Controls the parsing of the [suffix] on subject # lines in incoming emails. "strict" will return an # error to the sender if the [suffix] is not recognised. # "loose" will attempt to parse the [suffix] but just # pass it through as part of the issue title if not # recognised. "none" will always pass any [suffix] # through as part of the issue title. # Default: strict subject_suffix_parsing = strict # Defines the brackets used for delimiting the prefix and # suffix in a subject line. The presence of "suffix" in # the config option name is a historical artifact and may # be ignored. # Default: [] subject_suffix_delimiters = [] # Controls matching of the incoming email subject line # against issue titles in the case where there is no # designator [prefix]. "never" turns off matching. # "creation + interval" or "activity + interval" # will match an issue for the interval after the issue's # creation or last activity. The interval is a standard # Roundup interval. # Default: always subject_content_match = always # Update issue title if incoming subject of email is different. # Setting this to "no" will ignore the title part of the subject # of incoming email messages. # # Allowed values: yes, no # Default: yes subject_updates_title = yes # Regular expression matching a single reply or forward # prefix prepended by the mailer. This is explicitly # stripped from the subject during parsing. # Value is Python Regular Expression (UTF8-encoded). # Default: (\s*\W?\s*(fw|fwd|re|aw|sv|ang)\W)+ refwd_re = (\s*\W?\s*(fw|fwd|re|aw|sv|ang)\W)+ # Regular expression matching start of an original message # if quoted the in body. # Value is Python Regular Expression (UTF8-encoded). # Default: ^[>|\s]*-----\s?Original Message\s?-----$ origmsg_re = ^[>|\s]*-----\s?Original Message\s?-----$ # Regular expression matching the start of a signature # in the message body. # Value is Python Regular Expression (UTF8-encoded). # Default: ^[>|\s]*-- ?$ sign_re = ^[>|\s]*-- ?$ # Regular expression matching end of line. # Value is Python Regular Expression (UTF8-encoded). # Default: [\r\n]+ eol_re = [\r\n]+ # Regular expression matching a blank line. # Value is Python Regular Expression (UTF8-encoded). # Default: [\r\n]+\s*[\r\n]+ blankline_re = [\r\n]+\s*[\r\n]+ # Unpack attached messages (encoded as message/rfc822 in MIME) # as multiple parts attached as files to the issue, if not # set we handle message/rfc822 attachments as a single file. # Allowed values: yes, no # Default: no unpack_rfc822 = no # When parsing incoming mails, roundup uses the first # text/plain part it finds. If this part is inside a # multipart/alternative, and this option is set, all other # parts of the multipart/alternative are ignored. The default # is to keep all parts and attach them to the issue. # Allowed values: yes, no # Default: no ignore_alternatives = no # If an email has only text/html parts, use this module # to convert the html to text. Choose from beautifulsoup 4, # dehtml - (internal code), or none to disable conversion. # If 'none' is selected, email without a text/plain part # will be returned to the user with a message. If # beautifulsoup is selected but not installed dehtml will # be used instead. # Allowed values: beautifulsoup, dehtml, none # Default: none convert_htmltotext = none # When handling emails ignore the Resent-From:-header # and use the original senders From:-header instead. # (This might be desirable in some situations where a moderator # reads incoming messages first before bouncing them to Roundup) # Allowed values: yes, no # Default: no keep_real_from = no .. index:: config.ini; sections pgp .. _`config-ini-section-pgp`: .. code:: ini # OpenPGP mail processing options [pgp] # Enable PGP processing. Requires gpg. If you're planning # to send encrypted PGP mail to the tracker, you should also # enable the encrypt-option below, otherwise mail received # encrypted might be sent unencrypted to another user. # Allowed values: yes, no # Default: no enable = no # If specified, a comma-separated list of roles to perform # PGP processing on. If not specified, it happens for all # users. Note that received PGP messages (signed and/or # encrypted) will be processed with PGP even if the user # doesn't have one of the PGP roles, you can use this to make # PGP processing completely optional by defining a role here # and not assigning any users to that role. # Default: roles = # Location of PGP directory. Defaults to $HOME/.gnupg if # not specified. # Default: homedir = # Enable PGP encryption. All outgoing mails are encrypted. # This requires that keys for all users (with one of the gpg # roles above or all users if empty) are available. Note that # it makes sense to educate users to also send mails encrypted # to the tracker, to enforce this, set 'require_incoming' # option below (but see the note). # Allowed values: yes, no # Default: no encrypt = no # Require that pgp messages received by roundup are either # 'signed', 'encrypted' or 'both'. If encryption is required # we do not return the message (in clear) to the user but just # send an informational message that the message was rejected. # Note that this still presents known-plaintext to an attacker # when the users sends the mail a second time with encryption # turned on. # Default: signed require_incoming = signed .. index:: config.ini; sections nosy .. _`config-ini-section-nosy`: .. code:: ini # Nosy messages sending [nosy] # Send nosy messages to the author of the message. # Allowed values: yes, no, new, nosy -- if yes, messages # are sent to the author even if not on the nosy list, same # for new (but only for new messages). When set to nosy, # the nosy list controls sending messages to the author. # Default: no messages_to_author = no # Where to place the email signature. # Allowed values: top, bottom, none # Default: bottom signature_position = bottom # 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. # # Allowed values: yes, no, new # Default: new add_author = 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. # # Allowed values: yes, no, new # Default: new add_recipients = new # Controls the email sending from the nosy reactor. If # "multiple" then a separate email is sent to each # recipient. If "single" then a single email is sent with # each recipient as a CC address. # Default: single email_sending = single # Attachments larger than the given number of bytes # won't be attached to nosy mails. They will be replaced by # a link to the tracker's download page for the file. # Default: 9223372036854775807 max_attachment_size = 9223372036854775807 .. index:: config.ini; sections markdown .. _`config-ini-section-markdown`: .. code:: ini # Markdown rendering options. [markdown] # If yes/true, render single new line characters in markdown # text with
. Set true if you want GitHub Flavored Markdown # (GFM) handling of embedded newlines. # Allowed values: yes, no # Default: no break_on_newline = no code-001c16ac87ec/doc/tracker_templates.txt0000644000000000000000000000507215046233326016750 0ustar 00000000000000========================= Roundup Tracker Templates ========================= The templates distributed with Roundup are stored in the "share" directory nominated by Python. On Unix this is typically ``/usr/share/roundup/templates/`` (or ``/usr/local/share...``) and on Windows this is ``c:\python38\share\roundup\templates\``. The template loading looks in four places to find the templates: 1. *share* - eg. ``/share/roundup/templates/*``. This should be the standard place to find them when Roundup is installed running setup.py from source. 2. ``install_dir``/..//share/....``, where prefix is the Python's ``sys.prefix``. ``sys.base_prefix`` or `sys.base_prefix/local``. This finds templates (and locales) installed by pip. E.G. in a virtualenv located at (``sys.prefix``): ``/tools/roundup``, roundup would be at: ``/tools/roundup/lib/python3.7/site-packages/roundup``. The templates would be at: ``/tools/roundup/lib/python3.7/site-packages/tools/roundup/share/roundup/templates/``. (Replace 3.7 with the Python version you are running.) 3. ``/../../share/roundup/templates/*``. This will be used if Roundup's run in the distro (aka. source) directory. 4. ``/*``. This is for when someone unpacks a 3rd-party template. 5. ````. This is for someone who "cd"s to the 3rd-party template dir. Templates contain: - modules ``schema.py`` and ``initial_data.py`` - directories ``html``, ``detectors`` and ``extensions`` (with appropriate contents) - optional directory ``lib`` which contains modules used by the other tracker components - optional ``config_ini.ini`` file. It is structured like a tracker's ``config.ini`` but contains only headers (e.g. ``[main]``) and *required* parameters that are different from defaults. For example:: [main] template_engine = jinja2 static_files = static These settings override the default values in the tracker's ``config.ini`` when using roundup-admin to install a template. - template "marker" file ``TEMPLATE-INFO.txt``, which contains the name of the template, a description of the template and its intended audience. An example TEMPLATE-INFO.txt: .. code-block:: text Name: classic Description: This is a generic issue tracker that may be used to track bugs, feature requests, project issues or any number of other types of issues. Most users of Roundup will find that this template suits them, with perhaps a few customisations. Intended-For: All first-time Roundup users code-001c16ac87ec/doc/upgrading-history.txt0000644000000000000000000021013215046233326016711 0ustar 00000000000000=============================== Upgrading versions before 1.5.0 =============================== .. note:: If you are upgrading from a version of Roundup that is newer than 1.5.0, use the version steps in the `main upgrading document`_. Please read each section carefully and edit your tracker home files accordingly. Note that there is information about upgrade procedures in the `administration guide`_ in the `Software Upgrade`_ section. If a specific version transition isn't mentioned here (eg. 0.6.7 to 0.6.8) then you don't need to do anything. If you're upgrading from 0.5.6 to 0.6.8 though, you'll need to check the "0.5 to 0.6" and "0.6.x to 0.6.3" steps. General steps: 1. Make note of your current Roundup version. 2. Take your Roundup installation offline (web, email, cron scripts, roundup-admin etc.) 3. Backup your Roundup instance 4. Install a new version of Roundup 5. Make version specific changes as described below for each version transition. If you are starting at 1.5.0 and installing to 2.3, you need to make the changes for **all** versions starting at 1.5 and ending at 2.3. E.G. 1.5.0 -> 1.5.1, 1.5.1 -> 1.6.0, ..., 2.1.0 -> 2.2.0, 2.2.0 -> 2.3.0. 6. Run ``roundup-admin -i migrate`` for **all** your trackers. This will update the database if it is required. 7. Bring your Roundup instance back online 8. Test **IMPORTANT** The v1.5.x releases of Roundup were the last to support Python v2.5 and v2.6. Starting with the v1.6 releases of Roundup Python version 2.7 that is newer than 2.7.2 is required to run Roundup. Starting with Roundup version 2.0.0 we also support Python 3 versions newer than 3.4. Contents: .. contents:: :local: .. index:: Upgrading; 1.4.20 to 1.4.21 Migrating from 1.4.20 to 1.4.21 =============================== The ``_generic.calendar.html`` page of the instance has been updated to include ````. This prevents robots to follow all the links in the calendar. If you haven't modified the page on your local instance, you can simply replace it with the one in ``share/roundup/templates/classic/html/_generic.calendar.html``; if you did, you can add the tag manually. See issue2550765 and changeset a099ff2ceff3. If you are using the xml-rpc interface, there is a change in accessing it. You can not send text/xml data to any roundup url and get a response, you must use the /xmlrpc url. For example, if you used to send your xmlrpc request to: \http://myroundup.com/roundup you need to change the url to read: \http://myroundup.com/roundup/xmlrpc to invoke the xmlrpc handler. This allows us to send xml data to roundup for other handlers (e.g. REST, SOAP ...) in the future. .. index:: Upgrading; 1.4.19 to 1.4.20 Migrating from 1.4.19 to 1.4.20 =============================== Roundup used to allow certain HTML-Tags in OK- and Error-messages. Since these messages are passed via the URL (due to roundup redirecting after an edit), we did have security-issues (see issue2550724). If you have customised the OK or Error messages in your roundup-installation and you were using features like bold or italic in the message, you will have to do without this highlighting and remove HTML tags from messages. If you were using
tags for multi-line messages, you now should use newlines instead, these will be replaced with
during formatting. Note that the previous implementation also allowed links inside messages. Since these links could be set by an attacker, no links in roundup messages are supported anymore. This does *not* affect the "clear this message" link in OK-messages as it is generated by the template and is not part of the OK-message. If you have not modified any roundup messages, you need not do anything, the templates shipped with roundup did not use HTML tags in messages for highlighting. .. index:: Upgrading; 1.4.17 to 1.4.18 Migrating from 1.4.17 to 1.4.18 =============================== There was a bug in 1.4.17 where files were unlinked from issues if a mail without attachment was received via the mail interface. The following script will list likely issues being affected by the bug. The date in the script is the date of the 1.4.17 release. If you have installed 1.4.17 later than this date, you can change the date appropriately to your installation date. Run the script in the directory of your tracker:: #!/usr/bin/python import os from roundup import instance from roundup.date import Date dir = os.getcwd () tracker = instance.open (dir) db = tracker.open ('admin') # you may want to change this to your install date to find less candidates last_release = Date('2011-05-13') affected = {} for i in db.issue.getnodeids(): for j in db.issue.history(i): if i in affected: break if j[1] < last_release or j[3] != 'set' or 'files' not in j[4]: continue for op, p in j[4]['files']: if op == '-': affected [i] = 1 break print(', '.join(sorted(affected.keys()))) To find out which files where attached before you can look in the history of the affected issue. For fixing issues you can re-attach the files in question using the "set" command of roundup-admin, e.g., if the list of files attached to an issue should be files 5, 17, 23 for issue42 you will set this using roundup-admin -i /path/to/your/tracker set issue42 files=5,17,23 .. index:: Upgrading; 1.4.x to 1.4.17 Migrating from 1.4.x to 1.4.17 ============================== There is a new config-option `migrate_passwords` in section `web` to auto-migrate passwords at web-login time to a more secure storage scheme. Default for the new option is "yes" so if you don't want that passwords are auto-migrated to a more secure password scheme on user login, set this to "no" before running your tracker(s) after the upgrade. The standalone roundup-server now defaults to listening on localhost (no longer on all network interfaces). This will not affect you if you're already using a configuration file for roundup-server. If you are using an empty setting for the `host` parameter in the config-file you should explicitly put 0.0.0.0 there as the use of an empty string to specify listening to all interfaces is deprecated and will go away in a future version. If you are starting the server without a configuration file and want to explicitly listen to all network interface, you should specify the -n option with the address `0.0.0.0`. .. _new search permissions for query in 1.4.17: Searching now requires either read-permission without a check method, or you will have to add a "Search" permission for a class or a list of properties for a class (if you want to allow searching). For the classic template (or other templates derived from it) you want to add the following lines to your `schema.py` file:: p = db.security.addPermission(name='Search', klass='query') db.security.addPermissionToRole('User', p) This is needed, because for the `query` class users may view only their own queries (or public queries). This is implemented with a `check` method, therefore the default search permissions will not allow searching and you'll have to add an explicit search permission. If you have modified your schema, you can check if you're missing any search permissions with the following script, run it in your :term:`tracker home` directory, it will list for each Class and Property the roles that may search for this property:: #!/usr/bin/python from __future__ import print_function import os from roundup import instance tracker = instance.open(os.getcwd ()) db = tracker.open('admin') for cl in sorted(db.getclasses()): print("Class:", cl) for p in sorted(db.getclass(cl).getprops(protected=True).keys()): print(" Property:", p) roles = [] for role in sorted(db.security.role.keys()): if db.security.roleHasSearchPermission(cl,p,role): roles.append(role) print(" roles may search:", ', '.join(roles)) .. index:: Upgrading; 1.4.x to 1.4.12 Migrating from 1.4.x to 1.4.12 ============================== Item creation now checks the "Create" permission instead of the "Edit" permission for individual properties. If you have modified your tracker permissions from the default distribution, you should check that "Create" permissions exist for all properties you want users to be able to create. Fixing some potential security holes ------------------------------------ Enhanced checking was added to the user registration auditor. If you run a public tracker you should update your tracker's ``detectors/userauditor.py`` using the new code from ``share/roundup/templates/classic/detectors/userauditor.py``. In most cases you may just copy the file over, but if you've made changes to the auditor in your tracker then you'll need to manually integrate the new code. Some HTML templates were found to have formatting security problems: ``html/page.html``:: -tal:replace="request/user/username">username
+tal:replace="python:request.user.username.plain(escape=1)">username
``html/_generic.help-list.html``:: -tal:content="structure python:item[prop]"> +tal:content="python:item[prop]"> The lines marked "+" should be added and lines marked "-" should be deleted (minus the "+"/"-" signs). Some HTML interface tweaks -------------------------- You may wish to copy the ``user_utils.js`` and ``style.css` files from the source distribution ``share/roundup/templates/classic/html/`` directory to the ``html`` directory of your trackers as it includes a small improvement. If you have made local changes to those files you'll need to manually work the differences in to your versions or ignore the changes. .. index:: Upgrading; 1.4.x to 1.4.11 Migrating from 1.4.x to 1.4.11 ============================== Close potential security hole ----------------------------- If your tracker has untrusted users you should examine its ``schema.py`` file and look for the section granting the "Edit" permission to your users. This should look something like:: p = db.security.addPermission(name='Edit', klass='user', check=own_record, description="User is allowed to edit their own user details") and should be modified to restrict the list of properties they are allowed to edit by adding the ``properties=`` section like:: p = db.security.addPermission(name='Edit', klass='user', check=own_record, properties=('username', 'password', 'address', 'realname', 'phone', 'organisation', 'alternate_addresses', 'queries', 'timezone'), description="User is allowed to edit their own user details") Most importantly the "roles" property should not be editable - thus not appear in that list of properties. Grant the "Register" permission to the Anonymous role ----------------------------------------------------- A separate "Register" permission has been introduced to allow anonymous users to register. This means you will need to add the following to your tracker's ``schema.py`` to add the permission and assign it to the Anonymous role (replacing any previously assigned "Create user" permission for the Anonymous role):: +db.security.addPermission(name='Register', klass='user', + description='User is allowed to register new user') # Assign the appropriate permissions to the anonymous user's Anonymous # Role. Choices here are: # - Allow anonymous users to register -db.security.addPermissionToRole('Anonymous', 'Create', 'user') +db.security.addPermissionToRole('Anonymous', 'Register', 'user') The lines marked "+" should be added and lines marked "-" should be deleted (minus the "+"/"-" signs). You should also modify the ``html/page.html`` template to change the permission tested there:: -tal:condition="python:request.user.hasPermission('Create', 'user')" +tal:condition="python:request.user.hasPermission('Register', 'user')" Generic class editor may now restore retired items -------------------------------------------------- The instructions for doing so won't be present in your tracker unless you copy the ``_generic.index.html`` template from the roundup distribution in ``share/roundup/templates/classic/html`` to your tracker's ``html`` directory. .. index:: Upgrading; 1.4.x to 1.4.9 Migrating from 1.4.x to 1.4.9 ============================= Customized MailGW Class ----------------------- If you have customised the MailGW class in your tracker: The new MailGW class opens the database for each message in the method handle_message (instance.open) instead of passing the opened database as a parameter to the MailGW constructor. The old handle_message has been renamed to _handle_message. The new method opens the database and wraps the call to the old method into a try/finally. Your customised MailGW class needs to mirror this behavior. Fix the "remove" button in issue files and messages lists --------------------------------------------------------- The "remove" button(s) in the issue messages list needs to be altered. Find the following in your tracker's ``html/issue.item.html`` template::

and add ``method="POST"`` as shown below:: Then also find:: and add ``method="POST"`` as shown below:: Fixing the "retire" button in user management list -------------------------------------------------- Some previous versions of this upgrading document missed ``method="POST"`` in the change to the "retire" link in the user management list in section `Migrating from 1.4.x to 1.4.7`_. Make sure the change is done as listed below in this document. .. index:: Upgrading; 1.4.x to 1.4.7 Migrating from 1.4.x to 1.4.7 ============================= Several security issues were addressed in this release. Some aspects of your trackers may no longer function depending on your local customisations. Core functionality that will need to be modified: Grant the "retire" permission to users for their queries -------------------------------------------------------- Users will no longer be able to retire their own queries. To remedy this you will need to add the following to your tracker's ``schema.py`` just under the line that grants them permission to edit their own queries:: p = db.security.addPermission(name='Edit', klass='query', check=edit_query, description="User is allowed to edit their queries") db.security.addPermissionToRole('User', p) + p = db.security.addPermission(name='Retire', klass='query', check=edit_query, + description="User is allowed to retire their queries") + db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Create', klass='query', description="User is allowed to create queries") db.security.addPermissionToRole('User', p) The lines marked "+" should be added, minus the "+" sign. Fix the "retire" link in the users list for admin users ------------------------------------------------------- The "retire" link found in the file ``html/user.index.html``:: retire Should be replaced with::
Fix for Python 2.6+ users ------------------------- If you use Python 2.6 you should edit your tracker's ``detectors/nosyreaction.py`` file to change:: import sets at the top to:: from roundup.anypy.sets_ import set and then all instances of ``sets.Set()`` to ``set()`` in the later code. Trackers currently allowing HTML file uploading ----------------------------------------------- Trackers which wish to continue to allow uploading of HTML content against issues will need to set a new configuration variable in the ``[web]`` section of the tracker's ``config.ini`` file: # Setting this option enables Roundup to serve uploaded HTML # file content *as HTML*. This is a potential security risk # and is therefore disabled by default. Set to 'yes' if you # trust *all* users uploading content to your tracker. # Allowed values: yes, no # Default: no allow_html_file = no .. index:: Upgrading; 1.4.2 to 1.4.3 Migrating from 1.4.2 to 1.4.3 ============================= If you are using the MySQL backend you will need to replace some indexes that may have been created by version 1.4.2. You should to access your MySQL database directly and remove any indexes with a name ending in "_key_retired_idx". You should then re-add them with the same spec except the key column name needs a size. So an index on "_user (__retired, _name)" should become "_user (__retired, _name(255))". .. index:: Upgrading; 1.4.x to 1.4.2 Migrating from 1.4.x to 1.4.2 ============================= .. index:: roundup-admin; migrate subcommand You should run the "roundup-admin migrate" command for your tracker once you've installed the latest codebase. Do this before you use the web, command-line or mail interface and before any users access the tracker. This command will respond with either "Tracker updated" (if you've not previously run it on an RDBMS backend) or "No migration action required" (if you have run it, or have used another interface to the tracker, or are using anydbm). It's safe to run this even if it's not required, so just get into the habit. .. index:: Upgrading; 1.3.3 to 1.4.0 Migrating from 1.3.3 to 1.4.0 ============================= Value of the "refwd_re" tracker configuration option (section "mailgw") is treated as UTF-8 string. In previous versions, it was ISO8859-1. If you have running trackers based on the classic template, please update the messagesummary detector as follows:: --- detectors/messagesummary.py 17 Apr 2003 03:26:38 -0000 1.1 +++ detectors/messagesummary.py 3 Apr 2007 06:47:21 -0000 1.2 @@ -8,7 +8,7 @@ if newvalues.has_key('summary') or not newvalues.has_key('content'): return - summary, content = parseContent(newvalues['content'], 1, 1) + summary, content = parseContent(newvalues['content'], config=db.config) newvalues['summary'] = summary In the latest version we have added some database indexes to the SQL-backends (mysql, postgresql, sqlite) for speeding up building the roundup-index for full-text search. We recommend that you create the following database indexes on the database by hand:: CREATE INDEX words_by_id ON __words (_textid); CREATE UNIQUE INDEX __textids_by_props ON __textids (_class, _itemid, _prop); You can find out which database backend you are using by looking at the ``db/backend_name`` file in the tracker's home directory. The username, password, and database name can all be found in the ``config.ini`` file if you are using ``mysql`` or ``postgresql``. You can run the SQL commands using the native client interface: ``psql`` (postgres), ``mysql`` (MySQL), or ``sqlite3`` (SQLite). .. index:: Upgrading; 1.2.x to 1.3.0 Migrating from 1.2.x to 1.3.0 ============================= 1.3.0 Web interface changes --------------------------- Some of the HTML files in the "classic" and "minimal" tracker templates were changed to fix some bugs and clean them up. You may wish to compare them to the HTML files in your tracker and apply any changes. .. index:: Upgrading; 1.1.2 to 1.2.0 Migrating from 1.1.2 to 1.2.0 ============================= 1.2.0 Sorting and grouping by multiple properties ------------------------------------------------- Starting with this version, sorting and grouping by multiple properties is possible. This means that request.sort and request.group are now lists. This is reflected in several places: * ``renderWith`` now has list attributes for ``sort`` and ``group``, where you previously wrote:: renderWith(... sort=('-', 'activity'), group=('+', 'priority') you write now:: renderWith(... sort=[('-', 'activity')], group=[('+', 'priority')] * In templates that permit to edit sorting/grouping, request.sort and request.group are (possibly empty) lists. You can now sort and group by multiple attributes. For an example, see the classic template. You may want search for the variable ``n_sort`` which can be set to the number of sort/group properties. * Templates that diplay new headlines for each group of items with equal group properties can now use the modified ``batch.propchanged`` method that can take several properties which are checked for changes. See the example in the classic template which makes use of ``batch.propchanged``. .. index:: Upgrading; 1.1.0 to 1.1.1 Migrating from 1.1.0 to 1.1.1 ============================= 1.1.1 "Clear this message" -------------------------- In 1.1.1, the standard ``page.html`` template includes a "clear this message" link in the green "ok" message bar that appears after a successful edit (or other) action. To include this in your tracker, change the following in your ``page.html`` template::

error

to be::

clear this message

If you implemented the "clear this message" in your 1.1.0 tracker, then you should change it to the above and it will work much better! .. index:: Upgrading; 1.0.x to 1.1.0 Migrating from 1.0.x to 1.1.0 ============================= 1.1 Login "For Session Only" ---------------------------- In 1.1, web logins are alive for the length of a session only, *unless* you add the following to the login form in your tracker's ``page.html``::
See the classic tracker ``page.html`` if you're unsure where this should go. 1.1 Query Display Name ---------------------- The ``dispname`` web variable has been renamed ``@dispname`` to avoid clashing with other variables of the same name. If you are using the display name feature, you will need to edit your tracker's ``page.html`` and ``issue.index.html`` pages to change ``dispname`` to ``@dispname``. A side-effect of this change is that the renderWith method used in the ``home.html`` page may now take a dispname argument. 1.1 "Clear this message" ------------------------ In 1.1, the standard ``page.html`` template includes a "clear this message" link in the green "ok" message bar that appears after a successful edit (or other) action. To include this in your tracker, change the following in your ``page.html`` template::

error

to be::

clear this message

.. index:: Upgrading; 0.8.x to 1.0 Migrating from 0.8.x to 1.0 =========================== 1.0 New Query Permissions ------------------------- New permissions are defined for query editing and viewing. To include these in your tracker, you need to add these lines to your tracker's ``schema.py``:: # Users should be able to edit and view their own queries. They should also # be able to view any marked as not private. They should not be able to # edit others' queries, even if they're not private def view_query(db, userid, itemid): private_for = db.query.get(itemid, 'private_for') if not private_for: return True return userid == private_for def edit_query(db, userid, itemid): return userid == db.query.get(itemid, 'creator') p = db.security.addPermission(name='View', klass='query', check=view_query, description="User is allowed to view their own and public queries") db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Edit', klass='query', check=edit_query, description="User is allowed to edit their queries") db.security.addPermissionToRole('User', p) p = db.security.addPermission(name='Create', klass='query', description="User is allowed to create queries") db.security.addPermissionToRole('User', p) and then remove 'query' from the line:: # Assign the access and edit Permissions for issue, file and message # to regular users now for cl in 'issue', 'file', 'msg', 'query', 'keyword': so it looks like:: for cl in 'issue', 'file', 'msg', 'keyword': .. index:: Upgrading; 0.8.0 to 0.8.3 Migrating from 0.8.0 to 0.8.3 ============================= 0.8.3 Nosy Handling Changes --------------------------- A change was made to fix a bug in the ``nosyreaction.py`` standard detector. To incorporate this fix in your trackers, you will need to copy the ``nosyreaction.py`` file from the ``templates/classic/detectors`` directory of the source to your tracker's ``templates`` directory. If you have modified the ``nosyreaction.py`` file from the standard version, you will need to roll your changes into the new file. .. index:: Upgrading; 0.7.1 to 0.8.0 Migrating from 0.7.1 to 0.8.0 ============================= You *must* fully uninstall previous Roundup version before installing Roundup 0.8.0. If you don't do that, ``roundup-admin install`` command may fail to function properly. 0.8.0 Backend changes --------------------- Backends 'bsddb' and 'bsddb3' are removed. If you are using one of these, you *must* migrate to another backend before upgrading. 0.8.0 API changes ----------------- Class.safeget() was removed from the API. Test your item ids before calling Class.get() instead. 0.8.0 New tracker layout ------------------------ The ``config.py`` file has been replaced by ``config.ini``. You may use the roundup-admin command "genconfig" to generate a new config file:: roundup-admin genconfig /config.ini and modify the values therein based on the contents of your old config.py. In most cases, the names of the config variables are the same. The ``select_db.py`` file has been replaced by a file in the ``db`` directory called ``backend_name``. As you might guess, this file contains just the name of the backend. To figure what the contents of yours should be, use the following table: ================================ ========================= ``select_db.py`` contents ``backend_name`` contents ================================ ========================= from back_anydbm import ... anydbm from back_metakit import ... metakit from back_sqlite import ... sqlite from back_mysql import ... mysql from back_postgresql import ... postgresql ================================ ========================= The ``dbinit.py`` file has been split into two new files, ``initial_data.py`` and ``schema.py``. The contents of this file are: ``initial_data.py`` You don't need one of these as your tracker is already initialised. ``schema.py`` Copy the body of the ``def open(name=None)`` function from your old tracker's ``dbinit.py`` file to this file. As the lines you're copying aren't part of a function definition anymore, one level of indentation needs to be removed (remove only the leading four spaces on each line). The first few lines -- those starting with ``from roundup.hyperdb import ...`` and the ``db = Database(config, name)`` line -- don't need to be copied. Neither do the last few lines -- those starting with ``import detectors``, down to ``return db`` inclusive. You may remove the ``__init__.py`` module from the "detectors" directory as it is no longer used. There's a new way to write extension code for Roundup. If you have code in an ``interfaces.py`` file you should move it. See the `customisation documentation`_ for information about how extensions are now written. Note that some older trackers may use ``interfaces.py`` to customise the mail gateway behaviour. You will need to keep your ``interfaces.py`` file if this is the case. 0.8.0 Permissions Changes ------------------------- The creation of a new item in the user interfaces is now controlled by the "Create" Permission. You will need to add an assignment of this Permission to your users who are allowed to create items. The most common form of this is the following in your ``schema.py`` added just under the current assignation of the Edit Permission:: for cl in 'issue', 'file', 'msg', 'query', 'keyword': p = db.security.getPermission('Create', cl) db.security.addPermissionToRole('User', p) You will need to explicitly let anonymous users access the web interface so that regular users are able to see the login form. Note that almost all trackers will need this Permission. The only situation where it's not required is in a tracker that uses an HTTP Basic Authenticated front-end. It's enabled by adding to your ``schema.py``:: p = db.security.getPermission('Web Access') db.security.addPermissionToRole('Anonymous', p) Finally, you will need to enable permission for your users to edit their own details by adding the following to ``schema.py``:: # Users should be able to edit their own details. Note that this # permission is limited to only the situation where the Viewed or # Edited item is their own. def own_record(db, userid, itemid): '''Determine whether the userid matches the item being accessed.''' return userid == itemid p = db.security.addPermission(name='View', klass='user', check=own_record, description="User is allowed to view their own user details") p = db.security.addPermission(name='Edit', klass='user', check=own_record, description="User is allowed to edit their own user details") db.security.addPermissionToRole('User', p) 0.8.0 Use of TemplatingUtils ---------------------------- If you used custom python functions in TemplatingUtils, they must be moved from interfaces.py to a new file in the ``extensions`` directory. Each Function that should be available through TAL needs to be defined as a toplevel function in the newly created file. Furthermore you add an inititialization function, that registers the functions with the tracker. If you find this too tedious, donfu wrote an automatic init function that takes an existing TemplatingUtils class, and registers all class methods that do not start with an underscore. The following hack should be placed in the ``extensions`` directory alongside other extensions:: class TemplatingUtils: # copy from interfaces.py def init(tracker): util = TemplatingUtils() def setClient(tu): util.client = tu.client return util def execUtil(name): return lambda tu, *args, **kwargs: \ getattr(setClient(tu), name)(*args, **kwargs) for name in dir(util): if callable(getattr(util, name)) and not name.startswith('_'): tracker.registerUtil(name, execUtil(name)) 0.8.0 Logging Configuration --------------------------- See the `administration guide`_ for information about configuring the new logging implemented in 0.8.0. .. index:: Upgrading; 0.7.2 to 0.7.3 Migrating from 0.7.2 to 0.7.3 ============================= 0.7.3 Configuration ------------------- If you choose, you may specify the directory from which static files are served (those which use the URL component ``@@file``). Currently the directory defaults to the ``TEMPLATES`` configuration variable. You may define a new variable, ``STATIC_FILES`` which overrides this value for static files. .. index:: Upgrading; 0.7.0 to 0.7.2 Migrating from 0.7.0 to 0.7.2 ============================= 0.7.2 DEFAULT_TIMEZONE is now required -------------------------------------- The DEFAULT_TIMEZONE configuration variable is now required. Add the following to your tracker's ``config.py`` file:: # You may specify a different default timezone, for use when users do not # choose their own in their settings. DEFAULT_TIMEZONE = 0 # specify as numeric hour offest .. index:: Upgrading; 0.7.0 to 0.7.1 Migrating from 0.7.0 to 0.7.1 ============================= 0.7.1 Permission assignments ---------------------------- If you allow anonymous access to your tracker, you might need to assign some additional View (or Edit if your tracker is that open) permissions to the "anonymous" user. To do so, find the code in your ``dbinit.py`` that says:: for cl in 'issue', 'file', 'msg', 'query', 'keyword': p = db.security.getPermission('View', cl) db.security.addPermissionToRole('User', p) p = db.security.getPermission('Edit', cl) db.security.addPermissionToRole('User', p) for cl in 'priority', 'status': p = db.security.getPermission('View', cl) db.security.addPermissionToRole('User', p) Add add a line:: db.security.addPermissionToRole('Anonymous', p) next to the existing ``'User'`` lines for the Permissions you wish to assign to the anonymous user. .. index:: Upgrading; versions earlier than 0.7 Migrating from 0.6 to 0.7 ========================= 0.7.0 Permission assignments ---------------------------- Due to a change in the rendering of web widgets, permissions are now checked on Classes where they previously weren't (this is a good thing). You will need to add some additional Permission assignments for your regular users, or some displays will break. After the following in your tracker's ``dbinit.py``:: # Assign the access and edit Permissions for issue, file and message # to regular users now for cl in 'issue', 'file', 'msg', 'query', 'keyword': p = db.security.getPermission('View', cl) db.security.addPermissionToRole('User', p) p = db.security.getPermission('Edit', cl) db.security.addPermissionToRole('User', p) add:: for cl in 'priority', 'status': p = db.security.getPermission('View', cl) db.security.addPermissionToRole('User', p) 0.7.0 Getting the current user id --------------------------------- The Database.curuserid attribute has been removed. Any code referencing this attribute should be replaced with a call to Database.getuid(). 0.7.0 ZRoundup changes ---------------------- The templates in your tracker's html directory will need updating if you wish to use ZRoundup. If you've not modified those files (or some of them), you may just copy the new versions from the Roundup source in the templates/classic/html directory. If you have modified the html files, then you'll need to manually edit them to change all occurances of special form variables from using the colon ":" special character to the at "@" special character. That is, variables such as:: :action :required :template :remove:messages ... should become:: @action @required @template @remove@messages ... Note that ``tal:`` statements are unaffected. So are TAL expression type prefixes such as ``python:`` and ``string:``. Please ask on the roundup-users mailing list for help if you're unsure. 0.7.0 Edit collision detection ------------------------------ Roundup now detects collisions with editing in the web interface (that is, two people editing the same item at the same time). You must copy the ``_generic.collision.html`` file from Roundup source in the ``templates/classic/html`` directory. to your tracker's ``html`` directory. Migrating from 0.6.x to 0.6.3 ============================= 0.6.3 Configuration ------------------- You will need to copy the file:: templates/classic/detectors/__init__.py to your tracker's ``detectors`` directory, replacing the one already there. This fixes a couple of bugs in that file. Migrating from 0.5 to 0.6 ========================= 0.6.0 Configuration ------------------- Introduced EMAIL_FROM_TAG config variable. This value is inserted into the From: line of nosy email. If the sending user is "Foo Bar", the From: line is usually:: "Foo Bar" the EMAIL_FROM_TAG goes inside the "Foo Bar" quotes like so:: "Foo Bar EMAIL_FROM_TAG" I've altered the mechanism in the detectors __init__.py module so that it doesn't cross-import detectors from other trackers (if you run more than one in a single roundup-server). This change means that you'll need to copy the __init__.py from roundup/templates/classic/detectors/__init__.py to your /detectors/__init__.py. Don't worry, the "classic" __init__ is a one-size-fits-all, so it'll work even if you've added/removed detectors. 0.6.0 Templating changes ------------------------ The ``user.item`` template (in the tracker home "templates" directory) needs to have the following hidden variable added to its form (between the ```` and ```` 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: https://sourceforge.net/projects/roundup/lists/roundup-users See the customisation doc section on `Form Values`__ for documentation of the new form variables possible. __ reference.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 web page on sourceforge, https://www.roundup-tracker.org/. 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/