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 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, metainfo.yaml...
• More comprehensive documentation go into a docs subdirectory
• The source code for the targets go into src subdirectory, if several payloads are built (like a core lib and a gui layer on top) then src will contain one subdirectory per library: core, gui, widgets, etc.
• All license texts go into a LICENSES subdirectory (following the REUSE.software specification)
• 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 lifetime, for more details see the binary compatibility policy.

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 use Qt's categorized logging

Frameworks make use of Qt's categorized logging system. with standardized logging categories. This is described in the Frameworks Logging 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 Qt requirements

KDE Frameworks are tested and working with the last 3 minor Qt releases. For instance, once Qt 5.11 was released, the minimum required Qt version changed from Qt 5.8 to Qt 5.9, i.e. the three supported Qt versions became 5.9, 5.10 and 5.11.

In addition, a Qt LTS release remains supported until the next Qt release after the next Qt LTS release. For instance, when Qt 5.12 is released, Qt 5.9 remains supported until Qt 5.13, to give time for people to migrate from Qt 5.9 LTS to Qt 5.12 LTS. When Qt 5.13 is released, both Qt 5.9 LTS and Qt 5.10 are dropped, to go back to "last 3 minor Qt releases".

With Qt6 this changes a little bit again. We interpolate "as if" more Qt 5 versions would be released:

• Qt 5.13 will be the minimum required version 6 months after Qt 5.15, i.e. on 26 Nov 2020
• Qt 5.14 would be the minimum required version 12 months after Qt 5.15, i.e. on 26 May 2021. With no-one known to stick with Qt 5.13 at the time, the date was moved to earlier mid-December 2020 (see discussion)
• Qt 5.15 LTS was planned to be the minimum required version 18 months after its release, i.e. on 26 Nov 2021. To help preparing for Qt 6, the date was moved to beginning of April 2021, as discussed in the KF6 sprint, and [1] confirmed in the next meeting.

The bumping of the minimum required version in the code is done at the begin of the release cycle of the next KF version affected, right after the release of the previous one.

Frameworks compiler requirements and Modern C++

The following minimal compiler versions are supported by KDE Frameworks (starting from version 5.82) :

• GCC 8
• Clang 6
• MSVC 2017

This means all of the C++11 and C++14 standards can be used, as well as most of C++17 (not std::filesystem).