Qt-contributors-summit-2011-Qt5ProductDefinition
Qt 5 product definition
This document summarizes the outcome of Qt 5 product definition discussions at QtCS, and the follow up discussions on the qt5-feedback mailing list.
Background
This document is the Qt 5 product definition. It discusses 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.
| Category of module or tool | Description |
| Qt Essentials | Qt Essentials consist of the Qt modules that are cross-platform and are available on all reference platforms. A platform must support all Qt Essential modules in order to be Qt compliant. Qt Essentials define the heart or the foundation of Qt on all platforms. They will be source and binary compatible during Qt 5. These modules should cover a meaningful set of use cases of real applications. These modules are general and useful for a big portion of applications; a niche module needed in a specialized domain should not become essential even if it was completely cross-platform. |
| Qt Tools | Tools that are officially a part of Qt. The official tools should run on Qt’s supported desktop platforms. |
| 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. |
| Other Qt-related modules and tools | Modules and tools that are not developed in the Qt project |
The naming convention for all modules and tools that originate from the Qt project is to start with “Qt”, followed by a descriptive name of the module. For example Qt Designer, Qt Core, Qt Quick 3D and Qt Contacts.
Please pick just one name for the module, and use it consistently in documentation, QML import statement, library name, and the header file name. This makes Qt appear more consistent and guessable.
A recommended way for other Qt-related modules and tools to refer to Qt is to follow the pattern “Foo for Qt”.
Modules usually have a C++ API and a QML API. In the official documentation, we shouldn’t refer to “QML bindings” or “QML plugins” or “QML modules” when we actually mean the QML API provided by a Qt module.
Modules and Repositories
This section has been moved to the Qt Project wiki at http://wiki.qt.io/Creating_a_new_module_or_tool_for_Qt#The_structure_of_a_new_module_repository.
QML, C++ and qmake guidelines for Qt Essentials and Qt Add-On modules
This section has been moved to the Qt Project wiki at http://wiki.qt.io/Creating_a_new_module_or_tool_for_Qt#Using_the_module_name_in_application_code
It’s a good practice to pick a name that is likely to be unique among Qt related modules. One way to avoid clashes in the QML import statement is to use a reverse domain name:
Alternatively, it is possible to use a prefix in the module name, making the probability of a clash lower:
Module version numbers
The owners of each module decide how they number their releases. Not everything needs to be numbered from the 5.x range but it is fine to have Qt Quick 2.0 in Qt 5, for instance.
Versions in the 0.x range are used for experimental releases of add-on modules. Experimental modules are not included in Qt Essentials.
A Qt release will have different versions of different modules, so the developer will have to look up the version anyways. Documentation or auto-complete features in Creator will help here.
There should be no new features in the patch level releases of Qt 5. Not all modules need to be updated in every minor release.
Recommendation: each module should have just one name and one version number. Currently this is not the case, but we have stuff like lilbqtwebkit.so.4.8, which is the same as Qt WebKit 2.1 in the documentation and you import it with “import QtWebKit 1.1”. There is a similar problem with Qt Declarative/Qt Quick.
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 Qt 5 is different from Qt 4 (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 Qt 5 source compatibility target, we will not put the former Qt 4 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. A complete API review should be done to make the API consistent with the rest of Qt Essentials.
The C++ namespace is removed when an add-on module becomes an essential module.
Scope
Qt is a toolkit for developers and designers. It consists of libraries, developer tools, design tools, documentation, demos, examples. Qt’s main technologies are QML, C++ and JavaScript.
The following areas are not in scope of the Qt Essentials (but may be in scope of Qt Add-Ons)
- Applications
- Operating system functionalities such as window manager, process manager, application lifecycle management
- Other programming languages besides QML, C++ and !JavaScript
Releases
Qt 5 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.
Reference configurations:
- The Qt Project defines a small number of reference configurations, which are the primary configurations used in developing Qt. The number of reference configurations should not be a lot more than 5.
- 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.
Cross-platform promise
The cross-platform promise of Qt 5 differs from Qt 4 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 Qt 4: 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.
Qt 5.0
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:
http://developer.qt.nokia.com/wiki/Qt_5.0