1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/docs/wiki/Developing Thu Nov 05 20:00:51 2015 +0100
1.3 @@ -0,0 +1,157 @@
1.4 += Developing imip-agent =
1.5 +
1.6 +To start developing the imip-agent software further, first obtain the code
1.7 +by following the advice on the [[../Downloads|downloads page]]. Obtaining
1.8 +the code directly from the repository is advisable since any changes you
1.9 +make can then be tracked and managed.
1.10 +
1.11 +<<TableOfContents(2,3)>>
1.12 +
1.13 +== Distribution Contents ==
1.14 +
1.15 +The software distribution contains the following directories:
1.16 +
1.17 +{{{#!table
1.18 +'''Directory''' || '''Description'''
1.19 +==
1.20 +`conf`
1.21 +|| Example configuration files (see the
1.22 +.. [[../GettingStarted|getting started guide]] for details)
1.23 +==
1.24 +`docs`
1.25 +|| Documentation, including these wiki pages
1.26 +==
1.27 +`htdocs`
1.28 +|| Resources for the [[../CalendarManager|management interface]]
1.29 +==
1.30 +`imiptools`
1.31 +|| A Python package providing mail handling and support for calendar
1.32 +.. object processing
1.33 +==
1.34 +`imipweb`
1.35 +|| A Python package providing Web-related functionality for the
1.36 +.. [[../CalendarManager|management interface]]
1.37 +==
1.38 +`messages`
1.39 +|| Localised messages for the [[../AgentPrograms|agent programs]] and
1.40 +.. [[../CalendarManager|management interface]]
1.41 +==
1.42 +`tests`
1.43 +|| A suite of tests used to verify the behaviour of the software
1.44 +.. (see the [[../Testing|testing guide]])
1.45 +==
1.46 +`tools`
1.47 +|| Tools for [[../Administration|administration]] (see also the
1.48 +.. [[../GettingStarted|getting started guide]])
1.49 +}}}
1.50 +
1.51 +At the top level of the distribution, the following files are found:
1.52 +
1.53 +{{{#!table
1.54 +'''File''' || '''Description'''
1.55 +==
1.56 +`imip_person.py`
1.57 +||<rowspan="3"> The main program files for the
1.58 + .. [[../AgentPrograms|agent programs]]
1.59 +==
1.60 +`imip_person_outgoing.py`
1.61 +==
1.62 +`imip_resource.py`
1.63 +==
1.64 +`imip_manager.py`
1.65 +|| The [[../CalendarManager|management interface]] main program file
1.66 +==
1.67 +`imip_store.py`
1.68 +|| The Python module providing an abstraction over the
1.69 +.. [[../FilesystemUsage|data storage structures]]
1.70 +==
1.71 +`markup.py`
1.72 +|| A Python library providing HTML generation support
1.73 +==
1.74 +`README.txt`
1.75 +|| Some basic documentation
1.76 +==
1.77 +`vCalendar.py`
1.78 +||<rowspan="3"> Handling of vCalendar and related data formats
1.79 +==
1.80 +`vContent.py`
1.81 +==
1.82 +`vRecurrence.py`
1.83 +}}}
1.84 +
1.85 +== Architectural Components ==
1.86 +
1.87 +The principal components of the software architecture are described below.
1.88 +
1.89 +=== vContent ===
1.90 +
1.91 +The v-prefixed libraries are concerned with the basic interpretation of
1.92 +calendar-related data. For the most part, these libraries should already
1.93 +behave in a predictable and reliable fashion and should not need much
1.94 +further development. There are perhaps some deficiencies in the
1.95 +`vRecurrence` module that are described on the
1.96 +[[../CalendaringSupport|calendaring standards page]].
1.97 +
1.98 +It is not inconceivable that a `vCard` module be introduced in the future
1.99 +to handle vCard data, thus enhancing the data about people within
1.100 +imip-agent, perhaps also supporting mechanisms to obtain free/busy and
1.101 +other information about scheduling participants.
1.102 +
1.103 +=== imiptools ===
1.104 +
1.105 +The bulk of the work done in imip-agent happens within `imiptools`. When
1.106 +used from [[../AgentPrograms|agent programs]] launched by the mail system,
1.107 +the different modules support the "handler" functionality that involves
1.108 +obtaining information from calendar data, performing the necessary action
1.109 +related to a scheduling method, and generating responses or notifications.
1.110 +More details are given about these activities in the guide to
1.111 +[[../IncomingMessages|incoming message handling]].
1.112 +
1.113 +When used from the [[../CalendarManager|management interface]], the
1.114 +modules support the Web-based functionality as a more general calendar
1.115 +system client, typically handling a single calendar object at any given
1.116 +time.
1.117 +
1.118 +=== imipweb ===
1.119 +
1.120 +Most of the `imipweb` package is concerned with the display of calendar
1.121 +information as Web pages and the handling of submitted data over the Web
1.122 +as users interact with those Web pages. The `imip_manager.py` file is
1.123 +deployed as a [[https://tools.ietf.org/html/rfc3875|CGI]] program, and it
1.124 +acts as a simple "switch" that shows the appropriate kind of Web page (or
1.125 +"view") depending on the requested URL, delegating to one of the modules
1.126 +within the `imipweb` package to do so:
1.127 +
1.128 +|| '''Module''' || '''View''' ||
1.129 +|| `imipweb.calendar` || Calendar ||
1.130 +|| `imipweb.event` || Individual events ||
1.131 +|| `imipweb.profile` || User profile ||
1.132 +
1.133 +A general `imipweb.resource` module supports the different views with
1.134 +common functionality. Useful abstractions for period and date information
1.135 +are provided in the `imipweb.data` module. The CGI interfacing is defined
1.136 +in the `imipweb.env` module.
1.137 +
1.138 +One of the most awkward aspects of providing a Web interface to events is
1.139 +the need to provide a comprehensive enough representation of period data
1.140 +as expressed in calendar objects that can be held in a form defined in a
1.141 +Web page, interpreted by the program, written back to the form, all
1.142 +without losing information.
1.143 +
1.144 +=== imip_store ===
1.145 +
1.146 +The `imip_store` module provides the basis for calendar data persistence.
1.147 +From the very start, the nature of data organisation for calendar users
1.148 +was centred on the storage of each user's free/busy records, since the
1.149 +priority was to generate such records from messages exchanged over e-mail,
1.150 +and the use of plain text files was chosen as the simplest and most
1.151 +transparent approach. Beyond this, the need to retain calendar objects
1.152 +arose, and thus a [[../FilesystemUsage|filesystem-based approach]] was
1.153 +cultivated to manage such data.
1.154 +
1.155 +In the future, other persistence mechanisms could be supported. However,
1.156 +aside from performance concerns around access to free/busy schedules,
1.157 +there may be no urgent need to adopt relational database technologies,
1.158 +particularly as each user's data should remain isolated from that of
1.159 +other users, and thus the volumes of data should remain relatively small
1.160 +if managed well enough.
2.1 --- a/docs/wiki/FrontPage Thu Nov 05 18:17:00 2015 +0100
2.2 +++ b/docs/wiki/FrontPage Thu Nov 05 20:00:51 2015 +0100
2.3 @@ -3,7 +3,7 @@
2.4 {{{#!table
2.5 [[/Downloads|Downloads]] || [[/GettingStarted|Getting started]] ||
2.6 [[#Deployment|Deployment]] || [[#Usage|Usage]] ||
2.7 -[[#Notes|Design/Implementation Notes]] ||
2.8 +[[#Development|Development]] ||
2.9 [[/CalendaringSupport|Support for Standards]]
2.10 }}}
2.11
2.12 @@ -150,8 +150,13 @@
2.13
2.14 * [[/Usage|Using imip-agent]]
2.15
2.16 -<<Anchor(Notes)>>
2.17 -== Design and Implementation Notes ==
2.18 +<<Anchor(Development)>>
2.19 +== Development ==
2.20 +
2.21 +Some topics related to development:
2.22 +
2.23 + * [[/Developing|Developing imip-agent]]
2.24 + * [[/FuturePlans|Future Plans]]
2.25
2.26 Details of the mechanisms employed by imip-agent are described in the
2.27 following documents:
3.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
3.2 +++ b/docs/wiki/FuturePlans Thu Nov 05 20:00:51 2015 +0100
3.3 @@ -0,0 +1,16 @@
3.4 += Future Plans =
3.5 +
3.6 +The intention is to continuously improve imip-agent to fix known problems
3.7 +and to support missing features. Where it makes sense to do so, omissions
3.8 +in the [[../CalendaringSupport|calendaring support]] should be addressed
3.9 +as a matter of priority.
3.10 +
3.11 +Various other areas of improvement are described in the
3.12 +[[../UseCases|use cases guide]], and the functionality of imip-agent should
3.13 +be expanded to address such use cases. The intention is that imip-agent go
3.14 +beyond supporting the manual scheduling of events by providing functionality
3.15 +to automate scheduling and provisioning, employing readily-adopted tools and
3.16 +techniques that are adaptable to existing standards-based infrastructure.
3.17 +
3.18 +See the [[../Development|development guide]] for more information on
3.19 +improving imip-agent.