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