[Evolution-hackers] Upcoming evolution-data-server API changes (libical-glib + more)

[Milan Crha <mcrha redhat com>]

        Hello,
this is kind of heads-up e-mail about upcoming API changes in
evolution-data-server. I also do not like them, but they are sometimes
necessary.

The first part is about porting the calendar to use libical-glib [1],
instead of libical, in order to finally provide introspection for it.
The change was so huge that it deserved an API bump from 1.2 to 2.0
(libecal-1.2 and libedata-cal-1.2 will become libecal-2.0 and
libedata-cal-2.0). The API around ECalComponent and its structures had
been made introspection friendly too. I took the opportunity and
removed all the deprecated and obsolete stuff from libecal and
libedata-cal. This work depends on the unreleased libical git master,
but there's planned a 3.0.5 release of it with the necessary changes.

The second part was about preparation for passing flags from the client
towards the backend to influence behavior. It was initially meant for
this issue [2], but I extended it to pass also information about
conflict resolution for write operations. This change touched all the
APIs - the client side API, the server side API and the D-Bus API. The
last is probably the most disturbing, at least in case of the Flatpak
applications, which build against some version of the evolution-data-
server, but rely on the host system evolution-data-server (it's
possibly broken on both sides, aka building with new eds, but run with
old, or build with old eds, but run with new). I'd say the best option
for such applications is to run the eds services inside the Flatpak
sandbox, which has the advantage that also the server side fixes are
included in the application, not only the client side fixes. It has a
downside, the downloaded data and configurations are not shared with
the system. I guess it's a downside of Flatpak in general, but that's
only my opinion.

I made the same changes (for the [2]) for libebook, libebook-contacts
and libedata-book, where I also changed some defines (added E_ prefix)
and dropped EDataBookStatus error enum, which had not been really
needed (similarly as I dropped EDataCalCallStatus). It could be
replaced with EClientError and EBookClientError. As with the calendar,
this touched the D-Bus API too. These book changes are quite
straightforward.

All the changes are prepared in this side branch:
https://gitlab.gnome.org/GNOME/evolution-data-server/tree/wip/mcrha/libical-glib
The 'make check' passes without errors.

I already have prepared evolution, evolution-ews and evolution-mapi,
though only as a buildable. The testing is to-be -done, I only didn't
want to block this due to these three projects. Looking into the other
API users, I found these hosted on GNOME:

   almanah
   bijiben
   california
   ekiga
   evolution-activesync
   folks
   glabels
   gnome-calendar
   gnome-contacts
   gnome-phone-manager
   gnome-shell
   gnome-todo

I plan to create 'wip/mcrha/eds-libical-glib' branches in each and help
with porting as much as I can. The idea is that the maintainers will
just merge the branch changes and it'll be all (from the coding point
of view). I know the branch name is inaccurate for the book changes,
but I decided to keep all these things in one branch for simplicity. I
believe it's better to break the API in a single release, instead of
doing that within multiple releases. It will make it easier for the
maintainers of the applications - the porting effort will be done only
once, not multiple times.

I have in my list these additional projects (to be verified whether any
changes are needed there and help with them if yes):

   elementary-calendar
   ffgtk
   libopensync-plugin-evolution2
   libreoffice
   pidgin-chime
   sflphone
   syncevolution
   wingpanel-indicator-datetime

If you know more, then feel free to let me know. I'll be happy to help
with the porting.

With respect of timing, my plan was to have the things prepared for
3.35.1, I expected that the changes will take longer, but it went quite
smoothly (well, actual testing will take some more time). I definitely
want to wait for an official release of libical 3.0.5 with the
necessary changes in its libical-glib part. Then we can decide,
depending in what state respective projects will be. Maybe it'll be
possible for 3.33.2 or shortly after it. I definitely do not want to
push this close to the end of the development phase, I'd rather do this
in the beginning of it, thus any third-party projects have enough time
for porting. That's another reason why I chose 3.35.1 initially.

I know this change will break some GNOME infrastructure, like the GNOME
Continuous effort, thus it's understandable to have the critical
projects prepared/ported first and commit the things (almost) at the
same time. This would need some coordination, which is another reason
for this e-mail.

I do not foresee any additional API changes currently, definitely not
on the D-Bus side, thus once this is done, the API should stay stable
for the next several years, I believe. Of course, everything depends on
the feature requests and similar needs, but from the past experience it
seems it will be fine.

        Bye,
        Milan

[1] https://gitlab.gnome.org/GNOME/evolution-data-server/issues/33
[2] https://gitlab.gnome.org/GNOME/evolution-data-server/issues/59