1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
|
QUIP: 1
Title: QUIP Purpose and Guidelines
Author: Louai Al-Khanji,
Andrew Knight,
André Pönitz,
Kai Köhne,
Lars Knoll
Status: Active
Type: Process
Created: 2016-09-02
Post-History: https://lists.qt-project.org/pipermail/development/2016-September/027218.html
Requires: QUIP 2
What is a QUIP?
===============
QUIP stands for Qt's Utilitarian Improvement Process and for Qt User-Submitted
Improvement Proposal. QUIP is the Qt Project's community design process, while
a QUIP is a design document providing information to the Qt community, or
describing a new feature for Qt or its processes or environment. A QUIP should
provide a concise technical specification of the feature and a rationale for
the feature.
If this preamble seems familiar to you, then you are probably familiar with
the `PEP documents`_ maintained by the Python community. Thanks, Python!
We intend QUIPs to be the primary mechanism for proposing major new features,
for collecting community input on an issue, and for documenting design
decisions that have gone into Qt. The QUIP author is responsible for building
consensus within the community and documenting dissenting opinions.
Because QUIPs are maintained as text files in a versioned repository, their
revision history is the historical record of the feature proposal [1]_.
QUIP Types
==========
There are three kinds of QUIPs:
1. An **Implementation** QUIP describes a new feature, module or
implementation for Qt. QUIPs describing API changes as well as QUIPs describing
the introduction or removal of modules are also Implementation QUIPs.
2. An **Informational** QUIP describes a Qt design issue, or provides general
guidelines to the Qt community, but does not propose a new feature.
Informational QUIPs do not necessarily represent a Qt community consensus, so
users and contributors are free to ignore Informational QUIPs or follow their
advice.
3. A **Process** QUIP describes a process surrounding Qt, or proposes a change
to (or an event in) a process. Process QUIPs are like Implementation
QUIPs but apply to areas other than Qt itself. They may propose an
implementation, but not to Qt's codebase; they often require community
consensus; unlike Informational QUIPs, they are more than recommendations, and
users are typically not free to ignore them. Examples include procedures,
guidelines, changes to the decision-making process, and changes to the tools
or environment used in Qt development. Any meta-QUIP is also considered a
Process QUIP.
**Implementation** and **Process** QUIPs generally both require community
consensus. Consensus is established through The Qt Governance Model, as
described in QUIP 2.
QUIP Format
===========
QUIPs are UTF-8 encoded text files using the reStructuredText_ format.
ReStructuredText allows for rich markup that is still quite easy to read, but
also results in good-looking and functional HTML. A script automatically
converts QUIPs to HTML for viewing on the web [2]_. Lines should not exceed 80
characters in length.
QUIP Header Preamble
====================
Each QUIP must begin with an `RFC-822`_-style header preamble.
The headers must appear in the following order. Headers marked with "*" are
optional and are described below. All other headers are required. ::
QUIP: <quip number>
Title: <quip title>
Author: <list of authors' real names and, optionally, email addresses>
Status: <Active | Superseded | Withdrawn>
Type: <Implementation | Informational | Process>
* Qt-Version: <version number>
* Content-Type: text/x-rst
* Requires: <list of quips>
Created: <ISO date string>
Post-History: <links to mailing-list posts>
* Replaces: <list of quips>
* Superseded-By: <list of quips>
The Author header lists the names, and optionally the email addresses of all
the authors/owners of the QUIP. The format of the Author header value must be::
Random J. User <address@example.com>
if the email address is included, and just::
Random J. User
if the address is not given.
If there are multiple authors, each should be on a separate line following RFC
2822 continuation line conventions. Note that personal email addresses in QUIPs
will be obscured as a defense against spam harvesters.
The Status header supports a sub-graph of the python community's `PEP lifecycle`_.
The Type header specifies the type of QUIP: Implementation, Informational,
or Process.
The format of a QUIP is specified with a Content-Type header. The only
acceptable, and default, value is "text/x-rst" for reStructuredText.
The Created header records the date, that the QUIP was assigned a number, in
yyyy-mm-dd format. The Post-History is used to record references to the
discussion this QUIP summarizes.
Implementation QUIPs will typically have a Qt-Version header which
indicates the version of Qt that the feature will be released with.
Informational and Process QUIPs do not need a Qt-Version header.
QUIPs may have a Requires header, indicating the QUIPs that this
QUIP depends on.
QUIPs may also have a Superseded-By header indicating that this QUIP has been
rendered obsolete by one or several later QUIPs. The newer QUIPs must have a
Replaces header containing the QUIPs that they render obsolete.
File Naming
===========
QUIPs must be named ``quip-XXXX[-shortname].rst`` where the -shortname is optional
to help identifying the right file. shortname must not be a number since that would
conflict with auxiliary files (see below).
Auxiliary Files
===============
QUIPs may include auxiliary files such as diagrams. Such files must be
named ``quip-XXXX-Y[-shortname].ext``, where "XXXX" is the QUIP number, "Y" is a
serial number (starting at 1), and "ext" is replaced by the actual
file extension (e.g. "png"). The descriptive shortname is optional.
References and Footnotes
========================
.. _`PEP documents`: https://www.python.org/dev/peps/
.. [1] This historical record is available by the normal git commands
for retrieving older revisions, and can also be browsed via HTTP here:
https://code.qt.io/cgit/meta/quips.git/
.. [2] The source code for the exporting script lives in the same repository
as the QUIPs
.. _reStructuredText: http://docutils.sourceforge.net/rst.html
.. _RFC-822: https://www.ietf.org/rfc/rfc0822.txt
.. _`PEP lifecycle`: https://www.python.org/dev/peps/pep-0001/#pep-review-resolution
|
