From bd52f6ac01c3c4c4548061a50747f04c5e690a7c Mon Sep 17 00:00:00 2001 From: Edward Welbourne Date: Tue, 17 Apr 2018 11:35:02 +0200 Subject: 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 Reviewed-by: Frederik Gladhorn Reviewed-by: Oswald Buddenhagen Reviewed-by: Lars Knoll --- quip-0001.rst | 13 +++++++++---- template.rst | 32 ++++++++++++++++++++++++++++++++ 2 files changed, 41 insertions(+), 4 deletions(-) create mode 100644 template.rst 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: Title: Author: - Status: + Status: Type: * Qt-Version: * 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 -- cgit v1.2.3