Frameworks/Policies

Frameworks have a Tier and a Type

Each framework has a clear position in the Tier/Type matrix, its position forces a set of rules on its possible dependencies. This matrix and its rules are summarized in the Frameworks matrix document.

The constraints from Tiers are the following:

• Tier 1 Frameworks can depend only on Qt official frameworks or other system libraries;
• Tier 2 Frameworks can depend only on Tier 1 Frameworks, Qt official frameworks, or other system libraries;
• Tier 3 Frameworks can depend only on other Tier 3 Frameworks, Tier 2 Frameworks, Tier 1 Frameworks, Qt official frameworks, or other system libraries.

The constraints from Types are the following:

• Functional Qt Addons cannot have runtime dependencies;
• Integration Qt Addons can have an optional runtime dependencies and aim at integrating with the underlying OS/Platform;
• Solutions have a mandatory runtime dependencies, it is part of their design and where their added value comes from (think scalability, resource sharing, resilience, etc.).

Framework directory structure

All the frameworks will have the same directory structure which will follow some rules:

• The containing directory has the name of the technology (plasma, kio, itemmodels, etc.);
• At the top level we find the common files like README.md, COPYING.LIB, metainfo.yaml...
• More comprehensive documentation go into a docs subdirectory
• The source code for the targets go into src subdirectory, if several payload are built (like a core lib and a gui layer on top) then src will contain one subdirectory per library: core, gui, widgets, etc.
• Code examples go into an examples subdirectory
• Automatic tests go into an autotests subdirectory
• Test applications go into a tests subdirectory
• CMake modules (FindFoo.cmake etc.) or CMake macro files go into cmake subdirectory

Frameworks have automatic unit tests

Enough said really... They must be unit tested with automatic unit tests.

Corollary: When fixing a bug in a framework, the auto-test proving the bug and the fix should come in the same commit.

Frameworks maintain binary compatibility

Just like we did in kdelibs, KDE Frameworks maintain the binary compatibility through their life time, for more details see the binary compatibility policy on techbase.

Note however that this policy is lifted during major version transition, corresponding epics of milestones will be marked as such.

Frameworks are documented

The API exposed by frameworks are documented using Doxygen. Documentation follows the Frameworks Documentation Policy.

Frameworks are localized

Frameworks adapt to the user language and locale settings. This is described in the Frameworks Localization Policy.

Frameworks buildsystem is consistent

• each framework should install a CMake configuration file for itself. This includes:
  • a FooConfig.cmake file
  • a FooConfigVersion.cmake file
  • usually a FooTargets.cmake file
  • optionally a file containing macros/functions for using the package
• no framework should install any other CMake files than mentioned above. Find-modules useful for multiple packages should be upstreamed into extra-cmake-modules if they are generally useful.
• For especially exotic packages which are not suitable for extra-cmake-modules, it is ok for a framework to have extra find modules, but they should not be installed.
• Library names are in CamelCase
• All dependencies between frameworks are documented in the CMakeLists.txt (see for instance kio/src/core/CMakeLists.txt)

For an example, see the framework-template directory in the kdeexamples repository (you can use setup.sh to create a template that matches the name of your framework).

Frameworks commits are reviewed

Make sure all commits in the master branch of a repository part of the KDE Frameworks got a proper review. As such commits must contain either a "Reviewed by:" (for quick pastebin reviews) or a "REVIEW:" (for more formal reviewboard reviews).

Frameworks CI failures are treated as stop the line events

When a commit causes a regression in the CI for one of the frameworks, then all work on the corresponding framework should stop. The only commits allowed in are those working toward a resolution of the problem. Only once the framework is green again that regular work can be resumed.

Frameworks compiler requirements and C++11

The following minimal compiler versions are supported by KDE Frameworks:

• gcc 4.5
• clang 3.1
• VS2012 (MSVC11)

In particular it impacts which part of the C++11 standard we can use unconditionally. So far only the following C++11 features can be used unconditionally in KDE Frameworks:

• auto;
• rvalue support (except for "*this");
• lambdas.

For other C++11 features, they can be used provided the following constraints are met:

• they must be made optional by the use of #ifdef or the Q_* macros (e.g. Q_DECL_OVERRIDE);
• both the binaries built with or without those extra features must be binary compatible.