'whats up with those libs?'

[prev in list] [next in list] [prev in thread] [next in thread] 

List:       koffice-devel
Subject:    whats up with those libs?
From:       Thomas Zander <zander () kde ! org>
Date:       2009-12-31 13:50:01
Message-ID: 200912311450.01429.zander () kde ! org
[Download RAW message or body]

from recent conversations I noticed some confusion about goals and purpose of 
the libs work we are doing.
I thought its needed to send an update here, and rehash the timeline and 
issues we face.

The high level overview is that KOffice since 2.0 becomes a lot more powerful 
for 3rd party developers because of our plugin frameworks.
I count 12 plugin types in the libs alone. Krita has some more on top of that.

Now, as anyone that has been involved in any porting of API knows (Qt3->Qt4?) 
or even just making stuff work with changing APIs (graphicsmagick?) the only 
way to make those 3rd party developers no us for any change we make is to make 
our libraries binary compatible, source compatible and behavior compatible.
This is why you can write an app against Qt4.2 and still have it work without 
recompile in Qt4.6.

So, if we want to be taken seriously and we want to have more people develop 
exciting plugins on top of KOffice, we need to have several libs to be BC+SC.
At the Oslo meeting we agreed that we'll merge some libs and work on getting 
others ready for binary compatibility. [1] Boud and me are working on that. 
Help very much appreciated.

What happened so far
============

When I started the majority of the classes in Flake were not following the 
library guidelines which are there to make it possible to keep BC in the 
future. This is really the first step we have to make. I can't stress this 
enough; we have to follow those library guidelines[2] since any class that we 
have in there will essentially become forget-ware.  We can't really do much 
with a class that has variables or is just unfinished.
To clarify; you can not remove or add or even change any variables defined on a 
class.
You can't remove add or change any virtual methods.
You can't remove or rename any methods.
You can't change the arguments or any method.
And there is more, see [1].

So, those library guidelines[2] exist for a reason. Very smart people wrote 
them (KDELibs people, mostly).

Timeline;
=====
* First the classes in the library have to be made maintainable; which means 
follow the library guidelines.

* Second we should have a couple of rounds of API reviews. I started one 
already some time ago on naming of abstract classes.
We should have more reviews to make sure our classes are consistent and nice. 
As we can never ever change them after we freeze anymore.

* We freeze the API and impose BC/SC of the library of choice.  This will 
likely coincide with a release, I'm still hoping for 2.2 for this to happen.

* New additions to the lib should have a review done before we commit it. They 
should follow the library policy before they are commited too, naturally.
This includes adding a \since API-docs tag to those new classes or methods.

* party and conqueror the world.

The observant reader might have noticed that when we reach the point where we 
freeze the API the refactor count will essentially go to zero. Simply because 
it would break binary compatibility if we did. So, good news; the refactor 
pain will stop soon :)
Even faster if more people help out.

Anyone that has a class in a lib that will be frozen (currently libodf and 
libflake are the only ones on the agenda) are encouraged to see if their class 
might be better off moving to either kowidgets or komain or even to a plugin or 
an application for a little while.
Just temporary while the classes are getting improved and reviewed etc to a 
point where we have a good feeling they will be safe to impose binary 
compatibility on. Then they can be placed in the public libs.

Anyone that has a class in a lib that will be frozen is highly encouraged to 
help with writing API docs, making the class d-pointer safe and moving any 
private methods / slots and possibly protected methods to the Private class.

Any questions are welcome too :)

1) http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B
2) http://techbase.kde.org/Policies/Library_Code_Policy and 
http://techbase.kde.org/Policies/Library_Documentation_Policy
-- 
Thomas Zander
_______________________________________________
koffice-devel mailing list
koffice-devel@kde.org
https://mail.kde.org/mailman/listinfo/koffice-devel
[prev in list] [next in list] [prev in thread] [next in thread] 