Table of Content
Qt 5 product definition
This document summarizes the outcome of Qt5 product definition discussions at QtCS. This summary needs review and discussion, see the qt5-feedback mailing list.
The Qt5 product definition sessions at QtCS covered the naming, module structure, forward and backward compatibility promises, cross-platform promise, platform tiers, and high level principles about Qt releases.
The targets for the definition include
- Simple and clear structure and naming that works for existing users of Qt, new users of Qt, and creators of Qt, in all environments (desktop, embedded, mobile)
- Consistency between different parts of Qt and consistency between “marketing” and Real World
- There should be room for Qt Add-ons that provide additional benefits on specific environments, without bloating Qt for everyone.
- We want to send the correct message to the users of QWidget classes: they are 1st class citizens in the desktop environment, but not necessarily available in the embedded or mobile environments
How Qt is structured
Qt consists of the Qt Essentials, Qt Tools and Qt Add-ons. The following table summarizes these categories and their naming conventions:
|Description||Module/tool naming convention|
|Qt Essentials||Qt Essentials consist of the Qt modules that are cross-platform and are available on all platforms. They should cover a meaningful set of use cases of real applications. A platform must support all modules in order to be Qt compliant.||Qt Foo|
|Qt Tools||Tools that are officially a part of Qt. The official tools should run on Qt’s supported desktop platforms.||Qt Foo|
|Qt Add-ons||Modules and tools that bring additional value in specific environments. These modules and tools may be cross-platform or platform-specific. Some of them are included in the Qt releases on certain platforms. Each add-on module specifies its compatibility promise separately.||Qt Add-on Foo, for example “Qt Add-on UI Components for Windows”|
|Other Qt-related modules and tools||Modules and tools that are not developed in the Qt project||If the creators of the module or tool want to refer to Qt, we’d prefer “Foo for Qt”|
The naming QML import statement, C++ naming and library naming for different module types is shown in the table below:
|Module type||import statement||C++ naming||Library name|
|Qt Essentials|| || No namespace, the usual conventions for naming classes and functions (QMyClass etc.) ||libqtfoo.so.5.0, QtFoo5.dll etc.|
|Qt Add-ons|| || |
Naming classes like QMyClass is OK.
|libqtaddonfoo.so.1.0, QtAddOnFoo1.dll etc.|
|Other Qt-related modules|| We recommend using a reverse domain name to avoid clashes: |
- Current documentation, web site etc. use the term “module” to refer to libraries such as QtGui and QtXmlPatterns. We’ll keep this terminology, so we don’t have to rename the existing materials
- Modules are not 1:1 the same as repositories. The users of Qt should not usually need to know that certain modules are developed together in the same repository.
- Modules usually have a C++ API and a QML API
- The QML import statement version number, the module version number in documentation, and the library’s so version number should be the same — unlike currently for example with QtWebKit
- Not all modules in a Qt release will have the same version number
- Experimental modules cannot be a part of Qt Essentials. They follow the naming conventions for add-on modules
- Should we start from version 5.0 for all modules in Qt 5?
Moving modules between categories
Some of the Qt Add-ons for Qt 5.0 were a part of Qt 4. These modules become add-ons mainly because they are not available on all environments (for example the QWidget classes), or because the primary solution for the problem in Qt5 is different from Qt4 (e.g. Qt Script). We should not move any modules from Qt Essentials of Qt 5.0 into Add-ons later during the Qt 5 series. Because of the Qt5 source compatibility target, we will not put the former Qt4 modules in the QtAddOn C++ namespace.
It should be very easy to start a new Qt Add-on in the Qt project. When a new project is started, a module name is reserved (mechanism TBD). This module name will be used in the library name, import statement and in the C++ namespace (see above).
When a new Qt Add-on module is ready, stable and considered useful on some of Qt’s platforms, it can be included in the Qt release. This is a major decision that indicates endorsement by the Qt project. A high level quality, API reviews etc. are expected. No changes to the naming of the module, import statement, or C++ naming are required.
If a Qt Add-on module is considered essential and important for all users of Qt, then the add-on module can be moved to Qt Essentials. This requires a full compatibility and cross-platform promise. The module can be renamed at this point. The C++ namespace is removed, and a complete API review should be done to make the API consistent with the rest of Qt Essentials.
The following areas are not in scope of the Qt Essentials (but may be in scope of Qt Add-ons)
- Operating system functionalities such as window manager, process manager, application lifecycle management
Qt5 minor releases
Qt is released commonly for everyone. Global releases maintain the integrity and identity of Qt as a single toolkit instead of a fragmented collection of related toolkits.
Synchronized releases allow API review rounds and enable pervasive changes such as code refactoring to be done, because the project has a maturization period.
Global releases should be schedule based (Qt 5.0 is an exception).
Even though Qt is developed in a modular way and modules are generally independent, Qt is released as a collection of modules, where a certain combination of module versions is released together. Most Qt users should not need to care about the detailed version numbers of the modules but they should be able to consider Qt as a single non-fragmented toolkit.
Independent module releases
A new version of a module is developed against the latest released versions of other modules, and can be released as an independent module release. An independent module release must ensure that there is no regression. Also the new features need to be tested and new APIs need to be reviewed.
The developers of Qt modules and advanced users who are willing to take additional risks may also create “pick and mix” builds with other module version combinations. However, because the bigger Qt releases get a lot more review and validation from users and the developers of other modules, it is possible to discover problems or conflicts with other new modules, when an intermediate module release is finally included in the Qt release. Therefore, the new features in the intermediate module releases should be considered experimental.
Patch level releases
Patch level releases are meant for critical bug fixes and security updates only. Some modules (for example Qt WebKit) may need to issue security related patch level releases on a very short notice. Modules make patch level updates independently. Qt patch level releases consist of module patch level releases.
Configuration Tiers and Platform support
A configuration is a detailed specification of an operating system version, a tool chain version, a graphics system, and possibly other dependencies. The supported configurations of Qt are defined by what is used in the build bots. For user documentation, it is possible to “extrapolate” platform support from the tested configurations using common sense.
In Qt 5, the configuration tiers should be a matter of documenting the facts: if a configuration meets the criteria, it becomes Tier 1. A configuration can move between tiers during the lifetime of a release.
- All Qt releases must support all reference configurations
- Reference configurations must meet the Tier 1 criteria and never drop to Tier 2.
Tier 1 configuration criteria:
- The configuration participates in the CI system and any other automated testing
- Availability of beta, alpha packages for the platform, and timely participation in manual testing for the packages
- Bug metrics criteria like # of P0 and P1 bugs on the platform
- Community committed to maintain the configuration for patch level releases, and commitment is credible (capacity exists)
- Other possible criteria, for example any required platform specific documentation exists and is of high quality
Tier 2 configuration criteria:
- The configuration participates in the CI system and any other automated testing
- Availability of release packages for the platform
Tier 3 configurations are not officially a part of Qt. Platforms that do not meet the Tier 2 criteria fall into this category, for example because the platform is not in the CI system or “upstream”.
For new platforms, the contributors should start with a branch that tracks the master branches of the Qt, and provide a CI system for the branch. It is perfectly fine to make releases out of such platform specific branches. Once the platform has been proven to track the master successfully, the platform-specific branches can be integrated to the Qt module master branches and the platform can become an official part of Qt.
The cross-platform promise of Qt5 differs from Qt4 slightly, because some important functionalities are provided by add-on modules for which the platform support is defined separately.
We should aim at releasing new versions of each module for all the reference platforms and Tier1 platforms of the module. That results in the same mix of module versions in the Qt release. This has a couple of benefits:
- Synergies in testing and validating the new designs and fixing bugs. A significant portion of Qt’s bugs are cross-platform issues, so having all the platforms work on the same module version mix creates synergies and improves the quality of the release.
- We avoid releasing designs that haven’t been validated on some of the important platforms
- We maintain the integrity of Qt as a single toolkit, which makes it easier for developers to understand what Qt is and to reuse code across platforms. It also makes it easier for the SDK to include documentation, demos, and examples.
Making a new release of a module and choosing to not support a platform that is normally Tier1 should not be done. Similarly, defining a different module version mix for different platforms in a Qt release should not be done.
Compatibility promise and Qt release numbering
We will continue with the current major.minor.patch numbering scheme for Qt releases. The modules in Qt Essentials have the same forward and backward compatibility promises as Qt4: New Qt 5 minor releases will not break binary compatibility, and patch level releases are forward and backward compatible. Qt Add-on modules specify their compatibility promise separately.
See the Qt 5.0 page on the roadmap for a list of modules in Qt Essentials and Qt Add-ons for Qt 5.0: