Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/1.1/patches/2221215/?format=api
{ "id": 2221215, "url": "http://patchwork.ozlabs.org/api/1.1/patches/2221215/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/patch/20260408045531.3006678-2-jsnow@redhat.com/", "project": { "id": 14, "url": "http://patchwork.ozlabs.org/api/1.1/projects/14/?format=api", "name": "QEMU Development", "link_name": "qemu-devel", "list_id": "qemu-devel.nongnu.org", "list_email": "qemu-devel@nongnu.org", "web_url": "", "scm_url": "", "webscm_url": "" }, "msgid": "<20260408045531.3006678-2-jsnow@redhat.com>", "date": "2026-04-08T04:55:22", "name": "[v2,01/10] qapi: differentiate \"intro\" and \"details\" sections", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "edd2aa10f8ddd298c6b394c99b6f95ef9455cbe2", "submitter": { "id": 64343, "url": "http://patchwork.ozlabs.org/api/1.1/people/64343/?format=api", "name": "John Snow", "email": "jsnow@redhat.com" }, "delegate": null, "mbox": "http://patchwork.ozlabs.org/project/qemu-devel/patch/20260408045531.3006678-2-jsnow@redhat.com/mbox/", "series": [ { "id": 499174, "url": "http://patchwork.ozlabs.org/api/1.1/series/499174/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/list/?series=499174", "date": "2026-04-08T04:55:23", "name": "qapi: enforce section ordering", "version": 2, "mbox": "http://patchwork.ozlabs.org/series/499174/mbox/" } ], "comments": "http://patchwork.ozlabs.org/api/patches/2221215/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/2221215/checks/", "tags": {}, "headers": { "Return-Path": "<qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org>", "X-Original-To": "incoming@patchwork.ozlabs.org", "Delivered-To": "patchwork-incoming@legolas.ozlabs.org", "Authentication-Results": [ "legolas.ozlabs.org;\n\tdkim=pass (1024-bit key;\n unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256\n header.s=mimecast20190719 header.b=imHieWAQ;\n\tdkim-atps=neutral", "legolas.ozlabs.org;\n spf=pass (sender SPF authorized) smtp.mailfrom=nongnu.org\n (client-ip=209.51.188.17; helo=lists.gnu.org;\n envelope-from=qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org;\n receiver=patchwork.ozlabs.org)" ], "Received": [ "from lists.gnu.org (lists1p.gnu.org [209.51.188.17])\n\t(using TLSv1.2 with cipher ECDHE-ECDSA-AES256-GCM-SHA384 (256/256 bits))\n\t(No client certificate requested)\n\tby legolas.ozlabs.org (Postfix) with ESMTPS id 4frYdD33Fjz1yD3\n\tfor <incoming@patchwork.ozlabs.org>; Thu, 09 Apr 2026 05:52:48 +1000 (AEST)", "from localhost ([::1] helo=lists1p.gnu.org)\n\tby lists.gnu.org with esmtp (Exim 4.90_1)\n\t(envelope-from <qemu-devel-bounces@nongnu.org>)\n\tid 1wAYWD-0006RB-Ss; Wed, 08 Apr 2026 15:24:54 -0400", "from eggs.gnu.org ([2001:470:142:3::10])\n by lists1p.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from <jsnow@redhat.com>) id 1wAY6p-0007Ci-W5\n for qemu-devel@nongnu.org; Wed, 08 Apr 2026 14:58:40 -0400", "from us-smtp-delivery-124.mimecast.com ([170.10.133.124])\n by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256)\n (Exim 4.90_1) (envelope-from <jsnow@redhat.com>) id 1wAKxL-0005Tc-Ov\n for qemu-devel@nongnu.org; Wed, 08 Apr 2026 00:56:01 -0400", "from mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com\n (ec2-54-186-198-63.us-west-2.compute.amazonaws.com [54.186.198.63]) by\n relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3,\n cipher=TLS_AES_256_GCM_SHA384) id us-mta-52-UGhLi6MbMiaOvoMH2xKW4w-1; Wed,\n 08 Apr 2026 00:55:55 -0400", "from mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com\n (mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com [10.30.177.12])\n (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)\n key-exchange X25519 server-signature RSA-PSS (2048 bits) server-digest\n SHA256)\n (No client certificate requested)\n by mx-prod-mc-05.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS\n id ABED21956080; Wed, 8 Apr 2026 04:55:52 +0000 (UTC)", "from jsnow-thinkpadp16vgen1.westford.csb (unknown [10.22.88.7])\n by mx-prod-int-03.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTP\n id 6D3791955F2B; Wed, 8 Apr 2026 04:55:43 +0000 (UTC)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1775624159;\n h=from:from:reply-to:subject:subject:date:date:message-id:message-id:\n to:to:cc:cc:mime-version:mime-version:\n content-transfer-encoding:content-transfer-encoding:\n in-reply-to:in-reply-to:references:references;\n bh=zQNiTfcBvXKXQ+Z+lV3PoOjT3444LniGV6uuOZJ1Zbs=;\n b=imHieWAQxhh9EbcJ5a+RmoaR8CkxoWRwaO9MKcqhwd+f63BUCZkc2jVcNsEzyVtb/CABRL\n Kf+5ZpDyNQZXksepPrPIzuinnbNFh+4PcAc9cRH1b7UdsPO0uk2ldfTWUsUSBDuNvTwENj\n N5+3+yWTy7pbUvLDOf7PcfxrS7CezQE=", "X-MC-Unique": "UGhLi6MbMiaOvoMH2xKW4w-1", "X-Mimecast-MFC-AGG-ID": "UGhLi6MbMiaOvoMH2xKW4w_1775624153", "From": "John Snow <jsnow@redhat.com>", "To": "qemu-devel@nongnu.org", "Cc": "Kashyap Chamarthy <kchamart@redhat.com>,\n Stefan Berger <stefanb@linux.vnet.ibm.com>,\n Mauro Carvalho Chehab <mchehab+huawei@kernel.org>,\n Michael Roth <michael.roth@amd.com>,\n =?utf-8?q?Philippe_Mathieu-Daud=C3=A9?= <philmd@linaro.org>,\n qemu-block@nongnu.org, Pierrick Bouvier <pierrick.bouvier@linaro.org>,\n Yanan Wang <wangyanan55@huawei.com>, Hanna Reitz <hreitz@redhat.com>,\n Peter Xu <peterx@redhat.com>, Igor Mammedov <imammedo@redhat.com>,\n \"Michael S. Tsirkin\" <mst@redhat.com>, Kevin Wolf <kwolf@redhat.com>,\n\t=?utf-8?q?Marc-Andr=C3=A9_Lureau?= <marcandre.lureau@redhat.com>,\n Stefano Garzarella <sgarzare@redhat.com>, =?utf-8?q?Daniel_P=2E_Berrang?=\n\t=?utf-8?q?=C3=A9?= <berrange@redhat.com>, Lukas Straub <lukasstraub2@web.de>,\n Jason Wang <jasowang@redhat.com>, Alex Williamson <alex@shazbot.org>,\n Paolo Bonzini <pbonzini@redhat.com>, Fabiano Rosas <farosas@suse.de>,\n Zhao Liu <zhao1.liu@intel.com>,\n Richard Henderson <richard.henderson@linaro.org>, =?utf-8?q?C=C3=A9dric_Le_?=\n\t=?utf-8?q?Goater?= <clg@redhat.com>, Stefan Hajnoczi <stefanha@redhat.com>,\n Peter Maydell <peter.maydell@linaro.org>, Eric Blake <eblake@redhat.com>,\n\t=?utf-8?q?Alex_Benn=C3=A9e?= <alex.bennee@linaro.org>,\n Kostiantyn Kostiuk <kkostiuk@redhat.com>, Jiri Pirko <jiri@resnulli.us>,\n Markus Armbruster <armbru@redhat.com>, John Snow <jsnow@redhat.com>,\n Ani Sinha <anisinha@redhat.com>,\n Marcel Apfelbaum <marcel.apfelbaum@gmail.com>", "Subject": "[PATCH v2 01/10] qapi: differentiate \"intro\" and \"details\" sections", "Date": "Wed, 8 Apr 2026 00:55:22 -0400", "Message-ID": "<20260408045531.3006678-2-jsnow@redhat.com>", "In-Reply-To": "<20260408045531.3006678-1-jsnow@redhat.com>", "References": "<20260408045531.3006678-1-jsnow@redhat.com>", "MIME-Version": "1.0", "Content-Transfer-Encoding": "8bit", "X-Scanned-By": "MIMEDefang 3.0 on 10.30.177.12", "Received-SPF": "pass client-ip=170.10.133.124; envelope-from=jsnow@redhat.com;\n helo=us-smtp-delivery-124.mimecast.com", "X-Spam_score_int": "-25", "X-Spam_score": "-2.6", "X-Spam_bar": "--", "X-Spam_report": "(-2.6 / 5.0 requ) BAYES_00=-1.9, DKIMWL_WL_HIGH=-0.54,\n DKIM_SIGNED=0.1, DKIM_VALID=-0.1, DKIM_VALID_AU=-0.1, DKIM_VALID_EF=-0.1,\n RCVD_IN_DNSWL_NONE=-0.0001, RCVD_IN_MSPIKE_H2=0.001,\n RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001,\n SPF_HELO_PASS=-0.001, SPF_PASS=-0.001 autolearn=ham autolearn_force=no", "X-Spam_action": "no action", "X-BeenThere": "qemu-devel@nongnu.org", "X-Mailman-Version": "2.1.29", "Precedence": "list", "List-Id": "qemu development <qemu-devel.nongnu.org>", "List-Unsubscribe": "<https://lists.nongnu.org/mailman/options/qemu-devel>,\n <mailto:qemu-devel-request@nongnu.org?subject=unsubscribe>", "List-Archive": "<https://lists.nongnu.org/archive/html/qemu-devel>", "List-Post": "<mailto:qemu-devel@nongnu.org>", "List-Help": "<mailto:qemu-devel-request@nongnu.org?subject=help>", "List-Subscribe": "<https://lists.nongnu.org/mailman/listinfo/qemu-devel>,\n <mailto:qemu-devel-request@nongnu.org?subject=subscribe>", "Errors-To": "qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org", "Sender": "qemu-devel-bounces+incoming=patchwork.ozlabs.org@nongnu.org" }, "content": "This patch begins distinguishing \"Plain\" sections as being either\n\"Intro\" or \"Details\" sections for the purpose of, in the forthcoming\ndocumentation inliner, knowing when/where/how to inline those\nsections. i.e. \"Intro\" sections will not be inlined, but \"Details\"\nsections will be. The intent is for \"Intro\" sections to describe\n(briefly) only the specific entity, but for details sections to describe\ninformation in greater detail that would be relevant to include in\ninlined documentation.\n\nThe Intro section is always the first section of any doc block. It may\nbe empty or any number of paragraphs. It is interrupted by any other\nnon-plaintext section, i.e.; Members, Features, Errors, Returns, Since,\nand TODO.\n\nThe details section, as of this patch, is any plaintext section after\nthe initial section. (It cannot appear immediately following the INTRO\nsection, because it would then simply be part of that intro section.)\n\nSigned-off-by: John Snow <jsnow@redhat.com>\n\n---\n\n[Review note: .ir files remain unchanged before and after this patch, it\nshould be completely inert with regards to the rendered output. --js]\n\nSigned-off-by: John Snow <jsnow@redhat.com>\n---\n docs/sphinx/qapidoc.py | 2 +-\n scripts/qapi/parser.py | 35 +++++++++++++++++++++++-----------\n tests/qapi-schema/doc-good.out | 8 ++++----\n 3 files changed, 29 insertions(+), 16 deletions(-)", "diff": "diff --git a/docs/sphinx/qapidoc.py b/docs/sphinx/qapidoc.py\nindex c2f09bac16c..e359836f110 100644\n--- a/docs/sphinx/qapidoc.py\n+++ b/docs/sphinx/qapidoc.py\n@@ -368,7 +368,7 @@ def visit_sections(self, ent: QAPISchemaDefinition) -> None:\n for i, section in enumerate(sections):\n section.text = self.reformat_arobase(section.text)\n \n- if section.kind == QAPIDoc.Kind.PLAIN:\n+ if section.kind.name in (\"INTRO\", \"DETAILS\"):\n self.visit_paragraph(section)\n elif section.kind == QAPIDoc.Kind.MEMBER:\n assert isinstance(section, QAPIDoc.ArgSection)\ndiff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py\nindex c3cf33904ef..da0ac32ad89 100644\n--- a/scripts/qapi/parser.py\n+++ b/scripts/qapi/parser.py\n@@ -544,7 +544,7 @@ def get_doc(self) -> 'QAPIDoc':\n doc = QAPIDoc(info, symbol)\n self.accept(False)\n line = self.get_doc_line()\n- no_more_args = False\n+ have_tagged = False\n \n while line is not None:\n # Blank lines\n@@ -573,10 +573,10 @@ def get_doc(self) -> 'QAPIDoc':\n if not doc.features:\n raise QAPIParseError(\n self, 'feature descriptions expected')\n- no_more_args = True\n+ have_tagged = True\n elif match := self._match_at_name_colon(line):\n # description\n- if no_more_args:\n+ if have_tagged:\n raise QAPIParseError(\n self,\n \"description of '@%s:' follows a section\"\n@@ -588,7 +588,7 @@ def get_doc(self) -> 'QAPIDoc':\n if text:\n doc.append_line(text)\n line = self.get_doc_indented(doc)\n- no_more_args = True\n+ have_tagged = True\n elif match := re.match(\n r'(Returns|Errors|Since|Notes?|Examples?|TODO)'\n r'(?!::): *',\n@@ -629,10 +629,14 @@ def get_doc(self) -> 'QAPIDoc':\n if text:\n doc.append_line(text)\n line = self.get_doc_indented(doc)\n- no_more_args = True\n+ have_tagged = True\n else:\n # plain paragraph\n- doc.ensure_untagged_section(self.info)\n+\n+ # Paragraphs before tagged sections are \"intro\" paragraphs.\n+ # Any appearing after are \"detail\" paragraphs.\n+ intro = not have_tagged\n+ doc.ensure_untagged_section(self.info, intro)\n doc.append_line(line)\n line = self.get_doc_paragraph(doc)\n else:\n@@ -674,13 +678,14 @@ class QAPIDoc:\n \"\"\"\n \n class Kind(enum.Enum):\n- PLAIN = 0\n+ INTRO = 0\n MEMBER = 1\n FEATURE = 2\n RETURNS = 3\n ERRORS = 4\n SINCE = 5\n TODO = 6\n+ DETAILS = 7\n \n @staticmethod\n def from_string(kind: str) -> 'QAPIDoc.Kind':\n@@ -730,7 +735,7 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None):\n self.symbol: Optional[str] = symbol\n # the sections in textual order\n self.all_sections: List[QAPIDoc.Section] = [\n- QAPIDoc.Section(info, QAPIDoc.Kind.PLAIN)\n+ QAPIDoc.Section(info, QAPIDoc.Kind.INTRO)\n ]\n # the body section\n self.body: Optional[QAPIDoc.Section] = self.all_sections[0]\n@@ -748,12 +753,20 @@ def __init__(self, info: QAPISourceInfo, symbol: Optional[str] = None):\n def end(self) -> None:\n for section in self.all_sections:\n section.text = section.text.strip('\\n')\n- if section.kind != QAPIDoc.Kind.PLAIN and section.text == '':\n+ if (\n+ section.kind not in (\n+ QAPIDoc.Kind.INTRO, QAPIDoc.Kind.DETAILS\n+ ) and section.text == ''\n+ ):\n raise QAPISemError(\n section.info, \"text required after '%s:'\" % section.kind)\n \n- def ensure_untagged_section(self, info: QAPISourceInfo) -> None:\n- kind = QAPIDoc.Kind.PLAIN\n+ def ensure_untagged_section(\n+ self,\n+ info: QAPISourceInfo,\n+ intro: bool = True,\n+ ) -> None:\n+ kind = QAPIDoc.Kind.INTRO if intro else QAPIDoc.Kind.DETAILS\n \n if self.all_sections and self.all_sections[-1].kind == kind:\n # extend current section\ndiff --git a/tests/qapi-schema/doc-good.out b/tests/qapi-schema/doc-good.out\nindex 04a55072646..04e29e8d50f 100644\n--- a/tests/qapi-schema/doc-good.out\n+++ b/tests/qapi-schema/doc-good.out\n@@ -116,7 +116,7 @@ The _one_ {and only}, description on the same line\n Also _one_ {and only}\n feature=enum-member-feat\n a member feature\n- section=Plain\n+ section=Details\n @two is undocumented\n doc symbol=Base\n body=\n@@ -175,7 +175,7 @@ description starts on the same line\n a feature\n feature=cmd-feat2\n another feature\n- section=Plain\n+ section=Details\n .. note:: @arg3 is undocumented\n section=Returns\n @Object\n@@ -183,7 +183,7 @@ another feature\n some\n section=Todo\n frobnicate\n- section=Plain\n+ section=Details\n .. admonition:: Notes\n \n - Lorem ipsum dolor sit amet\n@@ -216,7 +216,7 @@ If you're bored enough to read this, go see a video of boxed cats\n a feature\n feature=cmd-feat2\n another feature\n- section=Plain\n+ section=Details\n .. qmp-example::\n \n -> \"this example\"\n", "prefixes": [ "v2", "01/10" ] }