Introduce QUIP 13, "Qt Examples"

The aim of this QUIP is twofold:

Consolidate best practices currently encoded in the
examples, and explained in the wiki pages
https://wiki.qt.io/Writing_Qt_Examples and
https://wiki.qt.io/Documentation_Style_for_Examples.

Be able to reach a consensus about new requirements.

Change-Id: I9cec1882dc43dde56c8fb96bbbd745061accfeb1
Reviewed-by: Shawn Rutledge <shawn.rutledge@qt.io>
Reviewed-by: Volker Hilsheimer <volker.hilsheimer@qt.io>

1 files changed, 134 insertions, 0 deletions

diff --git a/quip-0013-Examples.rst b/quip-0013-Examples.rst
new file mode 100644
index 0000000..8fb6e81
--- /dev/null
+++ b/quip-0013-Examples.rst
@@ -0,0 +1,134 @@
+QUIP: 13
+Title: Qt Examples
+Author: Kai Köhne, Edward Welbourne
+Status: Active
+Type: Informational
+Post-History: https://lists.qt-project.org/pipermail/development/2018-November/034338.html
+Created: 2022-10-11
+
+Qt Examples
+===========
+
+Examples in the Qt Framework show a particular aspect of Qt.
+They consist of source code and documentation.
+
+Examples should be concise. But be aware that users often use them as
+a starting point, so they should avoid the use of anti-patterns.
+
+Directory Layout
+~~~~~~~~~~~~~~~~
+
+Each git repository should have an ``examples/`` directory that contains
+subdirectories matching the Qt modules or tools in the repository.
+
+For instance, qtdeclarative.git has::
+
+   examples/qml
+   examples/quick
+   ...
+
+Each subdirectory may, in turn, group examples into a directory hierarchy.
+
+Note that installers merge the example directories from different git
+repositories. Therefore, the relative path of an example within the respective
+examples directory and the example name should be unique.
+
+Alternatively, examples can be hosted in the ``examples/`` directory of
+qtdoc.git. Such examples can use all Qt modules, regardless of the build order.
+
+Structure
+~~~~~~~~~
+
+The source directory of an example should be self-contained whenever possible.
+It should be possible to build either within the source tree, or when copied
+out to another directory.
+
+Each example should be documented. This is usually done in a ``doc/``
+subdirectory of the example.
+
+Launching
+~~~~~~~~~
+
+An example should launch from Qt Creator without any further actions necessary.
+In the few cases where this is not possible, the example should prominently
+state the steps required to try out the example.
+
+File Naming
+~~~~~~~~~~~
+
+If the example has a ``C++`` entry point, it should be in the file ``main.cpp``.
+Try to keep this as simple as possible: Most users have understood that
+``main()`` is usually dull and seldom take time to read it.
+
+For Qt Quick examples, the ``.qml`` file that contains the ``QML`` entry point
+and a ``.qmlproject`` file should be named the same as the directory.
+
+Coding Style
+~~~~~~~~~~~~
+
+Examples should follow the general Qt coding style, with some exceptions:
+
+``C++`` includes should use the camel-case class name notation, for example::
+
+   #include <QCoreApplication>
+
+*not*::
+
+  #include <QtCore/QCoreApplication>
+  #include <qcoreapplication.h>
+
+Rationale: Not including the module name allows easier portability between Qt
+major versions, where classes and API are sometimes moved to new modules. Also,
+failing to add a Qt module to the project file will result in a compile
+error, which is usually easier to understand than a linker error.
+
+In ``C++``, ``signals`` and ``slots`` keywords are preferred over their
+``Q_SIGNAL``, ``Q_SLOT`` variants.
+
+Example code should wrap at 80 characters because it's often quoted
+in the documentation.
+
+Comments
+~~~~~~~~
+
+Keep comments in source code minimal. Documentation and explanations
+belong in the example's exposition.
+
+You can use snippet markers for documentation purposes, though.
+
+Conditional Compilation
+~~~~~~~~~~~~~~~~~~~~~~~
+
+Use the preprocessor exclusively to protect against multiple inclusion of
+header files. In particular, do not use the Qt feature system to disable parts
+of an example because the individual features are currently not part of the
+public API. Instead, the build system should skip examples that do not have
+required dependencies.
+
+Application Settings
+~~~~~~~~~~~~~~~~~~~~
+
+Examples should store their custom settings in a common ``QtProject``
+scope so that the settings do not litter the user settings too much.
+This is usually done by calling::
+
+  QCoreApplication::setOrganizationName("QtProject");
+
+in ``main.cpp``.
+
+Licenses and Third-Party Assets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Examples should be made available under the Commercial/BSD 3 clause license:
+
+  // SPDX-License-Identifier: LicenseRef-Qt-Commercial OR BSD-3-Clause
+
+Code or assets (including images) from third-party sources must be explicitly
+documented. See QUIP-4 for the details.
+
+References
+==========
+
+- `Writing Qt Examples`: https://wiki.qt.io/Writing_Qt_Examples
+
+- `Documentation Style for Examples`: https://wiki.qt.io/Documentation_Style_for_Examples