NEWS + PIM README + autotools: updated for 1.3.99.1

3 files changed, 228 insertions, 1 deletions

diff --git a/NEWS b/NEWS
index 2db7f742..599655d7 100644
--- a/NEWS
+++ b/NEWS
@@ -1,3 +1,92 @@
+SyncEvolution 1.3.99.1, 25.10.2012
+==================================
+
+Development snapshot. The PIM Manager API implementation is fully
+implemented, see src/dbus/server/pim/README for an introduction.  The
+PBAP backend together with a new one-way caching sync mode provides an
+efficient way of keeping a local database in sync via Bluetooth with a
+phone which does not implement SyncML.
+
+Other changes:
+
+* workarounds for warnings from g++ 4.5
+
+* engine: : local cache sync mode
+
+  This patch  introduces support for true one-way syncing ("caching"):
+  the local datastore is meant to be an exact copy of the data on the
+  remote side. The assumption is that no modifications are ever made
+  locally outside of syncing. This is different from one-way sync modes,
+  which allows local changes and only temporarily disables sending them
+  to the remote side.
+
+  Another goal of the new mode is to avoid data writes as much as
+  possible.
+
+  This new mode only works on the server side of a sync, where the
+  engine has enough control over the data flow. Setting "sync" to:
+  - "local-cache-incremental" will do an incremental sync (if possible)
+    or a slow sync (otherwise). This is usually the right mode to use,
+    and thus has "local-cache" as alias.
+  - "local-cache-slow" will always do a slow sync. Useful for
+    debugging or after (accidentally) making changes on the local side.
+    An incremental sync will ignore such changes because they are not
+    meant to happen, aren't checked for to improve performance and
+    thus will leave client and server out-of-sync!
+
+  Both modes are recorded in the sync report of the local side. The
+  target side is the client and records the normal "two-way" or "slow"
+  sync modes.
+
+  With the current SyncEvolution contact field list, first, middle and
+  last name are used to find matches for contacts. For events, tasks
+  and memos, time, summary and description are used.
+
+* HTTP proxy: useProxy=0 overrides http_* env variables
+
+  Previously, if http_proxy was set, a proxy was used even if
+  explicitly disabled. This prevented disabling the use of a proxy
+  which only made sense in some cases, like accessing something
+  that runs locally. Explicitly telling SyncEvolution to ignore
+  http_proxy is necessary because it doesn't support no_proxy.
+
+* WebDAV: auto-discovery fix
+
+  With Google Contact + CardDAV the auto-discovery failed after
+  finding the default address book, without reporting that result.
+
+* command line: implement --create/remove-database
+
+  Creating a database is only possible with a chosen name. The UID is
+  chosen automatically by the storage. Only implemented in the EDS
+  backend.
+
+* file backend: sub-second mod time stamps
+
+  Change tracking in the file backend used to be based on the
+  modification time in seconds. When running many syncs quickly (as in
+  testing), that can lead to changes not being detected when they happen
+  within a second. Now the file backend also includes the sub-second part of the
+  modification time stamp, if available.
+
+  This change is relevant when upgrading SyncEvolution: most of the
+  items will be considered "updated" once during the first sync after
+  the upgrade (or a downgrade) because the revision strings get
+  calculated differently.
+
+* D-Bus server: avoid progress outside of 0-100% range
+
+  For example in the new TestLocalCache.testItemDelete100, the
+  percentage value in the ProgressChanged signal become larger
+  than 100 and then revert to 100 at the end of the sync.
+
+  Seems the underlying calculation is faulty or simply inaccurate.
+  This is not fixed. Instead the result is just clipped to the valid
+  range.
+
+* code cleanup + improvements in testing
+
+
 SyncEvolution 1.3 -> 1.3.1, 05.10.2012
 ======================================
 
diff --git a/configure.ac b/configure.ac
index 38eb196b..4a957425 100644
--- a/configure.ac
+++ b/configure.ac
@@ -8,7 +8,7 @@ dnl Invoke autogen.sh to produce a configure script.
 #
 # Starting with the 1.1 release cycle, the rpm-style
 # .99 pseudo-version number is used to mark a pre-release.
-AC_INIT([syncevolution], [m4_esyscmd([build/gen-git-version.sh 1.3.1])])
+AC_INIT([syncevolution], [m4_esyscmd([build/gen-git-version.sh 1.3.99.1])])
 # STABLE_VERSION=1.0.1+
 AC_SUBST(STABLE_VERSION)
 
diff --git a/src/dbus/server/pim/README b/src/dbus/server/pim/README
index 724acee4..4ea89c59 100644
--- a/src/dbus/server/pim/README
+++ b/src/dbus/server/pim/README
@@ -1,3 +1,6 @@
+Overview
+========
+
 The code in this directory only gets compiled when SyncEvolution is
 configured with --enable-dbus-service-pim. It uses libfolks and the
 PBAP backend to implement a unified address book. This additional
@@ -16,10 +19,145 @@ and the core Server class:
   * direct access to SyncEvolution instead having to go through
     the http://api.syncevolution.org D-Bus API
 
+Compilation
+===========
+
+Use --enable-dbus-service-pim --enable-pbap --enable-ebook.
+
+--enable-ebook is already the default at the moment. It must not be
+  disabled.
+
+The PBAP backend can be disabled. However, then fetching data from
+phones via PBAP obviously does not work.
+
+
+More information
+================
+
+Public discussion started here, comments can be sent via the gmane
+"reply" feature:
+http://comments.gmane.org/gmane.comp.mobile.syncevolution/4009
+
+Issues specific to PIM Manager can be found in this graph:
+https://bugs.freedesktop.org/showdependencygraph.cgi?id=55916&display=web&rankdir=TB
+
+
+Dependencies
+============
+
+A fairly recent libfolks > 0.7.4 is required. The 837a88 commit
+is required and several other pending changes are recommended:
+
+https://bugzilla.gnome.org/show_bug.cgi?id=686693
+writing birthday lacks conversion from UTC
+
+https://bugzilla.gnome.org/show_bug.cgi?id=685401
+linking by email
+
+https://bugzilla.gnome.org/show_bug.cgi?id=686695
+support nickname in add_persona_from_details
+
+Other requirements:
+* Evolution Data Server >= 3.6
+* boost::locale and libphonenumber (when using the default
+  sorting and searching)
+* glib >= 2.30
+* Python >= 2.7 (only for testing)
+
+
+Known issues
+============
+
+https://bugzilla.gnome.org/show_bug.cgi?id=652659
+Modifying many properties in a contact is inefficient and can deadlock in EDS.
+
+
+Extending the implementation
+============================
+
+Sorting and searching can be replaced with a different implementation
+at compile time via --enable-dbus-service-pim[=<locale>]: it uses the
+file src/dbus/server/pim/locale-factory-<locale>.cpp to implement
+sorting and searching.
+
+Any additional library dependencies for that file need to be added to
+the main configure.ac.
+
+
+Sorting + Searching
+===================
+
+The default implementation is based on boost::locale and libphonenumber.
+It is documented in pim-manager-api.txt.
+
+Lookup and search are different: the former is based on a valid
+number, the later on user input.
+
+A 'phone' lookup can compare normalized numbers including the country
+code, to ensure that the lookup is exact and does not mismatch numbers
+from different countries. Heuristics like suffix matching do not do
+this correctly in all cases.
+
+An 'any-contains' search is based on user input, which might contain
+just some digits in the middle of the phone number. The search ignores
+formatting in both input and address book.
+
+In both cases, alpha characters are treated as aliases for their
+corresponding digit on a keypad when matching phone numbers.
+
+In addition, an empty string as sort order picks a simple, ASCII-based
+"last/first" sorting. This is used for testing.
+
+
+Configuration and data handling
+===============================
+
+The configuration of peers is mapped to normal SyncEvolution
+configurations. Every peer gets its own context, which contains both
+the local source definition for the peer and sync plus target configs.
+The special name space prefix "pim-manager-" used to identify them and
+avoid potential conflicts with normal SyncEvolution configurations.
+
+Look in ~/.config/syncevolution/pim-manager-* to find the
+configuration files.
+
+Local EDS databases are created with a fixed UID and name that also
+have that prefix. One could go one step further than it is currently
+done and set these databases to "disabled" in the ESourceRegistry,
+which would hide them in Evolution.
+
+The SyncEvolution command line can be used to view or manipulate
+these databases:
+https://syncevolution.org/wiki/item-operations
+
+The persistent configuration of the sort order is stored in
+~/.config/syncevolution/pim-manager.ini as the "sort" property. It's
+values are the same string as in the API.
+
 
+Testing
+=======
 
+Tests are mostly written in Python. See test/test-dbus.py (base
+classes and testing of the normal SyncEvolution D-Bus API) and
+src/dbus/server/pim/testpim.py.
 
+These operations manipulate the system address book. To avoid
+unexpected data loss when a developer runs the script in his
+normal environment, check that testpim.py gets run like this:
 
+  XDG_CONFIG_HOME=`pwd`/temp-testpim/config \
+  XDG_DATA_HOME=`pwd`/temp-testpim/local/cache \
+  PATH=<SyncEvolution install path>/bin:<SyncEvolution install path>/libexec:$PATH \
+       <path to SyncEvolution source>/test/dbus-session.sh \
+       <path to SyncEvolution source>/src/dbus/server/pim/testpim.py
 
+This will use temp-testpim in addition to temp-testdbus in the current
+directory for temporary files.
 
+If TEST_DBUS_PBAP_PHONE is set to the Bluetooth MAC address (like
+A0:4E:04:1E:AD:30) of a phone, PBAP syncing with that phone is tested.
 
+The phone must be paired, connected and support SyncML in addition to
+PBAP. The test hard-codes Nokia SyncML settings to keep it simpe and
+because Nokia phones are most likely to be used.