diff options
| -rw-r--r-- | .gitignore | 5 | ||||
| -rw-r--r-- | Makefile | 76 | ||||
| -rw-r--r-- | ReadMe.rst | 116 | ||||
| -rw-r--r-- | docutils/quip.css | 2 | ||||
| m--------- | planetqt | 0 | ||||
| -rw-r--r-- | quip-0002.rst | 58 | ||||
| -rw-r--r-- | quip-0005.rst | 10 | ||||
| -rw-r--r-- | quip-0006.rst | 79 | ||||
| -rw-r--r-- | quip-0007.rst | 63 | ||||
| -rw-r--r-- | quip-0010-API-review.rst | 6 | ||||
| -rw-r--r-- | quip-0013-Examples.rst | 147 | ||||
| -rw-r--r-- | quip-0015-Security-Policy.rst | 162 | ||||
| -rw-r--r-- | quip-0016-branch-policy.rst | 252 | ||||
| -rw-r--r-- | quip-0017-Change-log-creation.rst | 80 | ||||
| -rw-r--r-- | quip-0018-license-specification.rst | 194 | ||||
| -rw-r--r-- | quip-0019-nodiscard-policy.rst | 161 | ||||
| -rw-r--r-- | quip-0021-images-in-docs.rst | 165 | ||||
| -rw-r--r-- | quips.pro | 38 | ||||
| -rwxr-xr-x | scripts/gen-quip-0000.py | 31 | ||||
| -rwxr-xr-x | scripts/quip2html.py | 26 | ||||
| -rw-r--r-- | scripts/setup.mk | 21 | ||||
| -rw-r--r-- | scripts/template.diff | 48 | ||||
| -rw-r--r-- | template.rst | 6 | ||||
| -rw-r--r-- | templates/simple_template.html | 27 |
24 files changed, 1576 insertions, 197 deletions
@@ -1,8 +1,5 @@ # Transient file created by patch (see ReadMe.rst): /scripts/template.html /scripts/template.rej -# Generated (if building in source): -/html/ +# Generated: /template.html -/Makefile -/.qmake.stash diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..62f04da --- /dev/null +++ b/Makefile @@ -0,0 +1,76 @@ +# Maintenance of the QUIP module and its generated HTML docs. +# Expects GNU make, run on Unix (so #!/usr/bin/env ... scripts work) +# See ReadMe.rst for further details. +default: html +.PHONY: default html + +HTMLDIR ?= ../html +# Don't print setup commands as they are run, unless VERBOSE is set: +ifeq ($(VERBOSE),) +Q ?= @ +endif + +RST := $(wildcard quip-[0-9][0-9][0-9][0-9]*.rst) +RSTHTML := $(RST:%.rst=$(HTMLDIR)/%.html) +HTML := $(HTMLDIR)/quip-0000.html $(RSTHTML) +ifeq ($(QUIP_TEMPLATE),) +WEBLINK := favicon.ico \ + cookiebar-x.png cookie_small.png list_arrow.png theqtcompany.png \ + extras.js main.js modernizr.custom.84855.js \ + online.css style.css \ + images +LINK := $(HTMLDIR)/.web $(HTMLDIR)/index.html $(WEBLINK:%=$(HTMLDIR)/%) +endif + +html: $(HTML) $(LINK) +$(HTML) $(LINK): $(HTMLDIR)/.ready + +%/.ready: + $Q mkdir -p $(@D) && touch $@ + +$(HTMLDIR)/index.html: $(HTMLDIR)/quip-0000.html + $Q [ -h $@ ] || (cd $(@D) && ln -s $(<F) $(@F)) +ifeq ($(QUIP_TEMPLATE),) +$(WEBLINK:%=$(HTMLDIR)/%) $(WEBLINK:%=$(HTMLDIR)/.web/%): $(HTMLDIR)/.web +$(WEBLINK:%=$(HTMLDIR)/%): $(HTMLDIR)/%: $(HTMLDIR)/.web/% + $Q [ -h $@ ] || (cd $(@D) && ln -s .web/$(@F) $(@F)) +$(HTMLDIR)/.web: planetqt/website + $Q [ -h $@ ] || (cd $(@D) && ln -s $(abspath $<) $(@F)) +endif + +$(HTMLDIR)/quip-0000.html: scripts/gen-quip-0000.py scripts/quip2html.py $(RST) template.html + scripts/gen-quip-0000.py $(RST) | scripts/quip2html.py - >$@ +$(RSTHTML): $(HTMLDIR)/%.html: %.rst scripts/quip2html.py template.html + scripts/quip2html.py $< >$@ + +ifeq ($(QUIP_TEMPLATE),) +.INTERMEDIATE: scripts/template.html +template.html: scripts/template.diff planetqt/template.qt + $Q patch -l -p0 -i $< -o scripts/$@ && mv scripts/$@ $@ +# We only stomp template.html if patch succeeds. +else +template.html: $(QUIP_TEMPLATE) + $Q rm -f $@; ln -s $< $@ +endif + +.PHONY: clean +clean: + $Q rm -f scripts/template.html template.html + $Q echo "Remove the generated HTML (perhaps in $(HTMLDIR)) yourself" + +# For use during an update: +.PHONY: patch +patch: template.html planetqt/template.qt + $Q if cp $< scripts/$< && diff -bu planetqt/template.qt scripts/$< >scripts/template.diff; \ + then echo Empty patch; else [ $$? -eq 1 ]; fi +# Does not declare dependency of template.diff on prerequisites, to avoid circular dependency. + +planetqt/template.qt planetqt/website: + $Q echo "Please see ReadMe.rst for submodule checkout instructions"; false +# The false is to stop the build dead if planetqt/ is missing. + +# TODO: we need a non-heroku site (QTWEBSITE-978) +HTMLURL ?= http://quips-qt-io.herokuapp.com/ +.PHONY: check +check: html + checklink -qbr $(HTMLURL) 2>&1 | grep -wv 'Use of uninitialized value .*/checklink line' @@ -1,57 +1,83 @@ -QUIP module maintenance + ======================= This module contains * The reStructuredText sources of all QUIPs (``quip-*.rst``) -* The scripts to process them (``quips.pro`` and ``scripts/``) +* The scripts to process them (in ``scripts/``) * A copy of Planet Qt as a sub-module -See ``html/``, once generated, for further details, or the preamble -for ``html/quip-000.html`` defined in ``scripts/gen-quip-0000.py`` for -a preview of what this is all about. +See the generated HTML for further details, or the preamble for +``html/quip-000.html`` defined in ``scripts/gen-quip-0000.py`` for a +preview of what this is all about. Generating HTML from QUIPs -------------------------- -You'll need this module checked out, along with its sub-module: see +If you want the output to include the Planet Qt style, +you'll need this module checked out, along with its sub-module: see `Planet Qt and the template`_ for how to get Planet Qt checked out and up to date. - -You can generate the HTML using ``qmake`` and ``make``, provided you -have (them and) both ``python`` and its ``docutils`` package -installed. -I recommend a shadow build: in some directory outside this source -tree, run ``qmake`` on ``quips.pro`` in this directory; then, in the -same directory, run ``make`` and it should generate a sub-directory -``html/`` containing the generated HTML and symlinks to the supporting -material from Planet Qt. +Alternatively, you can set the ``QUIP_TEMPLATE`` make variable +to use another HTML template. + +You can generate the HTML using ``make``, provided you have GNU +``make``, ``python3`` and its ``docutils`` package installed. + +By default, the ``Makefile`` generates HTML in an ``html/`` peer +directory of this module's checkout. +You can override that on the ``make`` command-line by setting +``HTMLDIR`` to some directory outside this source tree. +The HTML shall then be generated or updated in that directory. +Alongside the HTML, ``make`` will also place symlinks to the +supporting material from Planet Qt, referenced by the generated HTML. You can then point a web browser at the result and review it. -You can, of course, do the same in the source tree; you'll clutter it -with the generated content. -While ``.gitignore`` should save you from committing that, you can -clean up more robustly in an out-of-source build. - Checking ~~~~~~~~ It may be constructive to use checklink_ on the resulting HTML. On Debian, this is available for local use from the package named ``w3c-linkcheker``; other systems probably have something similar. -It can be run (be patient; it takes several minutes) as:: +It no longer supports checking ``file://`` URLs, or local files, so +you'll need to generate the HTML where you (at least) can see it on +the web. +If that's by running a local web-server on a non-public host, you may +need to comment out its ``Allow_private_IPs`` setting in +``/etc/w3c/checklink.conf`` to make the following work. + +Then pass the URL for the generated HTML directory to ``checklink`` +with command-line options ``-qbr``, for example: - checklink -qbr html/quip-*.html + checklink -qbr http://localhost/~test/quips/ + +Alternatively, set ``HTMLURL`` to that top-level URL on the +command-line to ``make check`` (which will filter out some unhelpful +warnings from ``perl`` about the ``checklink`` script itself), for +example: + + make HTMLURL=http://localhost/~test/quips/ check If that finds any broken links, check to see whether they derive from the template (report to the planetqt maintainers) or from the source of the QUIP (``quip-*.rst``, report to the relevant QUIP's author). -Some template links may use URLs without scheme, -e.g. ``href="//www.qt.io/terms-conditions/"``, which checklink shall -show as broken (since it's accessing links using ``file://``, -implicitly); these are not normally a problem. +Some certificate errors for ``account.qt.io`` may arise; they're not a +flaw in the generated HTML for QUIPs, so just manually check you can +visit the URLs it mentions for this. +As long as you can reach them, the problem is just with the script +having a limited implementation of ``https``, most likely. .. _checklink: http://validator.w3.org/docs/checklink.html +Minimal template +---------------- + +In ``templates/`` you will find a minimal html to generate the QUIPs +without any styling. This template can be used like: + + make QUIP_TEMPLATE="templates/simple_template.html" + +but by default, a template derived from Planet Qt is used. + Planet Qt and the template -------------------------- @@ -69,28 +95,34 @@ This might work fine with the existing scripts and templates, in which case it's fine to ``git add planetqt`` in the super-module and commit. However, if ``planetqt/template.qt`` has changed, it's possible the -scripts shall fail to generate ``template.html`` from it (in the build -directory, if different from the source directory). -The script first attempts this by applying ``scripts/template.diff`` -to produce ``scripts/template.html``; if this had succeeded, the -result would have been moved to the build directory. +scripts shall fail to generate ``template.html`` from it. +The ``Makefile`` first attempts this by applying +``scripts/template.diff`` to produce ``scripts/template.html``. When it fails, a partially-patched ``scripts/template.html`` should result in a ``scripts/template.rej`` file, containing the unapplied hunks from the patch. + You'll need to manually adapt the patch's modifications to produce a sensible ``template.html`` (see below) based on the new ``template.qt`` from Planet Qt. -Once you have a usable ``scripts/template.html``, run:: +Once you have a usable ``template.html``, move it from ``scripts`` to +this top-level directory and run:: - $ diff -bu planetqt/template.qt scripts/template.html >scripts/template.diff + $ make patch You might then want to move your working ``template.html`` to safety, while you check that building works; your test build shall, otherwise, stomp your ``template.html`` in the process of generating the one it uses. -If it all works nicely, commit your updated ``template.html`` along -with the updated ``planetqt/``. +If it all works nicely, commit your updated ``scripts/template.diff`` +along with the updated ``planetqt/``. + +You can also use this process, manually updating ``template.html`` and +updating the patch, to work round problems with the parts of Planet Qt +we use. +For example, problems in the style-sheets can be fixed by patching a +style element into the template, after the style-sheets. How the template works ~~~~~~~~~~~~~~~~~~~~~~ @@ -127,13 +159,13 @@ Under ``planetqt/website`` there are assorted files that shall be referenced from your ``template.html``, expecting them to be in the same directory. There's also a sub-directory ``images/``. -All of these need to be visible in the generated ``html/`` directory; -this is arranged by a setup target in ``quips.pro`` which (to save a -lot of repetition) uses ``scripts/setup.mk`` to drive creation of -symlinks from ``html/`` to ``planetqt/website/``. -You'll need to keep the ``WEBFILES`` and ``WEBDIRS`` lists up to date; -each is a list of names, of files or directories respectively, within -``planetqt/website`` that are needed by the template. +All of these need to be visible in the directory containing the +generated HTML; the ``Makefile`` rules for its default target +(``html``) should take care of this. + +You'll need to keep the ``WEBLINK`` list in the ``Makefile`` up to +date; it lists the names of files and directories, within (and +relative to) ``planetqt/website``, that are needed by the template. If the new planetqt template contains a copyright notice, consult with planetqt's owners about whether they're happy to have the adapted diff --git a/docutils/quip.css b/docutils/quip.css index c071a20..879ae6d 100644 --- a/docutils/quip.css +++ b/docutils/quip.css @@ -62,6 +62,8 @@ a.toc-backref { blockquote.epigraph { margin: 2em 5em ; } +blockquote li { margin-left: 2em; } + body { margin: 0px ; margin-bottom: 1em ; diff --git a/planetqt b/planetqt -Subproject 32079c4c100eb38f8e102bdfab584f721ca1d3a +Subproject 3e350aefca147b9c06361a25947fe5cd931da0c diff --git a/quip-0002.rst b/quip-0002.rst index 9550967..87698c6 100644 --- a/quip-0002.rst +++ b/quip-0002.rst @@ -3,9 +3,11 @@ Title: The Qt Governance Model Author: Thiago Macieira Lars Knoll Louai Al-Khanji + Volker Hilsheimer Status: Active Type: Process Post-History: https://lists.qt-project.org/pipermail/development/2016-September/027218.html + https://lists.qt-project.org/pipermail/development/2022-September/042922.html Created: 2016-09-03 Overview @@ -73,7 +75,7 @@ including: * Designing web sites and graphics * Organizing conferences * Doing community work (being active on mailing lists, forums like - https://forums.qt.io, IRC and at events) + https://forum.qt.io, IRC and at events) * Supporting and coaching new Users * Improving the Qt contribution process @@ -158,7 +160,10 @@ Maintainers are responsible for the overall quality and spirit fit of their component, so they need good visibility of Contributor and Approver activity. They ensure the smooth running of the Project and must always be aware of the current state of their component, normally ensuring it is ready for beta release -at any time. +at any time. Maintainers give the final approval to API and C++ header changes +for their component during the `API review process`_ that precedes releases, +and ensure that any third party code that is included in their components is +updated regularly in line with the `security policy`_. Maintainers are expected to participate in strategic planning, approve changes to the governance model, manage intellectual property rights discussions within @@ -169,6 +174,9 @@ The authoritative list of Maintainers, including the components they own, is `on the Qt project Wiki`_. .. _`on the Qt project Wiki`: https://wiki.qt.io/Maintainers +.. _`API review process`: quip-0010-API-review.html +.. _`security policy`: quip-0015-Security-Policy.html + How to become a Maintainer '''''''''''''''''''''''''' @@ -186,6 +194,11 @@ Once seconded, a new Maintainer is appointed unless a community member objects to the Chief Maintainer within 15 work days. If an objection is raised, the Chief Maintainer decides, usually within 15 work days. +When a Maintainer is newly appointed, the authoritative list of +Maintainers `on the Qt project Wiki`_ is updated to record their area +of responsibility and the new maintainer is added to the security +mailing list (see `QUIP 15`), if not already subscribed. + Becoming Maintainer of anything in a main module of Qt implies becoming Approver throughout Qt, if one is not so yet. The Maintainer of a playground project is an Approver for that project, even if not so more generally. @@ -199,11 +212,20 @@ Once someone has been appointed Maintainer, they remain in that role until they choose to step down by informing the Chief Maintainer, preferably with one month's warning. +Maintainers that have stopped participating in the development of their +component, do not review changes, do not ensure that their component is ready +for beta release, and do not respond to emails from the Chief Maintainer in +which at least one other maintainer has been copied, may be considered as +retired. In such a case, a new Maintainer may be nominated, following the +process described above. + In extreme circumstances Maintainer privileges can be revoked by a vote of no confidence, proposed by an existing Maintainer and arranged by the Chief Maintainer. Privilege revocation requires a two-thirds majority vote of those Maintainers who express an opinion. +.. _`QUIP 15`: quip-0015-Security-Policy.html + Chief Maintainer ---------------- @@ -223,14 +245,27 @@ roadmap perspective. How to become Chief Maintainer '''''''''''''''''''''''''''''' -When the Chief Maintainer decides to step down, the Maintainers will arrange a -vote to choose a successor by simple majority vote of all Maintainers. - Once someone has been appointed Chief Maintainer, they remain in that role until they choose to step down by informing the Maintainers, preferably with one month's warning, or until there is a vote of no confidence by two-thirds of all Maintainers. +To appoint a new Chief Maintainer, Maintainers nominate and then vote for +candidates. Only Approvers can be nominated. The nomination period runs for +14 calendar days from when the departing Chief Maintainer has given +notice, or after a vote of no confidence has revoked the current Chief +Maintainer's privilege. A nomination is only valid once the candidate has +confirmed by email to the mailing list that they accept the nomination. + +The Maintainers will arrange a vote to choose a successor from the nominated +candidates. Only Maintainers can vote. If exactly two candidates are nominated, +a candidate is elected by a simple majority, defined as receiving greater +than 50% of recorded, valid votes upon completion of 14 calendar days of +non-public voting. + +For the scenario of more than two candidates, the maintainers will agree on a +process. + Support ------- @@ -260,12 +295,13 @@ Lazy consensus Decision-making typically involves the following steps: -# Proposal -# Discussion -# Decision, by -## Consensus -## Maintainer, if consensus is not reached through discussion -## Chief Maintainer, if Maintainers disagree and cannot reach consensus +#) Proposal +#) Discussion +#) Decision, by + + #) Consensus + #) Maintainer, if consensus is not reached through discussion + #) Chief Maintainer, if Maintainers disagree and cannot reach consensus Any community member can make a proposal for consideration by the community. In order to initiate a discussion about a new idea, they should send an email to diff --git a/quip-0005.rst b/quip-0005.rst index 0150ebd..19a191c 100644 --- a/quip-0005.rst +++ b/quip-0005.rst @@ -1,10 +1,11 @@ QUIP: 5 Title: Choosing a Branch Author: Jędrzej Nowacki, Friedemann Kleint -Status: Active +Status: Superseded Type: Process Created: 2016-12-05 Post-History: https://lists.qt-project.org/pipermail/development/2017-January/028248.html +Superseded-By: QUIP 16 ======================================== Choosing a Branch @@ -180,6 +181,13 @@ the left) branch. | features | | | | | | mass updates | +----------------------------+-----+--------+--------+-------------+---------+---------------------+ +History +------- + +The dev / stable / release pattern originated in a discussion during +initial development of Qt 5: `Branching for Qt 5 repositories +<https://lists.qt-project.org/pipermail/development/2012-September/006691.html>`_ + Glossary -------- diff --git a/quip-0006.rst b/quip-0006.rst index 19900cf..fda1a23 100644 --- a/quip-0006.rst +++ b/quip-0006.rst @@ -5,6 +5,7 @@ Status: Active Type: Implementation Post-History: https://lists.qt-project.org/pipermail/development/2016-July/026527.html https://lists.qt-project.org/pipermail/development/2017-January/028340.html + https://lists.qt-project.org/pipermail/development/2022-December/043428.html Created: 2017-01-13 ======================================== @@ -14,9 +15,15 @@ Created: 2017-01-13 Motivation ---------- +Qt strives to keep source compatibility as much as possible within a major +Qt release, i.e. between minor releases. + +We acknowledge that there can be exceptional situations where adding new +functionality or fixing issues requires changes that might break existing +code. + This QUIP offers guidelines on which types of source-incompatible -changes are acceptable within a major Qt release, i.e. between minor -releases. +changes may be acceptable between minor releases. It originated from `the author's post <https://lists.qt-project.org/pipermail/development/2016-July/026543.html>`_ @@ -39,15 +46,16 @@ user code using Qt version checks, or similar techniques, such as Category A SiCs are acceptable, while Category B SiCs are not. +Category B SiCs can be made acceptable when hidden behind an *opt-in* macro. +Deprecations and QT_NO_x macros are the primary examples of such opt-in +mechanisms. User Notification ----------------- -Accepted SiCs need be communicated to users by way of changelog -entries of the form: - - [ChangeLog][Potentially Source-Incompatible Changes] - +Accepted SiCs need be communicated to users by way of changelog entries at the +library level, using the tag [Potentially Source-Incompatible Changes], see +`QUIP 17 <quip-0017-Change-log-creation.html>`_ for details. Examples -------- @@ -55,34 +63,45 @@ Examples This list is not exhaustive. Issues not listed here should be discussed on the mailing-list and then added here. -+-------------------------------------------------------------+-------+--------+ -| | Classification | -| Source-incompatible Change +-------+--------+ -| | Cat A | Cat B | -+-------------------------------------------------------------+-------+--------+ -| Adding an overload of a function | X | | -+-+-----------------------------------------------------------+-------+--------+ -| | Exception: when causing ambiguities | | X | -+-+-----------------------------------------------------------+-------+--------+ -| Adding Q_OBJECT to a QObject subclass that lacks it. | X | | -+-------------------------------------------------------------+-------+--------+ -| Deprecating a function/class/typedef (even though it breaks | X | | -| -Werror=deprecated builds) | | | -+-------------------------------------------------------------+-------+--------+ -| Removing an include from a public header file | X | | -+-------------------------------------------------------------+-------+--------+ -| Removing top-level const from return types (see footnote 1) | X | | -+-------------------------------------------------------------+-------+--------+ -| Removing/restricting public API (even if binary-compatible) | | X | -+-+-----------------------------------------------------------+-------+--------+ -| | Exception: when preventing API misuses at compile-time, | X | | -| | e.g. when constraining templates (further). | | | -+-+-----------------------------------------------------------+-------+--------+ ++-------+-------------------------------------------------------------+-------+--------+ +| | | Classification | +| # | Source-incompatible Change +-------+--------+ +| | | Cat A | Cat B | ++-------+-------------------------------------------------------------+-------+--------+ +| A.1 | Adding an overload of a function | X | | ++-------+-+-----------------------------------------------------------+-------+--------+ +| B.1 | | Exception: when causing ambiguities | | X | ++-------+-+-----------------------------------------------------------+-------+--------+ +| A.2 | Adding Q_OBJECT to a QObject subclass that lacks it. | X | | ++-------+-------------------------------------------------------------+-------+--------+ +| A.3 | Deprecating a function/class/typedef (even though it breaks | X | | +| | -Werror=deprecated builds) | | | ++-------+-------------------------------------------------------------+-------+--------+ +| A.4 | Removing an include from a public header file | X | | ++-------+-------------------------------------------------------------+-------+--------+ +| A.5 | Removing top-level const from return types (see footnote 1) | X | | ++-------+-------------------------------------------------------------+-------+--------+ +| B.6 | Removing/restricting public API (even if binary-compatible) | | X | ++-------+-+-----------------------------------------------------------+-------+--------+ +| A.6 | | Exception: when preventing API misuses at compile-time, | X | | +| | | e.g. when constraining templates (further). | | | ++-------+-+-----------------------------------------------------------+-------+--------+ +| B.7 | Moving declarations between headers that don't include each | | X | +| | other (see footnote 2). | | | ++-------+-+-----------------------------------------------------------+-------+--------+ +| A.7 | | Exception: when moving classes | X | | +| | | (we promise SC only for use of <QStyleHeaders>, | | | +| | | not the qstyleheaders.h) | | | ++-------+-+-----------------------------------------------------------+-------+--------+ ¹ On compilers, such as MSVC, that mangle the return type, this is a BiC change if the function is exported. In this case, the const needs to be kept for these compilers until the next BC break, usually the next major Qt release. +² This is technically SiC A, if the target header exists in the X.Y.0 release of Qt in + which the definition was introduced, but the project decided that we do not want these, + because it would mean unnecessary churn for Qt users. + References ---------- diff --git a/quip-0007.rst b/quip-0007.rst index 36104d1..b583e60 100644 --- a/quip-0007.rst +++ b/quip-0007.rst @@ -4,12 +4,16 @@ Author: Kai Köhne Status: Active Type: Implementation Created: 2017-02-15 -Post-History: https://lists.qt-project.org/pipermail/development/2017-March/029198.html +Post-History: + https://lists.qt-project.org/pipermail/development/2017-March/029198.html + https://lists.qt-project.org/pipermail/development/2023-February/043639.html + https://lists.qt-project.org/pipermail/development/2023-February/043667.html + https://lists.qt-project.org/pipermail/development/2023-September/044431.html Overview ======== -From Qt 5.8, Qt modules document their 3rd party code in qt_attribution.json +Qt modules document their 3rd party code in qt_attribution.json files. The format is JSON-based and can be processed with the qtattributionscanner tool. @@ -41,9 +45,15 @@ QtUsage (e.g. by using configure options), and what functionality is missing in this case. Mandatory. +SecurityCritical + Boolean attribute indicating whether the 3rd party code is security critical + - that is, if it is part of code paths that process untrusted code, or is + otherwise critical for security purposes. Optional, default is "false". Path - (Relative) path to the sources. Default is same directory as the file. - Optional. + (Relative) path to the source directory. Default is same directory as the + file. Optional. +Files + Array of paths to the source files, relative to Path. Optional. Description A short description of what the component is and is used for. Optional. Homepage @@ -53,7 +63,13 @@ Version or commit hash from a version control system. Optional. DownloadLocation - Link to exact upstream version. Optional. + Link to exact upstream version. Optional, unless SecurityCritical is + set to "true". +Comment + An arbitrary JSON object, for use by those maintaining third-party + components, to leave notes to those doing future updates. JSON + explicitly allows a name to be used repeatedly so separate comments + can be placed alongside any fields to which they may be relevant. License The license under which the component is distributed, preferably with the names from SPDX [1]_ 'Full Name'. Mandatory. @@ -61,9 +77,14 @@ LicenseId SPDX License Identifier [1]_, or an SPDX Expression [2]_. Optional. LicenseFile Relative path to file containing the license text. Optional for code in the - Public Domain, otherwise needed. + Public Domain. Required for code outside of the public domain if neither + LicenseFiles nor LicenseId are set. +LicenseFiles + Array of relative file paths containing the license texts. Optional for code + in the Public Domain. Required for code outside of the public domain if + neither LicenseFile nor LicenseId are set. Copyright - Aggregated list of copyright lines. Mandatory. + Copyright lines. String or (since Qt 6.5) string array are accepted. Mandatory. The list can be edited for brevity by, for example, combining different copyright years for the same author. Terms like "All rights reserved" can be @@ -79,6 +100,33 @@ Copyright is also acceptable. +Specification of License Files +------------------------------ + +There are two ways of specifying license files for 3rd-party code. + +Using SPDX License Identifiers +`````````````````````````````` + +For licenses that can be expressed with a valid SPDX license expression [1]_, +the corresponding license texts can be placed in +``LICENSES/<SPDX_IDENTIFIER>.txt`` files. The *LicenseId* property is required +in this case. + +*LicenseFiles* and *LicenseFile* are not required. + +A ``LICENSES/<SPDX_IDENTIFIER>.txt`` file can be created using the reuse +tool [6]_ by running:: + + pip install reuse + reuse download <SPDX_IDENTIFIER> + +Directly specifying the license file path +````````````````````````````````````````` + +With *LicenseFiles* or *LicenseFile* one can specify a list or just one license +file. The *LicenseId* property is optional in this case. + Related Work ============ @@ -121,3 +169,4 @@ References .. [3] https://spdx.org/specifications .. [4] https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ .. [5] https://src.chromium.org/viewvc/chrome/trunk/src/third_party/README.chromium.template +.. [6] https://github.com/fsfe/reuse-tool diff --git a/quip-0010-API-review.rst b/quip-0010-API-review.rst index c7b5d94..53b0694 100644 --- a/quip-0010-API-review.rst +++ b/quip-0010-API-review.rst @@ -27,8 +27,8 @@ The review takes the form of a code review, comparing the API-defining files of each module at the last release with their counterparts for the upcoming release. A commit representing this change, for each module, can be generated -by scripts in the qtsdk_ module, named ``all-api-modules`` -and ``api-review-gen``, which drive other scripts. +by scripts in the qtqa_ module's ``scripts/api-review/`` subdirectory, +named ``all-api-modules`` and ``api-review-gen``, which drive other scripts. See ``all-api-modules --help`` for details. Although the review is actually of a commit based on the earlier @@ -66,5 +66,5 @@ When all modules' API reviews have closed, the review task is resolved as Done. References ---------- -.. _qtsdk: https://code.qt.io/cgit/qtsdk/qtsdk.git +.. _qtqa: https://code.qt.io/cgit/qt/qtqa.git .. _`API design principles`: https://wiki.qt.io/API_Design_Principles diff --git a/quip-0013-Examples.rst b/quip-0013-Examples.rst new file mode 100644 index 0000000..05e0857 --- /dev/null +++ b/quip-0013-Examples.rst @@ -0,0 +1,147 @@ +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, +https://lists.qt-project.org/pipermail/development/2023-September/044467.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. + +Namespaced Qt +~~~~~~~~~~~~~ + +Qt examples need to compile also with Qt versions configured with +a custom namespace (configure -qt-namespace). However, the macros that +enable forward declaring Qt types - QT_BEGIN_NAMESPACE, QT_END_NAMESPACE, +QT_FORWARD_DECLARE_CLASS - are internal macros that are not supposed +to be used in customer code. Avoid using these, even if this means you need +to include an otherwise optional Qt header file. + +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 + +- `Qt in Namespace`: https://wiki.qt.io/Qt_In_Namespace diff --git a/quip-0015-Security-Policy.rst b/quip-0015-Security-Policy.rst new file mode 100644 index 0000000..5e5f35f --- /dev/null +++ b/quip-0015-Security-Policy.rst @@ -0,0 +1,162 @@ +QUIP: 15 +Title: Qt Project Security Policy +Author: Volker Hilsheimer +Status: Active +Type: Process +Content-Type: text/x-rst +Created: 2019-05-21 +Post-History: https://lists.qt-project.org/pipermail/development/2019-May/036030.html + https://lists.qt-project.org/pipermail/development/2020-June/039672.html + +Qt Project Security Policy +========================== + +This QUIP documents the security policy of the Qt project. The goal is to inform +users of Qt about how the project handles security issues in Qt, and to document +processes that enable contributors to the Qt project to participate in the +prevention and handling of suspected vulnerabilities. + +The Core Security Team +---------------------- + +The Core Security Team of Qt developers with `Approver`_ privileges is established +with the responsibility to ensure that this policy is followed. Any Approver may +volunteer to become a member of the Core Security Team, but needs to be supported +by at least one other approver. Members of the Core Security Team are added to +the security mailing list (security@qt-project.org). + +.. _`Approver`: https://quips-qt-io.herokuapp.com/quip-0002.html#approvers + +.. _`security mailing list`: https://lists.qt-project.org/listinfo/security + + +Proactive Measures to Prevent Security Issues +--------------------------------------------- + +The Qt project has implemented regular processes that help us reduce the risk of +introducing security vulnerabilities into the code-base or releasing them to users. + +* The established `code review process`_ and `commit policy`_ prevent bad or + compromised actors from committing malicious code or backdoors to the Qt + code-base. +* The Qt source code is regularly scanned using static code analysis tools. +* Qt functionality that is designed to consume untrusted data is regularly tested + using fuzzing. +* High priority issues discovered through static code scans and fuzz testing are + reported as security issues, and addressed before the next release. +* For each Qt release, third-party components are updated to the latest version + that is compatible with the respective Qt release. +* For each release, the Qt installer and other binary content in the released + packages are scanned with antivirus tools. +* The Core Security Team monitors the CVE database for vulnerabilities in third- + party components, and coordinates the application of necessary patches with + the module maintainers. + +.. _`code review process`: https://wiki.qt.io/Review_Policy + +.. _`commit policy`: https://wiki.qt.io/Commit_Policy + +Reporting Security Issues +------------------------- + +Security issues should not be reported via the normal bugreports.qt.io tracker, +but should instead be sent to security@qt-project.org. For commercial licensees, +the issue can be reported to the Qt Company Support team via the support +portal, using the "Security Issues" category. + +* The Core Security Team monitors and moderates incoming emails on business + days (i.e. not including weekends), and approves all posts that are not spam. +* Approved posts are delivered to all recipients subscribed to the security + mailing list. +* Any issue reported to security@qt-project.org should receive (at least) an + acknowledgment of receipt within two business days. +* If there is no response in the above time frame (this should never happen), + then the reporter should contact the Chief Maintainer directly. +* The Core Security Team controls membership of the security@qt-project.org; + generally, all `Maintainers`_ are subscribed to this list. +* For security issues reported to the Qt Company Support team, they will be + reported to security@qt-project.org and the reporter will be sent an + acknowledgment that this has been done. + +.. _`Maintainers`: https://quips-qt-io.herokuapp.com/quip-0002.html#maintainers + +Handling of Reported Security Issues +------------------------------------ + +* The Core Security Team determines if an issue falls within the purview of an + existing Maintainer; if so, then they ensure that the Maintainer is informed. +* Any issue reported should be triaged by the Maintainer to determine the risk + it poses to end-users of Qt within four business days of the initial report + to security@qt-project.org. +* Until the triaging is done and the analysis has been shared with the Core + Security Team via email to security@qt-project.org, any reported issue is + assumed to have P0 priority. +* Any issue determined to be high risk should be immediately reported to the + Chief Maintainer by the security team. +* If no triaging analysis is shared with the Core Security Team within seven + days, then the Core Security Team should escalate the issue to the Chief + Maintainer. +* Maintainers are responsible for addressing any security issues in the code + they maintain. +* The Core Security Team is responsible for ensuring that the issue is addressed + according to this policy, supports the Maintainer, and coordinates with other + relevant contributors and third parties. +* If the reported vulnerability is in third-party code, then the Core Security + Team coordinates with Maintainers and the respective third party. +* If the reported vulnerability is in commercially licensed only code, then the + Qt Company will handle it accordingly. +* Reported issues that are assessed to not have an impact on security can be + handled as regular bug reports, and may be filed by a suitable party in the + normal bugreports.qt.io tracker. + +How will Issues be Disclosed? +----------------------------- + +* The Core Security Team ensures that confirmed security issues in Qt code + are listed in the `Common Vulnerabilities and Exposures database`_, and + if needed files them after the risk assessment. +* Security issues will be disclosed by an email to the announce@qt-project.org + mailing list and to all commercial licencees once the CVE entry is published. +* All members of the Core Security Team must have posting rights for the + announce@qt-project.org list for this purpose. +* All security announcements will be made on behalf of the Qt Project, though + credit to those responsible for identifying and addressing the issue should + be made. +* The security announcement should describe: + * The security issue. + * How and when it will be addressed. + * Sufficient technical detail to allow users of Qt to determine the impact + on their applications. + * How to fix or work around the issue in existing installations and + applications. +* If an issue requires clarification beyond the security announcement, then this + can be done using the development mailing list or the interest mailing list. + This is not expected to be required for all security announcements and does + not replace the formal notification via the announce mailing list. +* Where possible, early notification should be sent to packagers such as + distribution contacts. These notifications should be considered privileged + information. A security-announce list for distribution contacts will be used + for this purpose. +* Membership of the security-announce mailing list should be kept small, and + granted only by agreement with the Core Security Team. This membership can + be revoked at any time, with no explanation required. +* Where possible, packagers should be informed directly of which SHA1s they + should cherry-pick in order to get a security fix. +* For every minor version of Qt, fixed security issues will be listed in the + change file of the first patch release which contains the fix. + +.. _`Common Vulnerabilities and Exposures database`: https://cve.mitre.org + +What Versions of Qt are Covered by this Policy? +----------------------------------------------- + +While we are interested in reports against any Qt version that is still +maintained, fixes are only guaranteed to be provided for: + +* The latest released version. +* The preceding minor version. + +Fixes for earlier versions, in particular LTS releases, may be provided, but the +Qt project makes no commitment to do so. Other groups such as The Qt Company +may choose to make such fixes available, but that is outside the scope of the +Qt project. diff --git a/quip-0016-branch-policy.rst b/quip-0016-branch-policy.rst new file mode 100644 index 0000000..136d19e --- /dev/null +++ b/quip-0016-branch-policy.rst @@ -0,0 +1,252 @@ +QUIP: 16 +Title: Branch policy +Author: Volker Hilsheimer +Status: Active +Type: Process +Created: 2020-04-29 +Post-History: https://lists.qt-project.org/pipermail/development/2019-November/037927.html +Replaces: QUIP 5 + +======================================== +Branch policy +======================================== + +Motivation +---------- + +In order to sustain vigorous development while maintaining stable releases without subjecting +users to disruptive upgrades, the Qt framework has diverse branches, on some of which only the +least disruptive of changes are permitted while, on others, developers have more freedom to +change APIs and behaviors. The aim of this QUIP is to make clear which changes go into +which branches, what stability commitments The Qt Project makes to its users for its various +types of release, and how the former ensures the latter. + +It supersedes QUIP 5 with the changes discussed at the +`QtCS2019 Branch Policy Session`_. + +Note 1: The QUIP applies to the normal course of development. Close to +feature-freezes, branching and releases, the release team may impose +tighter control. + +Note 2: The guidelines apply to the Qt frameworks only. Other products (like +Qt Creator) may choose a different approach. + +.. _`QtCS2019 Branch Policy Session`: https://wiki.qt.io/Qt_Contributors_Summit_2019_-_Branch_Policy + + +================== +Types of Branches +================== + +Goal of the release branches (X.Y.Z) +------------------------------------ + +- Prepare the code-base for a release, only making changes needed for that release. + + +Goal of the long term support (LTS) branches (5.12 at the time of writing) +-------------------------------------------------------------------------- + +- Support for 3 years after its initial release, extending the stable phase +- Two releases each year, plus extra releases for fixes to any issues deemed + critical enough. +- Support slow-moving OSes +- Fix bugs in applications that were already shipped bundling the LTS and + continue to build against the LTS +- Have a low regression risk +- Add new minor platforms - if and only if changes are minimal +- Add support for newer toolchains - if and only if changes are small +- Documentation clarifications + +We divide the LTS into 3 periods: + +*stable* + Initially, the LTS branch is handled like any stable branch. + +*strict* + This period starts when the one after next stable branch is created (for the + 5.12 LTS, the one after next was 5.14). Upgrading the Qt libraries (within LTS) + must not put installed applications at risk of breaking. Breaking existing bug + workarounds is therefore not allowed, even if the bug is fixed. + +*very strict* + (third year) we only accept fixes to P0 and P1 bugs, which there should be very + few of by this stage. + +*Note*: From 5.15 onwards, the extension of the stable phase becomes a service for +users of Qt under the commercial license. The stable phase ends when the next minor +or major release is available (typically after 6 months), and *strict* and +*very strict* phases affect only commercial releases. + +Goal of the stable branches (5.x) +--------------------------------- + +Each stable branch is initially stabilized after branching off dev, +in preparation for serving as the base for successive release branches. +Once stable, the branch accepts: + + - bug fixes + - performance fixes + - documentation fixes + +Goal of the dev branch: +----------------------- + +- New feature development (adding new API, classes, libraries or modules) +- Refactoring +- Risky changes, requiring longer testing period +- Completely new platforms + + +======== +Workflow +======== + +Changes are generally developed and submitted against the dev branch. Changes +that qualify for a stable, strict, or release branch may be cherry-picked into +those branches once the merge into dev is completed. This might require some +backporting and adjustments, or even a complete rewrite of the change. All +cherry-pick changes need to reference the original commit. + +Cherry-picking +-------------- + +Cherry-picking can be done semi-automatically, using the `Pick-to:` footer in +the commit message. The `Pick-to:` footer specifies a space-separated list of +branches into which the change should be cherry-picked once the patch has been +successfully merged. + +Each branch listed in the `Pick-to:` footer will generate a cherry-pick patch on +the target branch based on the latest revision of the merged patch. The owner of +the new patch will be the `Qt Cherry-pick Bot`, and the author of the original +commit will be the author of the cherry-pick. If the cherry-pick bot does not +encounter any conflicts, the commit will be automatically approved and staged. + +In case of any issues during the process, the original author will be set as the +assignee of the cherry-pick patch, and reviewers will be copied from the original +change. Author and reviewers will be notified about the issue, and can amend the +patch like any regular change review. + +To cherry-pick changes manually, use the `-x` option, and don't change the +gerrit `Change-Id` footer. The cherry-pick must be done from the commit once +it has been integrated into the published branch, not from a branch in a local +clone, whose sha1 shall be different from the published version. Even when the +change is a complete rewrite, it shall reference the original commit in its +commit message, using a "fake" cherry-pick footer following the pattern +`(adapted from commit <sha1>)`. Submit the patch for review like any other change. + + +Exceptions +---------- + +Changes should only be made directly on stable branches when there is no +matching change to make on dev (e.g. because the code in question has been removed). +In such cases, the change should be made on the newest stable branch to which it +applies and cherry-picked back to any older stable branch to which it may be relevant. + +Submitting changes directly to a strict LTS branch is not possible; changes +must be submitted to the stable branch and undergo some testing first before +being cherry-picked into a strict LTS branch. + +Changes made as part of the release process (such as adding change files) should +normally be kept to a minimum. Such changes should be propagated to their stable +branch, any more recent stable branches, and dev. + +=============================== +Types of changes to cherry-pick +=============================== + +The table below lists typical code changes, and indicates the branch the +change may be cherry-picked to. The table shows the most stable branch (i.e. +right-most), for every case. If a change is risky or it has lower impact, +then it should only be cherry-picked to a less stable (i.e. further to the left) +branch. + +Types of changes not listed here are in general only relevant for the dev branch, +and do not get cherry-picked. In particular, any feature addition, refactoring, +or adoption of new C++ language features does not get cherry-picked. + +In all cases, we need to estimate the impact of the change. For example, a fix +for a performance problem may end up in a different branch depending on: how +many users are affected, how big is the improvement, and what is the risk of +regressions. + ++----------------------------+--------+----------------------+---------+---------------------+ +| | | LTS | | | +| Reason for Change | Stable +--------+-------------+ Release | Notes | +| | | Strict | Very Strict | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Binary compatibility | | | | x | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Source compatibility | | | | x | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| API review finding | | | | x | Initial release | +| | | | | | only | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| RTA/package test finding | | | | x | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Security issue | | | | x | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| 3rd party update | | | x | | Very Strict only | +| | | | | | security/critical | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Adapt to minor OS/ | | | x | | | +| Compiler updates | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Memory leak | | x | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Feature added in this | | x | | | | +| minor version | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Undefined behavior | | x | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Something that makes | | x | | | | +| existing apps unstable | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Performance: significant | | x | | | | +| fix improving O() | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Performance: Issue | x | | | | | +| detected by profiling | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Compiler warnings | | x | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| False positives | x | | | | e.g. static code | +| raised by tools | | | | | analysers | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Documentation: small fixes | | | x | | | +| (links, typos, warnings) | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Documentation: refactoring | x | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Tests: flakiness | | | x | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Tests: refactoring | x | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Bugs: Easily triggered | | | x | | | +| crash | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Bugs: Hard to reproduce | | x | | | | +| crash | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Bugs: Regression | | x | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Bugs: Hard-to-reproduce | x | | | | | +| regression noticed some | | | | | | +| time after release | | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ +| Bugs: Other | x | | | | | ++----------------------------+--------+--------+-------------+---------+---------------------+ + + +Glossary +-------- + +RTA + Release testing automation + +References +---------- + +- `Branch Guidelines <http://wiki.qt.io/Branch_Guidelines>`_ +- `JIRA-Priorities <https://wiki.qt.io/JIRA-Priorities>`_ diff --git a/quip-0017-Change-log-creation.rst b/quip-0017-Change-log-creation.rst new file mode 100644 index 0000000..79fcd95 --- /dev/null +++ b/quip-0017-Change-log-creation.rst @@ -0,0 +1,80 @@ +QUIP: 17 +Title: Change log creation +Author: Mitch Curtis +Status: Active +Type: Process +Created: 2020-08-25 +Post-History: https://lists.qt-project.org/pipermail/development/2019-November/037927.html + +Overview +======== + +The Qt framework uses change logs as a means of informing users about new +features, important behavior changes, and bug fixes. Before each release, a +change log file is generated from the section of git commit messages that start +with the [ChangeLog] keyword. + +Content +======= + +Do include: +- Noteworthy features +- Significant changes +- Changes that affect many users +- Changes that affect compatibility +- Changes to information about third-party code (see QUIP-4) + +Do not include: + +- Fixes in tests +- Documentation fixes +- Pure code cleanup or refactoring +- Fixes for regressions introduced in not-yet-released commits +- Anything that is not relevant to users + +Format +====== + +- A [ChangeLog] entry may span multiple lines and ends with an empty line. +- You may add more than one [ChangeLog] entry, each in a separate paragraph, + if there are several ways the change affects users. +- Each entry starts with a sequence of tags, each in square brackets, the + first of which is [ChangeLog]. + + - If the Git repository contains multiple modules, use the module name as a + tag to indicate the area of the change, e.g. [QtCore]. + - Optionally specify a class or subtopic as an additional tag, e.g.: + [QtNetwork][QSslSocket] + - Other common tags are: + + - [General] + - [Important Behavior Changes] + - [Potentially Source-Incompatible Changes] + - [Deprecation Notices] + - [Platform Specific Changes] + - [Windows] + - [macOS] + - [Linux/XCB] + - [Third-Party Code] +- After the tags, describe how the change impacts users of the relevant + component. + + - Try to integrate the ChangeLog entry into the surrounding commit message to + avoid redundancy. + - If the change resolves a security issue, summarise the issue and mention any + relevant `CVE <https://cve.mitre.org>`_ or kindred identifiers. + - The description should use either simple past ("Fixed …") or be explicit + about referring to the current state ("… does now …"). + - Make sure the entry is reasonably self-contained. If you fail to formulate a + meaningful description, it's probably not useful information to start with. +- In summary, the entry should look like this: :: + + [ChangeLog][module][class/topic] description of the really important change + that was just made (on several lines). + +Tools +===== + +The createchangelog tool in the qtqa.git module is currently the most +feature-complete tool for change log creation. Documentation for it +can be found in its README under src/createchangelog. diff --git a/quip-0018-license-specification.rst b/quip-0018-license-specification.rst new file mode 100644 index 0000000..201a2f9 --- /dev/null +++ b/quip-0018-license-specification.rst @@ -0,0 +1,194 @@ +QUIP: 18 +Title: License specification in Qt's modules +Author: Lucie Gerard, + Jörg Bornemann +Status: Active +Type: Informational +Created: 2022-09-26 +Post-History: + https://lists.qt-project.org/pipermail/development/2023-February/043648.html + https://lists.qt-project.org/pipermail/development/2024-February/045028.html + +Overview +======== + +This QUIP specifies the licenses that are used in different parts of a +typical Qt module repository and also provides helpful guidance about +how to express which license source code is under. + +License header format +===================== + +The license header follows the SPDX standard [0]_. + +There is at least one copyright line and exactly one license +expression line:: + + Copyright (C) 2023 The Qt Company Ltd. + SPDX-License-Identifier: <spdx-license-expression> + +A copyright line for code written by a contributor outside the Qt +Company can include that contributor's name (or a legal entity they +represent) in the Copyright header. + +The copyright line should include the year the file was created, or - +in the case of additional copyright lines - the year the additional +copyright notice was added. Updating the copyright year when changes +are made to the file is possible. + +The copyright line may be prefixed with `SPDX-FileCopyrightText:`. + +The `<spdx-license-expression>` must be a valid expression, according +to the SPDX standard as defined in [1]_. + +The license identifiers used in a license expression are either from +the list of known licenses [2]_ or prefixed with `LicenseRef-`. + +The license files are placed into a `LICENSES` directory below the Qt +module repository's root. The license files are named after the SPDX +license identifier followed by ``.txt`` [3]_. + +Classification of files +======================= + +There are various kinds of files in a Qt module repository that should +include license headers. Here, we classify these files in order to +identify which files should be under which licenses. + +Files that do not support inline comments do not have to contain +licensing information. If licensing information for such files is +still desirable, it should be placed into an adjacent ``.license`` +text file. For example, ``blob.bin`` may be accompanied by +``blob.bin.license`` in the same directory. + +Licensing information may be omitted for files with trivial content. + +The documentation landing page of a Qt module contains a "Licenses and +Attributions" section that defines the licenses under which the module +and plugin implementation is available. See the list of Qt modules +[6]_. + +Module and plugin implementation +-------------------------------- + +Files that belong to the implementation of Qt modules and plugins. The +usual locations for module source code are the subdirectories ``src/`` +and ``plugins/``. + +There are two licensing models for module and plugin implementations: +GPL-only and one that is additionally licensed under LPGL. + +The license expression permitting the LPGL is +``LicenseRef-Qt-Commercial OR LGPL-3.0-only OR GPL-2.0-only OR +GPL-3.0-only``. + +The GPL-only license expression is ``LicenseRef-Qt-Commercial OR +GPL-3.0-only``. + +The license expression for files that are statically linked with user +code - even for dynamic builds of Qt - is +``LicenseRef-Qt-Commercial OR BSD-3-Clause``. + +Examples and Snippets +--------------------- + +Files that belong to the implementation of Qt examples. The usual +locations for examples is the ``examples/`` subdirectory. + +Also, any source code that appears in the documentation. The usual locations are +``snippets/`` directories throughout the Qt module repository's directory +tree. + +The license expression for examples and snippets is ``LicenseRef-Qt-Commercial OR +BSD-3-Clause``. + +Tests +----- + +Files that belong to the implementation of Qt tests. The usual +location is the ``tests/`` subdirectory. + +The license expression for tests is ``LicenseRef-Qt-Commercial OR +GPL-3.0-only``. + +Tools and Utils +--------------- + +Files that belong to the implementation of Qt tools that are for use +by Qt users. The usual location is the ``src/tools/`` subdirectory. + +Also considered tools are script and shell files, +as long as they are not part of an example or a documentation snippet. +Such files are usually using the following file name patterns: + +- ``*.sh`` +- ``*.py`` +- ``*.pl`` +- ``*.bat`` +- ``*.ps1`` + +Finally, files that are located in a /util/ directory. + +The license expression for tools and utils is ``LicenseRef-Qt-Commercial OR +GPL-3.0-only WITH Qt-GPL-exception-1.0``. + +Documentation +------------- + +All ``.qdoc``, ``.qdocinc`` and ``.qdocconf`` files that are needed to +generate the documentation. + +The license expression for documentation is ``LicenseRef-Qt-Commercial +OR GFDL-1.3-no-invariants-only``. + +Build System Files +------------------ + +All files that contribute to Qt's build system. That includes the following file +name patterns: + +- ``CMakeLists.txt`` +- ``*.cmake`` +- ``*.pro`` +- ``*.pri`` +- ``*.prf`` + +If such a file is present in a snippet directory, it is licensed as +a documentation snippets file. +If such a file is present in an example directory, it is licensed as +an example file. + +The license expression for build system files is ``BSD-3-Clause``. + +Testing License Usage +===================== + +The Qt CI can enforce correct usages of license files. +This requires a 'licenseRule.json' file to exist in the top-level +directory of the Qt module's repository. This file contain +declarative rules, based on file suffix and directory, +and should follow the rules set out in this QUIP. +They do allow for exceptions and special cases though, if necessary. + +Related Work +============ + +The "Software License Agreement between The KDE Free Qt Foundation and +The Qt Company Oy" [4]_ poses restrictions for the licenses of the Qt +Free Edition modules. + +To a certain extent, Qt follows REUSE [5]_. REUSE is a guideline on +how to specify the licenses in a project. We don't aim for full +compliance at this point, due to small/binary files and 3rd party +content. + +References +========== + +.. [0] https://spdx.github.io/spdx-spec/v2.3/ +.. [1] https://spdx.github.io/spdx-spec/v2.3/SPDX-license-expressions/ +.. [2] https://spdx.org/licenses/ +.. [3] https://reuse.software/tutorial/#step-1 +.. [4] https://kde.org/community/whatiskde/Software_License_Agreement_2015_Text.pdf +.. [5] https://reuse.software/spec/ +.. [6] https://doc.qt.io/qt-6/qtmodules.html diff --git a/quip-0019-nodiscard-policy.rst b/quip-0019-nodiscard-policy.rst new file mode 100644 index 0000000..8bec419 --- /dev/null +++ b/quip-0019-nodiscard-policy.rst @@ -0,0 +1,161 @@ +QUIP: 19 +Title: [[nodiscard]] Policy +Author: Marc Mutz +Status: Active +Type: Implementation +Created: 2023-06-19 +Post-History: https://lists.qt-project.org/pipermail/development/2023-June/044044.html + +``[[nodicard]]`` Policy +======================= + +This QUIP aims to document how we use the ``[[nodiscard]]`` attribute in Qt. + +Motivation +---------- + +The ``[nodiscard]]`` attribute can be applied to functions to cause a +warning if the function's return value is ignored (discarded). This +can be used to alert the user of the function to non-sensical +(``list.empty();``) or dangerous code (ignoring error codes). + +It can also be applied to constructors (but see below) to warn about +the object being ignored (``QMutexLocker(&mutex)`` instead of +``QMutexLocker locker(&mutex)``). + +Finally, it can be applied to classes whole-sale, in which case it +applies to all functions returning that type, Qt or user functions, +and, depending on compiler, to all constructors of the type, too. + +Version History +--------------- + +- Since ``[[nodiscard]]`` is a C++17 addition, Qt 5 has the + ``Q_REQUIRED_RESULT`` macro, defined to platform-dependent + equivalents, if any. This macro can only be used on + (non-constructor) functions. + +- Since Qt 6.0, we can use ``[nodiscard]`` unconditionally on + (non-constructor) functions and at class level (non-exported classes + only). The use of ``Q_REQUIRED_RESULT`` is discouraged in Qt 6. + +- Since Qt 6.6, we can use ``Q_NODISCARD_CTOR`` to apply + ``[[nodiscard]]`` to contructors, too. + +- Since Qt 6.7, we have access to C++20 ``[[nodiscard("reason")]]`` + via ``Q_NODISCARD_X`` and ``Q_NODISCARD_CTOR_X``. + +Policy +------ + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", +"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this +document are to be interpreted as described in `RFC 2119 +<https://datatracker.ietf.org/doc/html/rfc2119>`_. + +Unless mentioned otherwise, the following applies to both public and +private Qt C++ APIs. + +Unless mentioned otherwise, whenever ``[[nodiscard]]`` or +``Q_NODISCARD_CTOR`` are mentioned below, it SHALL be read as +including ``Q_NODISCARD_X`` and ``Q_NODISCARD_CTOR_X`` respectively. + +Constructors +```````````` + + +1. From Qt 6.6 onwards, all constructors of RAII and smart pointer + classes SHALL be marked as ``Q_NODISCARD_CTOR``. Constructors of + other classes MAY be marked as ``Q_NODISCARD_CTOR``, at author's + and reviewer's discretion. + +2. Qt versions prior to 6.6 lack the macro and therefore can't use + ``[[nodiscard]]`` on constructors. + +3. If (1) asks to mark all constructors of a class nodiscard, then + _named constructors_ (static functions returning an instance of the + class; often prefixed ``from~~~~()`` or ``create~~~()``) SHALL be + marked ``[[nodiscard]]``. + +Other Functions +``````````````` + +1. Functions where calls that ignore the return type are most likely + wrong (e.g. ``QList::empty()``, which sounds like a modifying + function, but in fact is ``const``) SHALL be marked as + ``[[nodiscard]]`` (or ``Q_REQUIRED_RESULT``, in Qt 5). + +2. Other functions whose only side-effect is to produce the + return value, esp. `const` member functions, MAY be marked as + ``[[nodiscard]]``, at author's and reviewer's discretion. + +3. Functions that have side-effects SHALL NOT be marked + ``[[nodiscard]]``, unless they fall into Case 1. + +Whole Classes +````````````` + +1. We currently do not use ``[[nodiscard]]`` on whole classes. Qt + still contains such uses, but they are historic and scheduled to be + replaced with ``Q_NODISCARD_CTOR`` on all the class' constructors. + +2. ``[[nodiscard]]`` MAY be used on classes, though, provided the user + documentation (in case of public API) or the commit message (in + case of private API) give rationale for doing so. + +3. Due to a bug in GCC, ``[[nodiscard]]`` *classes* cannot be exported + wholesale at the moment. If there is enough demand, this may be + worked around in the future. + +Formatting +---------- + +1. Syntactically, ``[[nodiscard]]`` MUST come first in the + declaration, esp. before a ``Q_*_EXPORT`` macro, if any. If the + function is a template, the *template-initalizer* MUST come + first. C++ enforces both, even though some compilers are known to + accept some forms of non-standard formatting, too (e.g. GCC). + + Examples: + + :: + + template <typname T> + [[nodiscard]] int foo(const T&); + + [[nodiscard]] Q_CORE_EXPORT int foo(const QString&); + + [[nodiscard]] Q_CORE_EXPORT QVeryLongReturnTypeClassName + bar(const QString&); + + Q_NODISCARD_CTOR explicit QFoo(const QBar &); + + Definitions that are not declarations SHALL NOT repeat the + attribute. + +2. New code SHOULD add the ``[[nodiscard]]`` or ``Q_NODISCARD_CTOR`` + as part of the line that also contains the (leading) return type. + + See point 1 for examples. + +3. When adding ``[[nodiscard]]`` or ``Q_NODISCARD_CTOR`` to + declarations that pertain to already-released API, the attribute + SHOULD be added on a separate line, or in a line with other + attributes newly-added for the current release. This makes the + header diff easier to read in API diffs at the cost of somewhat + more vertical space needed for the declaration going forward. + +4. The ``_X`` variants and ``[[nodiscard("reason")]]`` SHOULD always + be placed on a separate line, because they tend to be long + themselves. + +References +---------- + +`[[nodiscard]] documentation <https://en.cppreference.com/w/cpp/language/attributes/nodiscard>`_ + +`"[[nodiscard]] for ctors", Peter Sommerlad <https://wg21.link/p1771>`_ + +`GCC bug preventing class-level [[nodiscard]] on exported classes <https://gcc.gnu.org/bugzilla/show_bug.cgi?id=96117>`_ + +`"[[nodiscard("should have a reason")]]", JeanHeyd Meneide, Isabella Muerte <https://wg21.link/p1301>`_ diff --git a/quip-0021-images-in-docs.rst b/quip-0021-images-in-docs.rst new file mode 100644 index 0000000..36e84e9 --- /dev/null +++ b/quip-0021-images-in-docs.rst @@ -0,0 +1,165 @@ +QUIP: 21 +Title: Using images in Qt documentation +Author: Leena Miettinen +Status: Active +Type: Process +Created: 2023-11-13 +Post-History: https://lists.qt-project.org/pipermail/development/2023-November/044706.html + +Overview +======== + +You can use the following types of images in Qt documentation: + +- Screenshots +- Line diagrams +- Icons +- Animated images +- Embedded YouTube videos + +Saving images +============= + +QDoc can create references to images of any format. The image is shown if +the user's tool or browser supports the image format. Most browsers support the +following image formats: + +- GIF (``.gif``) +- JPEG (``.jpg``) +- WebP (``.webp``) +- PNG (``.png``) +- SVG (``.svg``) + +You can find reasons for picking a particular image format in the following +sections. + +Locations +--------- + +Save images in the Git repositories in an ``images`` folder. QDoc looks for +images in folders that you specify as values of the ``imagedirs`` variable [0]_ +in the documentation configuration file (``.qdocconf``). + +You can create subfolders for particular types of images, such as icons or +images used in examples. + +Considerations +-------------- + +Binary images can easily add megabytes to the Git history. To keep the history as +small as possible, the Git post-commit hooks remind you to try to keep image file +size below 50 KiB. To achieve this goal, crop images so that only relevant +information is visible. + +When possible, save images in WebP format for a smaller image file size. + +If you need to use the PNG format, optimize the images by using an image +optimization tool, such as ``optipng``. Optimization should not visibly +reduce image quality in the built documentation. If it does, save the +image as WebP or JPEG instead. + +QDoc commands and macros +======================== + +Use QDoc commands to refer to images from the text: + +- ``\image`` places the image on a separate line [1]_ +- ``\inlineimage`` places the image inline, surrounded by text [2]_ +- ``\youtube`` embeds a video from YouTube [3]_ + +Screenshots +=========== + +Qt tools, such as Qt Creator and Qt Design Studio, have the native look and feel +on Windows, Linux, and macOS. Therefore, screenshots can end up looking very +different depending on who takes them and which operating system they use. +Try to take the screenshots on one operating system, when possible. + +Follow these guidelines when taking screenshots: + +- Use the screen resolution of 1920x1080. + (Available on the most commonly used screens, as of this writing.) +- Use display scaling 100%. +- Use your favorite tool to take the screenshot. +- Include only the part of the screen that you need. + (You can crop the image also in the screen capture tool). +- Close all unnecessary views to avoid clutter. +- Do not scale or resize the images in the tool because it causes + reduced visual quality and increases the file size. Also, the CSS we use + online scales down images that are wider than 800 pixels. +- To highlight parts of the screenshot, use the images of numbers + that are stored in [4]_. +- If you use PNG images, optimize them before you submit them to the repository. + +Note: Do not rely on screenshots to present reasonable example values to +users, but always place example values also in the text. + +Note: The selected screen resolution is a compromise that offers acceptable +quality with acceptable image file size. We are looking for solutions to using +high-DPI images [5]_. + +Highlighting parts of the screen +--------------------------------- + +You can use number icons in screenshots to highlight parts of the screenshot +(instead of using arrows or borders, for example). You can then refer to the +numbers in text. For example, see [6]_. + +This improves the consistency of the look and feel of Qt documentation, +and eliminates the need to describe parts of the UI in the text because +you can just insert the number of the element you are referring to in +brackets. + +You can find images of numbers from 1 to 10 in [4]_. + +To use the numbers, copy-paste the number images on the screenshot to the +places that you want to refer to from text. + +Icons +===== + +You can view Qt Documentation online [7]_ in dark and light modes. To make the +icons used in the docs visible in both modes, save icon files as gray-scale +images with a transparent background. + +If you receive a large number of icons that are not visible in either light +or dark mode or have a solid background, run the ``recolordocsicons.py`` +Python script from the ``qttools/util/recolordocsicons`` folder. For options +and examples, see [8]_. + +Animated images +=============== + +Sometimes, it is easier to explain how something works by recording a short +animation in lossless WebP or GIF format. You can use any tool you like, such +as the screen recorder in Qt Creator [9]_ or ScreenToGif [10]_. Animated images +are typically bigger than screenshots, so try to make them as short and to the +point as you can. + +Use the ``\image`` command [1]_ to refer to WebP and GIF files from the +documentation. + +Note: If the animation is very long, consider recording a video and embedding +it from YouTube. + +YouTube videos +============== + +You can use the ``\youtube`` macro [3]_ to embed a YouTube video in the HTML. +When QDoc generates offline documentation (``.qch``), it adds an external +link to the video with a thumbnail image. + +References +========== + +.. [0] https://doc.qt.io/qt-6/22-qdoc-configuration-generalvariables.html#imagedirs +.. [1] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#image-command +.. [2] https://doc.qt.io/qt-6/09-qdoc-commands-includingimages.html#inlineimage-command +.. [3] ``macro.youtube`` in ``qtbase/doc/global/macros.qdocconf`` +.. [4] ``qtdoc/doc/images/numbers/`` +.. [5] https://bugreports.qt.io/browse/QTBUG-63366 +.. [6] https://doc.qt.io/qtcreator/creator-quick-tour.html +.. [7] https://doc.qt.io/ +.. [8] ``qttools/util/recolordocsicons/README.md`` +.. [9] https://doc.qt.io/qtcreator/creator-how-to-record-screens.html +.. [10] https://www.screentogif.com/ diff --git a/quips.pro b/quips.pro deleted file mode 100644 index 33ec099..0000000 --- a/quips.pro +++ /dev/null @@ -1,38 +0,0 @@ -TEMPLATE = aux - -QUIPS += $$files($$PWD/quip-*.rst) - -PYTHON = python -GENQUIP0_PY = $$PWD/scripts/gen-quip-0000.py -QUIP2HTML_PY = $$PWD/scripts/quip2html.py -HTTP_PORT = 8000 - -quip2html.input = QUIPS -quip2html.output = html/${QMAKE_FILE_BASE}.html -quip2html.commands = $$PYTHON $$QUIP2HTML_PY ${QMAKE_FILE_NAME} > ${QMAKE_FILE_OUT} -quip2html.depends += $$QUIP2HTML_PY template.html -quip2html.CONFIG += target_predeps - -quip_0000.target = html/quip-0000.html -quip_0000.commands = $$PYTHON $$GENQUIP0_PY $$QUIPS | $$PYTHON $$QUIP2HTML_PY - > $$quip_0000.target -quip_0000.depends += $$GENQUIP0_PY $$QUIP2HTML_PY $$QUIPS html/.ready - -html_index.target = html/index.html -html_index.commands = ln -sf quip-0000.html html/index.html -html_index.depends = html/.ready - -html_setup.target = html/.ready -html_setup.commands = make -f $$PWD/scripts/setup.mk SRC=$$PWD setup - -template.depends = $$PWD/scripts/template.diff $$PWD/planetqt/template.qt -template.target = template.html -template.commands = patch -d $$PWD -l -p0 -i scripts/template.diff -o scripts/template.html && mv $$PWD/scripts/template.html ./ - -html_serve.target = serve -html_serve.commands = cd html && $$PYTHON -m SimpleHTTPServer $$HTTP_PORT - -POST_TARGETDEPS += html/quip-0000.html html/index.html html/.ready -QMAKE_CLEAN += html/ - -QMAKE_EXTRA_TARGETS += html_setup template quip_0000 html_index html_serve -QMAKE_EXTRA_COMPILERS += quip2html diff --git a/scripts/gen-quip-0000.py b/scripts/gen-quip-0000.py index afc6bc2..ebc0d43 100755 --- a/scripts/gen-quip-0000.py +++ b/scripts/gen-quip-0000.py @@ -1,23 +1,24 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 # -*- coding: utf-8 -*- -# Copyright (C) 2017 The Qt Company Ltd. +# Copyright (C) 2020 The Qt Company Ltd. # Contact: http://www.qt.io/licensing/ # # You may use this file under the terms of the CC0 license. # See the file LICENSE.CC0 from this package for details. from email.parser import HeaderParser -from glob import glob +from sys import stdout import os.path + class RootQuip (dict): def __init__(self, files): parser = HeaderParser() for quip in files: - with open(quip, 'r') as quipfp: + with open(quip, 'r', encoding='utf-8') as quipfp: self[quip] = parser.parse(quipfp) - def last_name(names): # tool function for owners; not a method + def last_name(names): # tool function for owners; not a method while names and names[-1].startswith('<') and names[-1].endswith('>'): names.pop() return names[-1] @@ -60,15 +61,29 @@ The following QUIPs exist: <tr><th>type</th><th>number</th><th>title</th><th>owners</th></tr> """ - endpiece = """\ + endpiece = """ </table> -.. [0] https://codereview.qt-project.org/#/q/project:meta/quips,n,z +These documents are generated from ReStructuredText sources which can +be found at [1]_. Proposals for change or new QUIPs can be +contributed, via the Qt Project's usual contribution process [2]_, to +the repository [3]_. See QUIPs 1 through 3, above, for further +details. + +.. [0] https://codereview.qt-project.org/q/project:meta/quips + +.. [1] https://code.qt.io/cgit/meta/quips.git/ + +.. [2] http://wiki.qt.io/Qt_Contribution_Guidelines + +.. [3] https://codereview.qt-project.org/admin/repos/meta/quips """ def compose_body(self): return self.preamble + '\n'.join(self.quip_entries()) + self.endpiece + if __name__ == '__main__': import sys - print RootQuip(sys.argv[1:]).compose_body() + sys.stdout.reconfigure(encoding='utf-8') + print(RootQuip(sys.argv[1:]).compose_body()) diff --git a/scripts/quip2html.py b/scripts/quip2html.py index 19d293c..434852e 100755 --- a/scripts/quip2html.py +++ b/scripts/quip2html.py @@ -1,4 +1,4 @@ -#!/usr/bin/env python +#!/usr/bin/env python3 # -*- coding: utf-8 -*- # Copyright (C) 2017 The Qt Company Ltd. # Contact: http://www.qt.io/licensing/ @@ -10,9 +10,6 @@ Adapted from the python project's similar code for PEPs. """ -from __future__ import absolute_import, with_statement -from __future__ import print_function - __docformat__ = 'reStructuredText' import os, sys, subprocess @@ -167,6 +164,11 @@ class QuipReader(standalone.Reader): standalone.Reader.__init__(self, parser, '') class QuipWriter(html4css1.Writer): + def __init__(self, stem): + # For gen-quip-0000 we want quip-0000; otherwise, use the stem as is: + self.__stem = stem[4:] if stem.startswith('gen-') else stem + super().__init__() + # Assumed to be run from the build directory cwd_file = os.path.join(os.getcwd(), 'dummy') script_dir = os.path.dirname(__file__) @@ -205,10 +207,7 @@ class QuipWriter(html4css1.Writer): header = self.document[index] self.quipnum = header[0][1].astext() subs['quip'] = self.quipnum - try: - subs['quipnum'] = '%04i' % int(self.quipnum) - except ValueError: - subs['quipnum'] = self.quipnum + subs['urlstem'] = self.__stem self.title = header[1][1].astext() subs['title'] = 'QUIP %s | %s' % (self.quipnum, self.title) subs['body'] = ''.join(self.body_pre_docinfo + self.docinfo + self.body) @@ -247,9 +246,11 @@ def main(filename, source, output, stderr): reader=QuipReader(), parser_name='restructuredtext', writer_name='html4css1', - writer=QuipWriter(), + writer=QuipWriter(os.path.splitext(git.base)[0]), # Allow Docutils traceback if there's an exception: - settings_overrides={'traceback': True, 'halt_level': 2})) + settings_overrides={'traceback': True, 'halt_level': 2, + # output.write needs a string: + 'output_encoding': 'unicode'})) except DataError as what: stderr.write('\n'.join(what.args) + '\nin %s\n' % filename) return 1 @@ -257,10 +258,13 @@ def main(filename, source, output, stderr): return 0 if __name__ == '__main__': + sys.stdin.reconfigure(encoding='utf-8') + sys.stdout.reconfigure(encoding='utf-8') + sys.stderr.reconfigure(encoding='utf-8') if len(sys.argv) < 2 or sys.argv[1] == '-': here = os.path.split(sys.argv[0])[0] sys.exit(main(os.path.join(here, 'gen-quip-0000.py'), sys.stdin, sys.stdout, sys.stderr)) else: - with open(sys.argv[1]) as fd: + with open(sys.argv[1], encoding='utf-8') as fd: sys.exit(main(sys.argv[1], fd, sys.stdout, sys.stderr)) diff --git a/scripts/setup.mk b/scripts/setup.mk deleted file mode 100644 index 74d088e..0000000 --- a/scripts/setup.mk +++ /dev/null @@ -1,21 +0,0 @@ -# Make-file for quips.pro to delegate to as: -# make SRC=$$PWD setup -default: setup -WEB = $(SRC)/planetqt/website - -html: - mkdir -p html - -WEBDIRS = images -$(WEBDIRS:%=html/%): html/%: html - [ -d $@ ] || ln -sf $(WEB)/images $(@D) - -WEBFILES = favicon.ico \ - online.css style.css \ - main.js extras.js modernizr.custom.84855.js \ - cookie_small.png cookiebar-x.png list_arrow.png theqtcompany.png -$(WEBFILES:%=html/%): html/%: html - [ -f $@ ] || ln -sf $(WEB)/$(@F) $(@D) - -setup: $(WEBFILES:%=html/%) $(WEBDIRS:%=html/%) - touch html/.ready diff --git a/scripts/template.diff b/scripts/template.diff index 0902e11..dd96a75 100644 --- a/scripts/template.diff +++ b/scripts/template.diff @@ -1,6 +1,6 @@ ---- planetqt/template.qt 2017-04-21 16:11:06.542439585 +0200 -+++ scripts/template.html 2017-04-25 17:50:11.806838515 +0200 -@@ -9,8 +9,8 @@ +--- planetqt/template.qt 2022-10-03 14:44:25.447587715 +0200 ++++ scripts/template.html 2022-10-21 11:08:02.685280289 +0200 +@@ -9,14 +9,15 @@ <meta charset="UTF-8" /> <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no" /> @@ -11,7 +11,15 @@ <link rel="shortcut icon" href="favicon.ico" /> <link href='http://fonts.googleapis.com/css?family=Open+Sans:700,300,400' rel='stylesheet' type='text/css'> <link rel="stylesheet" type="text/css" href="online.css" /> -@@ -82,33 +82,14 @@ + <link rel="stylesheet" type="text/css" href="style.css" /> ++ <!-- Can remove this style hack once QTWEBSITE-1071 is fixed in planetqt's master --> ++ <style type="text/css"> em { font-style: italic; } strong { font-weight: bold; } </style> + +- <script type="text/javascript" src="http://d3hp9ud7yvwzy0.cloudfront.net/wp-content/themes/oneqt/js/combo.js.gzip"></script> + <script type="text/javascript" src="main.js"></script> + <script type="text/javascript" src="extras.js"></script> + <script type="text/javascript" src='modernizr.custom.84855.js'></script> +@@ -82,32 +83,14 @@ </div> <div class="content"> <div class="wrapper"> @@ -34,40 +42,42 @@ - <h3>Join us</h3> - <ul class="icon-links"> - <li class="qtproject-twitter"><a href="http://twitter.com/qtproject">@qtproject</a></li> -- <li class="qtproject-gplus"><a href="https://plus.google.com/104580575722059274792">Qt Project</a></li> - <li class="qt-meetup"><a href="http://www.meetup.com/QtEverywhere/">Qt Meetups</a></li> - </ul> - <h3>Contributing</h3> -- <p>All who blog in English about Qt can either add their complete RSS feed or a feed based on a specific category or tag for those blogging about multiple topics. All you need to do is clone the <a href="https://codereview.qt-project.org/#admin,project,www/planetqt,info">Planet Qt repository</a>, add your feed's address, and put your change up for <a href="http://wiki.qt.io/Code_Reviews">review</a>.</p> +- <p>All who blog in English about Qt can either add their complete RSS feed or a feed based on a specific category or tag for those blogging about multiple topics. All you need to do is clone the <a href="https://code.qt.io/cgit/www/planetqt.git/">Planet Qt repository</a>, add your feed's address, and put your change up for <a href="http://wiki.qt.io/Code_Reviews">review</a>.</p> - <h3>Subscriptions</h3> - __feedlist__ - </aside> -+ <h1>%(title)s</h1> -+ <ul> -+ <li><a href="./">QUIP Index</a></li> -+ <li><a href="quip-%(quipnum)s.html">QUIP %(quip)s</a></li> -+ </ul> -+<div class="context document"> ++ <h1>%(title)s</h1> ++ <ul> ++ <li><a href="./">QUIP Index</a></li> ++ <li><a href="%(urlstem)s.html">QUIP %(quip)s</a></li> ++ </ul> ++ <div class="context document"> +%(body)s -+</div> ++ </div> </div> </div> <div id="footer"> -@@ -174,7 +155,7 @@ +@@ -173,10 +156,7 @@ <a href="http://www.qt.io/about-us/" target="_blank" class="theqtcompany"></a> <div class="footer-social clearfix"> <div class="facebook"> - <iframe scrolling="no" frameborder="0" allowTransparency="true" src="//www.facebook.com/plugins/like.php?href=https%3A%2F%2Fwww.facebook.com%2Fqtbydigia&width&layout=button_count&action=like&show_faces=true&share=false&height=21" style="border:none;overflow:hidden;height:21px;"></iframe> +- </div> +- <div class="twitter"> +- <iframe id="twitter-widget-0" scrolling="no" frameborder="0" allowtransparency="true" src="//platform.twitter.com/widgets/follow_button.33b190ea0cba008796487b65df7f6d8e.en.html#_=1414403615717&id=twitter-widget-0&lang=en&screen_name=qtproject&show_count=true&show_screen_name=false&size=m" class="twitter-follow-button twitter-follow-button" title="Twitter Follow Button" data-twttr-rendered="true" style="width: 160px; height: 20px;"></iframe> + <iframe scrolling="no" frameborder="0" allowTransparency="true" src="//www.facebook.com/plugins/like.php?href=https%%3A%%2F%%2Fwww.facebook.com%%2Fqtbydigia&width&layout=button_count&action=like&show_faces=true&share=false&height=21" style="border:none;overflow:hidden;height:21px;"></iframe> </div> - <div class="twitter"> - <iframe id="twitter-widget-0" scrolling="no" frameborder="0" allowtransparency="true" src="//platform.twitter.com/widgets/follow_button.33b190ea0cba008796487b65df7f6d8e.en.html#_=1414403615717&id=twitter-widget-0&lang=en&screen_name=qtproject&show_count=true&show_screen_name=false&size=m" class="twitter-follow-button twitter-follow-button" title="Twitter Follow Button" data-twttr-rendered="true" style="width: 160px; height: 20px;"></iframe> -@@ -186,7 +167,7 @@ + </div> + </div> +@@ -185,7 +165,7 @@ <div class="container clearfix no_discs"> <ul id="menu-footer-submenu" class="right clearfix"><li class="menu-item"><a href="http://www.qtworldsummit.com">Qt World Summit</a></li> <li class="menu-item"><a title="Sign into your account." href="https://account.qt.io/login">Sign In</a></li> - <li class="menu-item"><a href="mailto:feedback@theqtcompany.com?Subject=Feedback%20about%20www.qt.io%20site">Feedback</a></li> -+ <li class="menu-item"><a href="mailto:feedback@theqtcompany.com?Subject=Feedback%%20about%%20www.qt.io%%20site">Feedback</a></li> - <li class="menu-item"><a href="http://www.qt.io/about-us">© 2015 The Qt Company</a></li> ++ <li class="menu-item"><a href="mailto:feedback@theqtcompany.com?Subject=Feedback%%20about%%20QUIPs on qt.io%%20site">Feedback</a></li> + <li class="menu-item"><a href="http://www.qt.io/about-us">© 2019 The Qt Company</a></li> </ul> </div> diff --git a/template.rst b/template.rst index 7d5f5b8..f7c1b8c 100644 --- a/template.rst +++ b/template.rst @@ -1,7 +1,6 @@ QUIP: Title: -Author: Comma-Separated List, - With Continuation Lines +Author: Comma-Separated List, With Continuation Lines Status: { Active | Superseded | Withdrawn } Type: { Implementation | Informational | Process } [Qt-Version:] @@ -17,6 +16,7 @@ Title Introductory paragraph, motivation. Use reStructuredText_ mark-up. +Run it through the checker_ to see how it'll look. Various sections ---------------- @@ -30,3 +30,5 @@ References https://code.qt.io/cgit/meta/quips.git/tree/quip-0001.rst .. _reStructuredText: http://docutils.sourceforge.net/rst.html + +.. _checker: http://rst.ninjs.org/ diff --git a/templates/simple_template.html b/templates/simple_template.html new file mode 100644 index 0000000..9b92838 --- /dev/null +++ b/templates/simple_template.html @@ -0,0 +1,27 @@ +<!DOCTYPE html> +<html lang="en"> + +<head> + <meta charset="UTF-8" /> + <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=yes" /> + + <title>%(title)s</title> + %(stylesheet)s + <link rel="shortcut icon" href="favicon.ico" /> +</head> +<body> +<div class="content"> + <div class="wrapper"> + <h1>%(title)s</h1> + <ul> + <li><a href="./">QUIP Index</a></li> + <li><a href="%(urlstem)s.html">QUIP %(quip)s</a></li> + </ul> + <div class="context document"> + %(body)s + </div> + </div> +</div> + +</body> +</html> |