imip-agent

Annotated docs/wiki/Developing

1069:37921ab84c01
1024:48b37822d2a0
1009:c030453cb40b
2016-01-29 Paul Boddie file changeset files shortlog Moved common test initialisation into a separate script.
paul@1007 1 
= Developing imip-agent =
paul@1007 2 
 
 paul@1007      3 
To start developing the imip-agent software further, first obtain the code
 
 paul@1007      4 
by following the advice on the [[../Downloads|downloads page]]. Obtaining
 
 paul@1007      5 
the code directly from the repository is advisable since any changes you
 
 paul@1007      6 
make can then be tracked and managed.
 
 paul@1007      7 
 
 paul@1007      8 
<<TableOfContents(2,3)>>
 
 paul@1007      9 
 
 paul@1007     10 
== Distribution Contents ==
 
 paul@1007     11 
 
 paul@1007     12 
The software distribution contains the following directories:
 
 paul@1007     13 
 
 paul@1007     14 
{{{#!table
 
 paul@1007     15 
'''Directory''' || '''Description'''
 
 paul@1007     16 
==
 
 paul@1007     17 
`conf`
 
 paul@1007     18 
|| Example configuration files (see the
 
 paul@1007     19 
.. [[../GettingStarted|getting started guide]] for details)
 
 paul@1007     20 
==
 
 paul@1007     21 
`docs`
 
 paul@1007     22 
|| Documentation, including these wiki pages
 
 paul@1007     23 
==
 
 paul@1007     24 
`htdocs`
 
 paul@1007     25 
|| Resources for the [[../CalendarManager|management interface]]
 
 paul@1007     26 
==
 
 paul@1007     27 
`imiptools`
 
 paul@1007     28 
|| A Python package providing mail handling and support for calendar
 
 paul@1007     29 
.. object processing
 
 paul@1007     30 
==
 
 paul@1007     31 
`imipweb`
 
 paul@1007     32 
|| A Python package providing Web-related functionality for the
 
 paul@1007     33 
.. [[../CalendarManager|management interface]]
 
 paul@1007     34 
==
 
 paul@1007     35 
`messages`
 
 paul@1007     36 
|| Localised messages for the [[../AgentPrograms|agent programs]] and
 
 paul@1007     37 
.. [[../CalendarManager|management interface]]
 
 paul@1007     38 
==
 
 paul@1007     39 
`tests`
 
 paul@1007     40 
|| A suite of tests used to verify the behaviour of the software
 
 paul@1007     41 
.. (see the [[../Testing|testing guide]])
 
 paul@1007     42 
==
 
 paul@1007     43 
`tools`
 
 paul@1007     44 
|| Tools for [[../Administration|administration]] (see also the
 
 paul@1007     45 
.. [[../GettingStarted|getting started guide]])
 
 paul@1007     46 
}}}
 
 paul@1007     47 
 
 paul@1007     48 
At the top level of the distribution, the following files are found:
 
 paul@1007     49 
 
 paul@1007     50 
{{{#!table
 
 paul@1007     51 
'''File''' || '''Description'''
 
 paul@1007     52 
==
 
 paul@1007     53 
`imip_person.py`
 
 paul@1007     54 
||<rowspan="3"> The main program files for the
 
 paul@1007     55 
             .. [[../AgentPrograms|agent programs]]
 
 paul@1007     56 
==
 
 paul@1007     57 
`imip_person_outgoing.py`
 
 paul@1007     58 
==
 
 paul@1007     59 
`imip_resource.py`
 
 paul@1007     60 
==
 
 paul@1007     61 
`imip_manager.py`
 
 paul@1007     62 
|| The [[../CalendarManager|management interface]] main program file
 
 paul@1007     63 
==
 
 paul@1007     64 
`imip_store.py`
 
 paul@1007     65 
|| The Python module providing an abstraction over the
 
 paul@1007     66 
.. [[../FilesystemUsage|data storage structures]]
 
 paul@1007     67 
==
 
 paul@1007     68 
`markup.py`
 
 paul@1007     69 
|| A Python library providing HTML generation support
 
 paul@1007     70 
==
 
 paul@1007     71 
`README.txt`
 
 paul@1007     72 
|| Some basic documentation
 
 paul@1007     73 
==
 
 paul@1007     74 
`vCalendar.py`
 
 paul@1007     75 
||<rowspan="3"> Handling of vCalendar and related data formats
 
 paul@1007     76 
==
 
 paul@1007     77 
`vContent.py`
 
 paul@1007     78 
==
 
 paul@1007     79 
`vRecurrence.py`
 
 paul@1007     80 
}}}
 
 paul@1007     81 
 
 paul@1007     82 
== Architectural Components ==
 
 paul@1007     83 
 
 paul@1007     84 
The principal components of the software architecture are described below.
 
 paul@1007     85 
 
 paul@1007     86 
=== vContent ===
 
 paul@1007     87 
 
 paul@1007     88 
The v-prefixed libraries are concerned with the basic interpretation of
 
 paul@1007     89 
calendar-related data. For the most part, these libraries should already
 
 paul@1007     90 
behave in a predictable and reliable fashion and should not need much
 
 paul@1007     91 
further development. There are perhaps some deficiencies in the
 
 paul@1007     92 
`vRecurrence` module that are described on the
 
 paul@1007     93 
[[../CalendaringSupport|calendaring standards page]].
 
 paul@1007     94 
 
 paul@1007     95 
It is not inconceivable that a `vCard` module be introduced in the future
 
 paul@1007     96 
to handle vCard data, thus enhancing the data about people within
 
 paul@1007     97 
imip-agent, perhaps also supporting mechanisms to obtain free/busy and
 
 paul@1007     98 
other information about scheduling participants.
 
 paul@1007     99 
 
 paul@1007    100 
=== imiptools ===
 
 paul@1007    101 
 
 paul@1007    102 
The bulk of the work done in imip-agent happens within `imiptools`. When
 
 paul@1007    103 
used from [[../AgentPrograms|agent programs]] launched by the mail system,
 
 paul@1007    104 
the different modules support the "handler" functionality that involves
 
 paul@1007    105 
obtaining information from calendar data, performing the necessary action
 
 paul@1007    106 
related to a scheduling method, and generating responses or notifications.
 
 paul@1007    107 
More details are given about these activities in the guide to
 
 paul@1007    108 
[[../IncomingMessages|incoming message handling]].
 
 paul@1007    109 
 
 paul@1007    110 
When used from the [[../CalendarManager|management interface]], the
 
 paul@1007    111 
modules support the Web-based functionality as a more general calendar
 
 paul@1007    112 
system client, typically handling a single calendar object at any given
 
 paul@1007    113 
time.
 
 paul@1007    114 
 
 paul@1007    115 
=== imipweb ===
 
 paul@1007    116 
 
 paul@1007    117 
Most of the `imipweb` package is concerned with the display of calendar
 
 paul@1007    118 
information as Web pages and the handling of submitted data over the Web
 
 paul@1007    119 
as users interact with those Web pages. The `imip_manager.py` file is
 
 paul@1007    120 
deployed as a [[https://tools.ietf.org/html/rfc3875|CGI]] program, and it
 
 paul@1007    121 
acts as a simple "switch" that shows the appropriate kind of Web page (or
 
 paul@1007    122 
"view") depending on the requested URL, delegating to one of the modules
 
 paul@1007    123 
within the `imipweb` package to do so:
 
 paul@1007    124 
 
 paul@1007    125 
|| '''Module'''       || '''View'''        ||
 
 paul@1007    126 
|| `imipweb.calendar` || Calendar          ||
 
 paul@1007    127 
|| `imipweb.event`    || Individual events ||
 
 paul@1007    128 
|| `imipweb.profile`  || User profile      ||
 
 paul@1007    129 
 
 paul@1007    130 
A general `imipweb.resource` module supports the different views with
 
 paul@1007    131 
common functionality. Useful abstractions for period and date information
 
 paul@1007    132 
are provided in the `imipweb.data` module. The CGI interfacing is defined
 
 paul@1007    133 
in the `imipweb.env` module.
 
 paul@1007    134 
 
 paul@1007    135 
One of the most awkward aspects of providing a Web interface to events is
 
 paul@1007    136 
the need to provide a comprehensive enough representation of period data
 
 paul@1007    137 
as expressed in calendar objects that can be held in a form defined in a
 
 paul@1007    138 
Web page, interpreted by the program, written back to the form, all
 
 paul@1007    139 
without losing information.
 
 paul@1007    140 
 
 paul@1007    141 
=== imip_store ===
 
 paul@1007    142 
 
 paul@1007    143 
The `imip_store` module provides the basis for calendar data persistence.
 
 paul@1007    144 
From the very start, the nature of data organisation for calendar users
 
 paul@1007    145 
was centred on the storage of each user's free/busy records, since the
 
 paul@1007    146 
priority was to generate such records from messages exchanged over e-mail,
 
 paul@1007    147 
and the use of plain text files was chosen as the simplest and most
 
 paul@1007    148 
transparent approach. Beyond this, the need to retain calendar objects
 
 paul@1007    149 
arose, and thus a [[../FilesystemUsage|filesystem-based approach]] was
 
 paul@1007    150 
cultivated to manage such data.
 
 paul@1007    151 
 
 paul@1007    152 
In the future, other persistence mechanisms could be supported. However,
 
 paul@1007    153 
aside from performance concerns around access to free/busy schedules,
 
 paul@1007    154 
there may be no urgent need to adopt relational database technologies,
 
 paul@1007    155 
particularly as each user's data should remain isolated from that of
 
 paul@1007    156 
other users, and thus the volumes of data should remain relatively small
 
 paul@1007    157 
if managed well enough.
 
 paul@1009    158 
 
 paul@1009    159 
== Localisation ==
 
 paul@1009    160 
 
 paul@1009    161 
The traditional [[https://www.gnu.org/s/gettext|gettext]] mechanisms for
 
 paul@1009    162 
translating labels, messages and other user-readable strings are employed
 
 paul@1009    163 
in the imip-agent code. Some tools have been provided to maintain this
 
 paul@1009    164 
localisation.
 
 paul@1009    165 
 
 paul@1009    166 
To extract "messages" from the code, run the `tools/i18n_messages.sh`
 
 paul@1009    167 
script:
 
 paul@1009    168 
 
 paul@1009    169 
{{{
 
 paul@1009    170 
tools/i18n_messages.sh
 
 paul@1009    171 
}}}
 
 paul@1009    172 
 
 paul@1009    173 
This produces a file called `imip-agent.pot` in the current directory,
 
 paul@1009    174 
and it also attempts to merge any new messages into the existing message
 
 paul@1009    175 
translations found in the `messages` directory. Such translation files
 
 paul@1009    176 
have the following form:
 
 paul@1009    177 
 
 paul@1009    178 
{{{
 
 paul@1009    179 
messages/xx_XX.imip-agent.po
 
 paul@1009    180 
}}}
 
 paul@1009    181 
 
 paul@1009    182 
Here, `xx` is usually an [[WikiPedia:ISO_639-1|ISO 639-1]] language code,
 
 paul@1009    183 
whereas `XX` is usually an [[WikiPedia:ISO_3166-1|ISO 3166-1]] country code.
 
 paul@1009    184 
 
 paul@1009    185 
Translators should inspect and edit their files in the `messages`
 
 paul@1009    186 
directory and then use the `tools/i18n_format.sh` script to generate the
 
 paul@1009    187 
translations that the software will use:
 
 paul@1009    188 
 
 paul@1009    189 
{{{
 
 paul@1009    190 
tools/i18n_format.sh
 
 paul@1009    191 
}}}
 
 paul@1009    192 
 
 paul@1009    193 
This installs the "compiled" translations into the `locale` directory in
 
 paul@1009    194 
a location of the following form:
 
 paul@1009    195 
 
 paul@1009    196 
{{{
 
 paul@1009    197 
locale/xx_XX/LC_MESSAGES/imip-agent.mo
 
 paul@1009    198 
}}}
 
 paul@1009    199 
 
 paul@1009    200 
The `tools/install.sh` script will copy the `locale` directory into the
 
 paul@1009    201 
installation location unless the `--no-locale-dir` option is given. This is
 
 paul@1009    202 
provided to allow any centrally-installed translations to take precedence
 
 paul@1009    203 
over any locally-available translations.