by Edward Welbourne
The Qt framework consists of libraries, plugins, tools, examples, documentation, build system and further infrastructure. These are grouped into Qt Modules1, like Qt Core, Qt Gui, or Qt Qml, and tools like Qt Linguist. These, in turn, are grouped into version-control repositories that are checked out as sub-modules of the top-level superproject. Some modules are considered essential components of Qt, some are included as add-ons and others may be considered extensions.
New modules are added to Qt from time to time, usually as a repository containing a single Qt module. These typically start out as playground projects, migrate to technology preview components of the primary Qt checkout and eventually mature into maintained modules. Old modules may also be retired from Qt.
Some modules, particularly extensions, may bypass some steps in this life-cycle. In particular, some modules are introduced as technology previews, without spending time as public playground projects first.
This QUIP describes the prerequisites for a module to make each of the transitions in that life-cycle. At each step, those proposing the transition should post to the Qt project’s developer mailing list making the case that the module satisfies the prerequisites and requesting that the module make the transition.
For a module to be accepted into the Qt project’s playground we require
Once accepted as a playground module, the module is added as a new version-control repository in The Qt Playground.
Here are the criteria for a module to be added to the main Qt project as a Technology Preview module (first proposed in2):
The module solves a problem our users have
The module builds inside the Qt build system on all platforms
- Compilation may be disabled on some platforms but is not allowed to break any platform we support
The module is CI-controlled
There is a decent set of automated tests covering the main functionality and most of the API of the module
APIs have been reviewed, and we are reasonably satisfied with them (we’ve done larger changes to APIs after Technology Preview before)
Architecture has been reviewed, its benefits and any limitations are understood
It follows the Qt coding style and conventions
Implementation has been checked for sanity
A module accepted into Technology Preview shall be added to a released
superproject of the Qt project, with status set to preview in its
section of the superproject’s .gitmodules file. Its version-control
repository is moved to the relevant superproject’s directory in relevant
mirrors. A Technology Preview module makes no promise of source
compatibility or binary compatibility between versions.
The module’s documentation is made part of the general Qt documentation,
with an indication that it is a Technology Preview. This can be achieved
by setting the \modulestate Technology Preview in the QDoc sources,
and adding the module to the “Technology Preview” section in the “All
Modules” Qt documentation3.
After a module has been in Technology Preview, it can be promoted to a Maintained state in a following minor or major Qt release. The decision for this is done on the Qt development mailing list.
Criteria for promoting a module to be Maintained include:
Once a module is accepted as a Maintained module, its entry in its
superproject’s .gitmodules file is updated to a status that reflects
its role. The documentation of the module, as well as the Qt overview
documentation, 4, should also be updated to reflect this.
Maintained modules are part of regular Qt releases and are required to live up to the standard source- and binary-compatibility promises that the Qt project makes to its users.
A module may be retired from Qt by setting its status to either
deprecated or ignored. The criteria for deprecating, ignoring or
retiring a module are not set in stone: discussion on the developer
mailing list is the final authority on deciding such transitions.
Criteria for retiring a module include:
A module may be deprecated to indicate that client code should stop
using it. A module may be created as a temporary repository in which to
retain some deprecated APIs in a later major version than the one in
which they were deprecated, rather than fully removing them. For
example, Qt 6 contains a qt5compat module containing code from Qt 5
that was retired at Qt 6.
A deprecated module’s entry in the superproject .gitmodules file has
its status field set to deprecated. A deprecated module is an
official part of Qt releases. The support level for deprecated modules
may differ from other maintained modules. A deprecated module continues
to receive updates to stay compatible with other Qt modules as their
APIs evolve.
Changes to deprecated modules (including such updates) remain under CI
control. However, deprecated modules are not necessarily included in
binary installers or convenience packages (like qt-everywhere
archives).
The Qt project makes no guarantees to fix issues reported in deprecated modules, but may accept patches to fix bugs. The public API of a deprecated module does not change.
The documentation of a deprecated module should make its status
explicit. This can be achieved by adding \deprecated in the \module
part of its documentation sources, while also removing any
\modulestate directive. The documentation should furthermore explain
the reason for deprecation, possible alternatives, and which support
guarantees are still given, with a particular focus on the handling of
security-critical issues.
Particularly when the reason for deprecation is an issue with the design or architecture of the module, the module documentation should also make clear any known limitations, deficiencies or hazards that may result from use of the module.
A deprecated module may be removed from the superproject at a later major release of Qt, or it may be ignored.
A module may be retained in the top-level Qt source tree with status
set to ignore in the .gitmodules file. An ignored module is not
included in official releases. Patches may be accepted to keep a retired
module compiling with newer versions of Qt or other relevant software.
A module should be moved to the ignored state if the module no longer meets the requirements for a maintained or even deprecated module. An ignored module is not included in official releases; nor is it part of the regular QA activities around a Qt release; nor is its documentation published as part of the Qt documentation. Patches to keep an ignored module compiling with newer versions of Qt or other relevant software might still be accepted.
Ignored modules are sometimes brought back to a maintained state. In other cases, they are completely removed from the top-level Qt project after some time.
If (or when) there is a plan to remove a module from Qt, this should be made explicit in the module’s documentation, for example prominently saying “this module shall be removed from Qt at version 7.0.” Such removal is usually at the transition to a new major version, although removal at a minor version is possible given good reasons.
A retired module’s source-code repository remains part of the published
software of the Qt project, on code.qt.io and other mirrors controlled
by the Qt project. It may, of course, also be mirrored, or even
maintained, by others under the terms of its (possibly revised) license.
[1] Qt modules are listed in the documentation
https://doc.qt.io/qt-6/qtmodules.html generated from
qtdoc/doc/src/qtmodules.qdoc ↩
[2] Post by Lars Knoll on qtremoteobjects as Tech Preview
https://lists.qt-project.org/pipermail/development/2017-January/028313.html ↩
[3] Post by Lars Knoll on qtremoteobjects as Tech Preview
https://lists.qt-project.org/pipermail/development/2017-January/028313.html ↩
[4] Post by Lars Knoll on qtremoteobjects as Tech Preview
https://lists.qt-project.org/pipermail/development/2017-January/028313.html ↩
