Policies/New KDE Library API Policy

Rationale

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") or have been released with prior KDE releases as part of another module (and so have been tested and proven in practice), 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

For API destined for inclusion in kdelibs, the source code should appear in trunk/KDE/kdelibs/experimental in its own subdirectory. It needs to be able to be built as an independent project from within its directory there.

An example CMakeLists.txt file can be found here

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.1 in its first release and the next release that includes source of binary incompatible changes might install libgreatness-2.so.2.

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

Also remember to version the library symbols; this can be done in the CMakeLists.txt file with "set_target_properties(greatness-1 PROPERTIES VERSION 1.0.0 SOVERSION 1)", replacing the various names and version numbers as appropriate.

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 strongly recommend though not strictly 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.

API Review

API review should be asked for on the appropriate mailing lists, e.g. kde-core-devel at kde dot org for kdelibs, during the code's experimental phase. Application developers should also be engaged for feedback, and it is encouraged that the developer of the new API take an active role in helping applications use the new API.

Use of Experimental API in Applications

While an API is marked as experimental, usage by applications should in most cases be limited to applications that ship as part of the KDE Software Distribution. This makes it easier on packagers and distributors to work with us when it comes time to migrate from one version of the experimental lib to another or when it gets merged into kdelibs proper.

Note that not only the API is considered experimental, but all aspects of the functionality (D-Bus interfaces used internally, etc.). Therefore using such experimental API in applications that do not ship as part of the KDE Software Distribution means that the functionality can break with any update.

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, and the code meets the other requirements of library code such as API documentation, 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.

Any namespace used marking the code as experimental should be removed, and this will avoid symbol name collisions with applications that haven't yet updated away from the experimental library.

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