Added documentation

6 files changed, 223 insertions, 0 deletions

diff --git a/.gitignore b/.gitignore
index 45034c74..3ef8fe7f 100644
--- a/.gitignore
+++ b/.gitignore
@@ -3,3 +3,4 @@
 *.diff
 *.patch
 *.swp
+site
diff --git a/docs/design.md b/docs/design.md
new file mode 100644
index 00000000..2e2b6997
--- /dev/null
+++ b/docs/design.md
@@ -0,0 +1,94 @@
+# Architecture / Design
+
+## Overview
+Kontact Quick is supposed to be a small and concise codebase that is easy to modify and evolve.
+
+It's following a reactive model, where in one direction we have controllers generating modifications, and in the other direction models updating themselves on changes.
+
+The overall architecture is split into three layers; Ui, Domain Logic and Infrastructure.
+
+```
++----------------------------+
+|             UI             |
++----------------------------+
+|                            |
+|        Domain Logic        |
+|                            |
++--------------+------+------+
+|              |      |      |
+| Akonadi Next |Config| ...  |
+|              |      |      |
++--------------+------+------+
+```
+
+The UI Layer consists of views (mostly written in QML), view-models (models that are view specific and potentially implement user interaction details), and the glue code to use various controllers from the interface. Different UI layers may exist for different form factors.
+
+The domain logic layer holds the application state. It povides models to access data and controllers to act upon it. The domain logic is by definition Kontact Quick specific and not sharable with other applications, at it needs to be taylored exactly according to the requirements of Kontact Quick.
+
+The infrastructure layer provides:
+
+* Data access (Akonadi Next)
+* Configuration (Config files, etc.)
+* Various functionality provided by libraries (email sending, ldap, iTip handling, iCal implementation (kcalcore), vCard implementation, ...)
+Various bits of the infrastructure layer may be exchanged on different platforms, to i.e. integrate into native infrastructure providers on a platform.
+
+Note: By using the onion architecture we ensure the infrastructure is exchangable just as well as the UI.
+
+## Domain Logic
+
+### Models
+Self-updating models are used to implement the read-only part of the application.
+By using QAbstractItemModels we can reuse the existing update mechanism, have something that works well with QML, and avoid implementing a boatload of boilerplate code for hand-coded domain objects.
+
+Models should always be reactive and configured with a query, so they are asynchronous.
+
+By implementing everything according to that model we can later on achieve lazy-loading of properties and zero-copy (or at least close to zero-copy) directly from storage without modifying anything besides data access.
+
+### Controllers
+Use-case specific controllers are used to operate on the data. Controllers allow to completely separate the modifications from the view.
+Rather than splitting controllers by domain type (e.g. an email controller, or a calendar controller), we specifically write controllers for specific usecases (e.g. an email editor), that exposes all required actions. That way we ensure that the API's a UI is working with is always clear an consice, and that we have all domain logic captured in the domain logic layer, rather than the UI layer.
+Of course controllers will need to share functionality internally as soon as an action is available from more than one place.
+
+## Infrastructure
+
+The infrastructure layer interfaces with the rest of the system. It is the place where we can integrate with various native infrastructure parts.
+
+### Akonadi Next
+Akonadi Next is used for primary data access and handles all synchronization.
+
+### Configuration
+Configuration as traditionally store in config files in ~/.kde
+
+### Notification
+Notifications for the system.
+
+### Files
+Store/Load/Shared stuff (attachments, events, ....)
+* Additional to the basic store/load stuff that may need further abstraction for mobile platforms beyond what qt provides.
+* Android Intents/Libpurpose (share with various applications etc).
+
+### Import/Export
+Same as files? Import/Export calendar data
+
+### RFC implementations
+* iCal: KCalCore
+* vCard: KContacts
+* iTip: extract from kdepim repo
+
+### Cryptography
+* PGP, PEP
+* ObjectTreeParser
+
+Keyselection, encryption, decryption, signing
+Probably requires access to identities in some way.
+
+### MIME-Message parsing
+* ObjectTreeParser
+* KMime
+
+## Interaction with external applications
+External applications, like the KDE calendar plasmoid, should be able to load parts of Kontact Quick when available. It should for instance be possible to load the Event editor as embeddable QML component, that is fully functional. That way it becomes very easy for third parties to provide extra functionality if Kontact Quick is installed, without having to reimplement the Domain Logic (as is the case if only data access is provided through akonadi).
+
+The same mechanism should probably be used by Kontact Quick itself to ensure loose coupling and allow mashups with various content types.
+
+Note: We'll probably want a component-viewer application to easily load and test individual components (similar to plasmoidviewer).
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..e6a7193c
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,4 @@
+# Documentation
+This documentation is built using [mkdocs.org](http://mkdocs.org).
+
+Use `mkdocs serve` to run a local webserver to view the docs.
diff --git a/docs/project.md b/docs/project.md
new file mode 100644
index 00000000..85778eee
--- /dev/null
+++ b/docs/project.md
@@ -0,0 +1,38 @@
+# Vision
+Kontact Quick aims to be an enterprise-ready PIM solution, that has a high-quality and rock solid core. The focus of the core is on high-quality code, maintainability, stability and performance.
+
+We strive to keep the core to the necessary minimum, with minimal dependencies and maximum portability, and in a way that it is maintainable by a small team.
+We also strive to keep the solution agile so that work by corporate partners can be executed upstream.
+
+Experimental or advanced features are supported as optional addons, to not affect the high quality of the core product.
+
+Kontact Quick aims to be available on various form-factors and platforms.
+
+# Project Structure
+While this is an open project that welcomes participation from everyone who's interested, we do have an explicit team strucuture to ensure it's clear to everyone who's repsonsible for what. External contributions are alwas welcome and the team is of course open for extension.
+
+Team Lead: Christian Mollekopf
+Team Members: Michael Bohlender, Sandro Knauss, Aaron Seigo
+
+It's the team leads responsibility to:
+
+* Organize regular online meetings (medium yet unknown)
+* Give direction to the product and ensure it's followed.
+* Direct development and oversee decisions
+* Ensure documentation of decisions
+
+## Decision making process
+Decisions are generally made in discussion with the team, and result in documentation or an item on the roadmap. Non-trivial decisions are always either discussed on the mailinglist or in an online meeting.
+
+Should the team not be able to reach consensus, the team lead makes the final decision.
+
+NOTE: We should probably have a phabricator board for open decisions.
+
+## Planning
+All planning happens on the KDE Phabricator instance: https://phabricator.kde.org/project/view/43/
+
+## Releases / Milestones
+Releases will follow achieved milestones. Milestones are assembled from tasks on the roadmap.
+
+## Versioning
+The product will follow the semantic versioning scheme (semver.org), with each feature release corresponding to a milestone on phabricator.
diff --git a/docs/requirements.md b/docs/requirements.md
new file mode 100644
index 00000000..1b1f5f24
--- /dev/null
+++ b/docs/requirements.md
@@ -0,0 +1,85 @@
+# Personas
+Note: This is a draft only
+
+## Roadwarrior
+* Fires up Kontact quickly to see what's up next (it's not constantly open)
+* Has to deal with bad/intermitted network connection
+* Relies on offline capabilities to access content
+* Uses various mobile devices
+
+## Average Desktop User
+* Relies on notifications to immediately see when he's contacted.
+* Requires a simple and efficient UI
+* Doesn't customize a lot
+* Has constant internet access
+* Works 9 to 5, doesn't care outside of business hours
+
+## Power Desktop User
+* Inherits Average Desktop User Requirements
+* Regularly checks email on the go (mobile)
+* Regularly checks calendar on the go (mobile)
+* Creates events on the go (mobile)
+
+# Kontact Inventory
+We need to go through the current codebase, assess what features are available, how the implementation looks and where it is, and to what extent the code is reusable.
+This will help us in figuring out the useful feature set, and will allow us to reuse the lessons learned that are embedded in the codebase.
+
+This inventory is currently hosted in an ikiwiki (ikiwiki.info) git repository(kde:scratch/aseigo/KontactCodebaseInventory.git)
+
+# Target platforms
+The codebase is supposed to be portable across a range of platforms.
+Initially we'll work on a reasonably recent linux distribution though.
+
+The aimed for minimum bar is:
+
+Linux:
+
+* Fedora 22
+* Ubuntu 12.04
+* Centos/RHEL 7
+
+Windows:
+
+* 7sp1
+
+OS X:
+
+* ?
+
+Android:
+
+* 5.0
+
+# Dependencies
+Since the codebase needs to be portable across various platforms old and new, dependencies should be managed that they are as little and as low as possible. While we don't want to reinvent the wheel constantly or work with ancient technology, each additional dependency or dependency bump needs to be justified and we need to evaluate wether that results in a problem with any of the target platforms. This evaluation of course includes transitive dependencies.
+
+Currently available dependencies:
+
+* GCC 4.6.3 / MSVC 2013
+* Qt 5.2
+
+# Codebase
+
+## Requirements
+* Each module has at least rudimentary tests that can then be extended
+    * Tests need to be deterministic, no random timeouts to check if something already happened, only `QTRY_VERIFY` and alike is allowed.
+* Clear layering. No depending on akonadi from everywhere.
+* Each module comes with a clear set of justified dependencies.
+* Commented code is only allowed in conjunction with a task in phabricator. No dead/commented code.
+* Each module requires a clear interface that allows the module internals to be replaced eventually.
+* UI modules need to be separated from non-UI parts. All UI parts need to be eventually replacable by QML equivalents.
+* No dialogs in non-UI parts.
+* New features are only added after having been selected from the roadmap for a future release
+* An accounts based configuration for everything
+* No non-persistant data in config files (collection ids...)
+
+* No KParts
+* No KXMLGui
+
+## Guidelines
+* Singletons that hold a modifyable state should be avoided.
+* Where standards are available we strive to follow those, and deviations from the standard are avoided as much as possible. Repurposing of standard elements should be avoided altogether.
+* Fallbacks (i.e. for configs ), should be applied in a single place only, and should be avoided wherever possible.
+* Libraries need to be purpose built and with clear responsibilities. No artificial boundaries that don't help something.
+* Modal dialogs should be avoided.
+
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 00000000..30b80930
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1 @@
+site_name: Kontact Quick