Policies/New KDE Library API Policy

Rational

From time to time it becomes apparent that new API needs to be added to KDE's libraries in kdelibs, kdepimlibs, etc. It may be in the form of new classes to existing libraries or entirely new libraries altogether.

However, the main KDE library modules have strict binary and source compatibility guarantees and it is nearly impossible to get an API perfect on the first round and without real world application usage. This is doubly true for API which results in changes to the user experience (e.g. new user interface elements, changes in workflow, etc.)

For this reason, unless the new class(es) or library are of a provably right nature (which usually means they fall into the realm of "trivial additions"), it is wise to release an experimental version of the classes as a separate library for use by applications before they find their way into an official KDE library release.

This policy describes what is currently considered as the best practice approach in such situations.

Source Code

The source code should appear in trunk/extragear/libs (or trunk/KDE/kdelibs-experimental?) in it's own subdirectory. It needs to be able to be built as an independent project from its directory there.

Library Naming

The name of the library should take the form lib<foo>-#.so where the number (#) part corresponds to which binary compatible release this is. Therefore such an experimental library addition containing the Greatness classes might install libgreatness-1.so in its first release and the next release that includes source of binary incompatible changes might install libgreatness-2.so.

This allows application developers to use the library without concerns of random application breakage due to upgrading the library.

Header Installation

Public headers should be installed into a directory that matches the name of the library. For example include/greatness-1.

This allows application developers to use the library without concerns of random compilation breakage due to upgrading the library.

Namespace Recommendation

If the code is still experimental and/or intended for inclusion in one of the existing KDE libraries, consider using the Experimental C++ namespace for the public classes. This will help remind application developers using this library that it is subject to change.

This is not, however, required.

Releases

A buildable tarball of the library must be released either before or in tandem with the KDE release in which applications are intended to use it. A tag should also be created marking the release.

Making the Transition to Stable Releases

Once there is reasonable confidence in the ABI and API of the new library or class(es), which may take one release or several to accomplish, then the library may be moved into kdelibs (or into the appropriate library in the case of classes) and no further independent releases are required.

Out of consideration, application developers should be given reasonable notice of this transition via appropriate mailing lists or other communication channels.