diff options
author | Edward Welbourne <edward.welbourne@qt.io> | 2018-04-17 11:35:02 +0200 |
---|---|---|
committer | Lars Knoll <lars.knoll@qt.io> | 2018-05-23 12:59:55 +0000 |
commit | bd52f6ac01c3c4c4548061a50747f04c5e690a7c (patch) | |
tree | 5c1c86cc7e4cf124182748b944f554ee73dcd084 | |
parent | f92ce52537dace6c27aea83ef0aa1b45bba7afa5 (diff) |
Prune the QUIP life-cycle and add a QUIP template
The template.rst will make it easier for future QUIP authors to get
started. In the course of review of it, we decided that QUIP-1
offered too many options for Status: it was based on the PEP
life-cycle where we have settled on a simpler life-cycle for QUIPs.
So pruned the list of Status options and made references to the PEP
system explicit by providing links.
Change-Id: I838163e4e830e263d38c6ad63a685735593d6112
Reviewed-by: Kai Koehne <kai.koehne@qt.io>
Reviewed-by: Frederik Gladhorn <frederik.gladhorn@qt.io>
Reviewed-by: Oswald Buddenhagen <oswald.buddenhagen@qt.io>
Reviewed-by: Lars Knoll <lars.knoll@qt.io>
-rw-r--r-- | quip-0001.rst | 13 | ||||
-rw-r--r-- | template.rst | 32 |
2 files changed, 41 insertions, 4 deletions
diff --git a/quip-0001.rst b/quip-0001.rst index 23f3e3b..650d618 100644 --- a/quip-0001.rst +++ b/quip-0001.rst @@ -23,7 +23,7 @@ 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! +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 @@ -68,7 +68,7 @@ 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 +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. @@ -85,8 +85,7 @@ 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: <Draft | Active | Accepted | Deferred | Rejected | - Withdrawn | Final | Superseded> + Status: <Active | Superseded | Withdrawn> Type: <Implementation | Informational | Process> * Qt-Version: <version number> * Content-Type: text/x-rst @@ -111,6 +110,8 @@ 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. @@ -152,6 +153,8 @@ 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/ @@ -162,3 +165,5 @@ References and Footnotes .. _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 diff --git a/template.rst b/template.rst new file mode 100644 index 0000000..3ee821a --- /dev/null +++ b/template.rst @@ -0,0 +1,32 @@ +QUIP: +Title: +Author: Comma-Separated List, + With Continuation Lines +Status: { Active | Superseded | Withdrawn } +Type: { Implementation | Informational | Process } +[Qt-Version:] +[Content-Type: text/x-rst] +[Requires: QUIP-1] +Created: YYYY-MM-dd +Post-History: http://lists.qt-project.org/pipermail/development/YYYY-Month/nnnnnn.html +[Replaces:] +[Superseded-By:] + +Title +===== + +Introductory paragraph, motivation. +Use reStructuredText_ mark-up. + +Various sections +---------------- + +Develop the theme and state the proposal. + +References +---------- + +.. [0] QUIP-1 defines the form this template anticipates: + https://code.qt.io/cgit/meta/quips.git/tree/quip-0001.rst + +.. _reStructuredText: http://docutils.sourceforge.net/rst.html |