[Kde-pim] PIM Sprint: Porting PIM to Frameworks

[John Layt]

On 19 November 2013 22:59, Stephen Kelly <steveire at gmail.com> wrote:
> John Layt wrote:

> Those TODO tasks are very 'vertical'. Many tasks, and most useful tasks in
> frameworks porting, are horizontal. The horizontal tasks should largely be
> done before the vertical ones. Horizontal tasks are things like:
>
>  * Port existing code to modern APIs (eg port KBlog to KCalCore)
>  * Remove use of to-be-deleted code (eg KCal)
>  * Remove obsolete code (eg KCal)
>  * Make it build
>  ** Use compatibility layers (KDE4Support)
>  ** Update the C++ code for changes in Qt, KDE and upstreams
>  * Remove use of compatibility layers
>  ** Remove buildsystem use of KDE4Support
>  ** Remove C++ use of KDE4Support
>  ** Both of the above can be parallelized
>  * Make it cool
>  ** API updates
>  ** Refactoring
>
> That's the real todo list that should come before everything else you wrote
> in the wiki page. Note also that that todo list applies identically to *all*
> kde modules we're going to port. It also applied to the work already done in
> kdelibs.git.
>
> The point I want to stress is that you should focus on horizontal tasks when
> porting, not on vertical ones.

The idea of the wiki page was to set out the high level plan, document
what we currently have, and sketch out what we want the end-result to
be.  Your porting steps above then pick up from there once people
actually start working on it.  Call me old-fashioned waterfall model
guy, but I like to know where I'm heading first before breaking out my
code editor :-)

> Other steps already taken:
>
>  * Include-what-you-use - Add includes which are 'missing' on porting.
>  * Ensure that new conventions from KF5 such as C++11 language and library
> use don't conflict with existing code (see
> f237ca726d8ba66d377afaf0e3b5dce6b2d4e224 in kdepimlibs)
>  * Use Q_SLOTS and Q_SIGNALS.
>  * Replace kde4_add_library with add_library CMake command.
>  * Ensure that KF5::KDE4Support provides maximum SC.
>  ** This is what I've been doing lately. See gitk --author=steveire in kf5
>
> Note:
>  * All of these are 'clean up tasks'
>  * All of these should happen in master
>  * These are already happening. See gitk --author=steveire in kdepimlibs
>  * The above (partial) todo list is the same as should happen in all KDE
> modules we want to port. It should happen in the master branch. That makes
> the 'porting branch' small, readable, reviewable, and something others can
> learn from and replicate.
>  * We can use kdepim{,libs} porting as a validation of the SC goals of KF5
> and KDE4Support. The time-to-release goal trumped that so far for plasma and
> related. It's important for all others though, so we should ensure that a
> 'clean' (see above) KDE module is easy to port.

Cool, great to know that you've been working on this already :-)  Is
there a check-list and/or instructions somewhere for this stuff? Do
you need any help with these tasks, or are you happy to finish them
yourself?

>> We will drop all the old KResource
>> related code, KCal, and anything still using Qt3Support.
>
> Already done in my frameworks branch:
>
>  http://quickgit.kde.org/?p=clones%2Fkdepimlibs%2Fskelly%2Fetmwork.git&a=shortlog&h=f97c0b8eff8cc3ab9f7b60146465271c021b7f6e

Yay! \O/  I didn't realise you were so advanced with the porting, that
certainly changes a lot of what we discussed at the sprint, and the
timeframes for finishing the work.  If you had to guess at a timeframe
for how long before we can get to the point we can split, what would
it be?

>> We will have
>> a more relaxed approach than the kdelibs Frameworks and allow more
>> breaking of source compatibility like removing deprecated api and
>> renames.
>
> Good. That's something I'd certainly like to see more of in KF5 too. Time is
> the main reason that's not done there I think, because all resource and
> attention has been on 'splitting'. Much of kdelibs was written/designed in
> Qt 3 times and should be reviewed for modernness, appropriate use of more
> recent Qt APIs, resolving warnings (building KF5 shows *lots*) etc.

We also have the advantage that we have fewer clients using our
libraries, and when clients outside kdepim use them they have fairly
simple use cases.  That means the main people we 'hurt' with major api
changes are ourselves, so it's really for our own benefit :-)

>> We will also consider splitting existing libraries into
>> smaller libraries if they will be more useful, especially focusing on
>> the split between KDE integration, and the underlying libraries and
>> utilities that could be used by other PIM apps.
>
> Yes, I think libakonadi is a primary candidate here.

Another one discussed was IMAP support.  While Trojita won't use
KIMAP, Jan was interested in sharing some of the lower-level
utilities.  How achievable or useful that really is needs
investigation.

>> using Qt's tr() instead of
>> KDE's i18n() for lower tier frameworks.
>
> This shouldn't be a goal in places where it is hard. If it is trivial and
> worth it (eg drops 'home dependencies' from 1 to 0), then it can be done but
> otherwise should not be.

But where we know we want to make a library useful for external PIM
apps we don't want to be forcing them to pull in i18n, kconfig, and
all the rest.  If we know in advance that we want some libraries to be
that low-level then we know we have to solve any tr() issues that may
crop up, just like in kdelibs.  KDE integration level libraries
obviously should stick with i18n().  That may affect how we decide to
split things up so needs thinking about.

>> * Make any internal splits, code moves, and library renaming required
>> * Split kdepimlibs
>> * Do api and code clean-ups, port away from kde4support, etc
>
> This should happen before the two above it. It is 'largely horizontal'.

The main reason for suggesting doing it in that order was so that
high-priority libraries could be released sooner than low-priority
ones, if we wait for all of kdepimlibs to be cleanly ported before
splitting then that could delay libraries needed by Plasma 2.
However, given how advanced you seem to be then timing may not be as
much of an issue as expected.

>> * Review the wiki page to ensure the information there is correct
>
> You may want to revise it with the list of horizontal tasks and other
> information from this mail.

It's a wiki for a reason :-)  But I'll add sections for the actual
porting steps you've documented, and revise the suggested release plan
to account for already having a functional frameworks branch and your
other suggested steps.

>> MAINTAINERS need to perform the following steps before the frameworks
>> branch is forked:
>>
>> * Decide what Code Units are to be deleted
>> * Document the dependencies required for the Unit
>
> Why is this a prerequisite to a frameworks branch?

>> * Take a guess at the Frameworks Tier to aim for
>
> Also not relevant, and not a prerequisite to a frameworks branch.

Not prerequisites, but we were working on the basis that nothing had
been done yet and we'd have 2-3 months before we'd be starting work,
so we could make use of the time to think about what we want to do.

The prerequisites was so we have some idea about priorities, if
KCalCore depended on KMime, and KCalCore was a high priority, then
that would make KMime a high priority.  It also helps people focus on
whether a dependency is really required or not, or if things can be
split to make the dependencies tree more sensible (e.g. move a widget
elsewhere, lose a KDEUI dependency making it a lower tier library).
For example Volker has documented that KMime includes KCalendarSystem,
a quick check shows it should only be including KLocale, so that's a
clean-up to do in master.

The tier was because there's some things we know we want to make as
low a tier as possible and there's no harm in stating that up front as
it allows you to decide what needs to be changed in porting, mainly
around tr().

> I recommend:
>
>  * clean up master
>  * make frameworks build
>  * do frameworks todo tasks
>  ** split, move code around, API update etc.
>  ** Close master for significant updates at some point.
>  * As one of the last commits in kdepimlibs.git, run astyle
>  ** It might be an idea to do this in kdelibs.git too.
>  * Close kdepimlibs.git frameworks branch.
>  ** It remains for archeology with additional help from git grafts.
>  *** The astyle change being 'at the top' means that it won't get in the
> way.
>  * Split into multiple repos.

I'll copy that and your other points into the high-level plan and get
you to have another look after I'm done.  I think I'll need to split
things over a couple of pages now :-)

Cheers!

John.