# HG changeset patch # User Paul Boddie # Date 1446750051 -3600 # Node ID 3273c34ff13c36f677565ae7808eab6274b48d26 # Parent ead8eeb668ff8cc6d77d3aab994fcb643f221d99 Added development-related documentation. diff -r ead8eeb668ff -r 3273c34ff13c docs/wiki/Developing --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/Developing Thu Nov 05 20:00:51 2015 +0100 @@ -0,0 +1,157 @@ += Developing imip-agent = + +To start developing the imip-agent software further, first obtain the code +by following the advice on the [[../Downloads|downloads page]]. Obtaining +the code directly from the repository is advisable since any changes you +make can then be tracked and managed. + +<> + +== Distribution Contents == + +The software distribution contains the following directories: + +{{{#!table +'''Directory''' || '''Description''' +== +`conf` +|| Example configuration files (see the +.. [[../GettingStarted|getting started guide]] for details) +== +`docs` +|| Documentation, including these wiki pages +== +`htdocs` +|| Resources for the [[../CalendarManager|management interface]] +== +`imiptools` +|| A Python package providing mail handling and support for calendar +.. object processing +== +`imipweb` +|| A Python package providing Web-related functionality for the +.. [[../CalendarManager|management interface]] +== +`messages` +|| Localised messages for the [[../AgentPrograms|agent programs]] and +.. [[../CalendarManager|management interface]] +== +`tests` +|| A suite of tests used to verify the behaviour of the software +.. (see the [[../Testing|testing guide]]) +== +`tools` +|| Tools for [[../Administration|administration]] (see also the +.. [[../GettingStarted|getting started guide]]) +}}} + +At the top level of the distribution, the following files are found: + +{{{#!table +'''File''' || '''Description''' +== +`imip_person.py` +|| The main program files for the + .. [[../AgentPrograms|agent programs]] +== +`imip_person_outgoing.py` +== +`imip_resource.py` +== +`imip_manager.py` +|| The [[../CalendarManager|management interface]] main program file +== +`imip_store.py` +|| The Python module providing an abstraction over the +.. [[../FilesystemUsage|data storage structures]] +== +`markup.py` +|| A Python library providing HTML generation support +== +`README.txt` +|| Some basic documentation +== +`vCalendar.py` +|| Handling of vCalendar and related data formats +== +`vContent.py` +== +`vRecurrence.py` +}}} + +== Architectural Components == + +The principal components of the software architecture are described below. + +=== vContent === + +The v-prefixed libraries are concerned with the basic interpretation of +calendar-related data. For the most part, these libraries should already +behave in a predictable and reliable fashion and should not need much +further development. There are perhaps some deficiencies in the +`vRecurrence` module that are described on the +[[../CalendaringSupport|calendaring standards page]]. + +It is not inconceivable that a `vCard` module be introduced in the future +to handle vCard data, thus enhancing the data about people within +imip-agent, perhaps also supporting mechanisms to obtain free/busy and +other information about scheduling participants. + +=== imiptools === + +The bulk of the work done in imip-agent happens within `imiptools`. When +used from [[../AgentPrograms|agent programs]] launched by the mail system, +the different modules support the "handler" functionality that involves +obtaining information from calendar data, performing the necessary action +related to a scheduling method, and generating responses or notifications. +More details are given about these activities in the guide to +[[../IncomingMessages|incoming message handling]]. + +When used from the [[../CalendarManager|management interface]], the +modules support the Web-based functionality as a more general calendar +system client, typically handling a single calendar object at any given +time. + +=== imipweb === + +Most of the `imipweb` package is concerned with the display of calendar +information as Web pages and the handling of submitted data over the Web +as users interact with those Web pages. The `imip_manager.py` file is +deployed as a [[https://tools.ietf.org/html/rfc3875|CGI]] program, and it +acts as a simple "switch" that shows the appropriate kind of Web page (or +"view") depending on the requested URL, delegating to one of the modules +within the `imipweb` package to do so: + +|| '''Module''' || '''View''' || +|| `imipweb.calendar` || Calendar || +|| `imipweb.event` || Individual events || +|| `imipweb.profile` || User profile || + +A general `imipweb.resource` module supports the different views with +common functionality. Useful abstractions for period and date information +are provided in the `imipweb.data` module. The CGI interfacing is defined +in the `imipweb.env` module. + +One of the most awkward aspects of providing a Web interface to events is +the need to provide a comprehensive enough representation of period data +as expressed in calendar objects that can be held in a form defined in a +Web page, interpreted by the program, written back to the form, all +without losing information. + +=== imip_store === + +The `imip_store` module provides the basis for calendar data persistence. +From the very start, the nature of data organisation for calendar users +was centred on the storage of each user's free/busy records, since the +priority was to generate such records from messages exchanged over e-mail, +and the use of plain text files was chosen as the simplest and most +transparent approach. Beyond this, the need to retain calendar objects +arose, and thus a [[../FilesystemUsage|filesystem-based approach]] was +cultivated to manage such data. + +In the future, other persistence mechanisms could be supported. However, +aside from performance concerns around access to free/busy schedules, +there may be no urgent need to adopt relational database technologies, +particularly as each user's data should remain isolated from that of +other users, and thus the volumes of data should remain relatively small +if managed well enough. diff -r ead8eeb668ff -r 3273c34ff13c docs/wiki/FrontPage --- a/docs/wiki/FrontPage Thu Nov 05 18:17:00 2015 +0100 +++ b/docs/wiki/FrontPage Thu Nov 05 20:00:51 2015 +0100 @@ -3,7 +3,7 @@ {{{#!table [[/Downloads|Downloads]] || [[/GettingStarted|Getting started]] || [[#Deployment|Deployment]] || [[#Usage|Usage]] || -[[#Notes|Design/Implementation Notes]] || +[[#Development|Development]] || [[/CalendaringSupport|Support for Standards]] }}} @@ -150,8 +150,13 @@ * [[/Usage|Using imip-agent]] -<> -== Design and Implementation Notes == +<> +== Development == + +Some topics related to development: + + * [[/Developing|Developing imip-agent]] + * [[/FuturePlans|Future Plans]] Details of the mechanisms employed by imip-agent are described in the following documents: diff -r ead8eeb668ff -r 3273c34ff13c docs/wiki/FuturePlans --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/docs/wiki/FuturePlans Thu Nov 05 20:00:51 2015 +0100 @@ -0,0 +1,16 @@ += Future Plans = + +The intention is to continuously improve imip-agent to fix known problems +and to support missing features. Where it makes sense to do so, omissions +in the [[../CalendaringSupport|calendaring support]] should be addressed +as a matter of priority. + +Various other areas of improvement are described in the +[[../UseCases|use cases guide]], and the functionality of imip-agent should +be expanded to address such use cases. The intention is that imip-agent go +beyond supporting the manual scheduling of events by providing functionality +to automate scheduling and provisioning, employing readily-adopted tools and +techniques that are adaptable to existing standards-based infrastructure. + +See the [[../Development|development guide]] for more information on +improving imip-agent.