Patch Detail
get:
Show a patch.
patch:
Update a patch.
put:
Update a patch.
GET /api/1.1/patches/2221054/?format=api
{ "id": 2221054, "url": "http://patchwork.ozlabs.org/api/1.1/patches/2221054/?format=api", "web_url": "http://patchwork.ozlabs.org/project/qemu-devel/patch/20260408045531.3006678-4-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-4-jsnow@redhat.com>", "date": "2026-04-08T04:55:24", "name": "[v2,03/10] qapi: add \"Details:\" disambiguation marker", "commit_ref": null, "pull_url": null, "state": "new", "archived": false, "hash": "7ca86fd71ae21ef15e7e6cc7a8c2b6cef05c1f03", "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-4-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/2221054/comments/", "check": "pending", "checks": "http://patchwork.ozlabs.org/api/patches/2221054/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=ClYvlLXz;\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 (unknown [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 4frX134DhGz1xv0\n\tfor <incoming@patchwork.ozlabs.org>; Thu, 09 Apr 2026 04:39:51 +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 1wAXoZ-00070X-Cb; Wed, 08 Apr 2026 14:39:47 -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 1wAXoX-0006lM-OS\n for qemu-devel@nongnu.org; Wed, 08 Apr 2026 14:39:45 -0400", "from us-smtp-delivery-124.mimecast.com ([170.10.129.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 1wAKxe-0005Uw-Jx\n for qemu-devel@nongnu.org; Wed, 08 Apr 2026 00:56:20 -0400", "from mx-prod-mc-08.mail-002.prod.us-west-2.aws.redhat.com\n (ec2-35-165-154-97.us-west-2.compute.amazonaws.com [35.165.154.97]) by\n relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3,\n cipher=TLS_AES_256_GCM_SHA384) id us-mta-31-j8ceCinXPCSEENH141qwYA-1; Wed,\n 08 Apr 2026 00:56:13 -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-08.mail-002.prod.us-west-2.aws.redhat.com (Postfix) with ESMTPS\n id C9529180034F; Wed, 8 Apr 2026 04:56:10 +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 6EF3319560A6; Wed, 8 Apr 2026 04:56:01 +0000 (UTC)" ], "DKIM-Signature": "v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com;\n s=mimecast20190719; t=1775624178;\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=gjEgL/Yg7IG4CWwCmU+agYoD289+Mk5M4ZdIeYzk0UM=;\n b=ClYvlLXzs7s+kUSiLt89ld1JQe0WJ32zpIf6fR/rUilc266pKn7ebZABa//99P6ZknvqSC\n FFqH+QBi2XEF5Fjge4thOWzlg8y9znZR4Oic1TukXBZZjZZK6YnnImiLdT09MUoI/8KZRO\n tBASYKjoBlvS6qJ02DDU3i6rTqNIUmc=", "X-MC-Unique": "j8ceCinXPCSEENH141qwYA-1", "X-Mimecast-MFC-AGG-ID": "j8ceCinXPCSEENH141qwYA_1775624171", "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 03/10] qapi: add \"Details:\" disambiguation marker", "Date": "Wed, 8 Apr 2026 00:55:24 -0400", "Message-ID": "<20260408045531.3006678-4-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.129.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_H4=0.001, RCVD_IN_MSPIKE_WL=0.001,\n RCVD_IN_VALIDITY_RPBL_BLOCKED=0.001, RCVD_IN_VALIDITY_SAFE_BLOCKED=0.001,\n SPF_HELO_PASS=-0.001,\n SPF_PASS=-0.001 autolearn=unavailable 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": "When a documentation block consists only of plaintext, there is nothing\nto semantically differentiate the \"intro\" from the \"details\"\nsection. For the purposes of the inliner, the intro section of\ndocumentation inlined into another documentation block will be omitted,\nwhich may lead to unintentional omissions of details in the rendered\noutput.\n\nWhen the delineation between \"intro\" and \"details\" is not clear because\nthere is no intervening description/tagged sections, the parser assumes\nthe entire text section is an \"intro\" section. This may not always be\nsemantically true, so this patch clarifies certain sections explicitly\nas \"details\" sections by using an empty \"Details:\" marker.\n\nReplace existing uses of \"TODO:\" hacks to achieve this effect with the\ncanonical marker.\n\nSigned-off-by: John Snow <jsnow@redhat.com>\n\n---\n\n[Review note: all *.ir files are completely unchanged before and after\nthis patch. --js]\n\nSigned-off-by: John Snow <jsnow@redhat.com>\n---\n docs/devel/qapi-code-gen.rst | 18 ++++++++++++++++++\n qapi/machine.json | 2 +-\n qapi/migration.json | 4 ++--\n qapi/net.json | 2 +-\n qapi/yank.json | 2 +-\n scripts/qapi/parser.py | 8 ++++++++\n 6 files changed, 31 insertions(+), 5 deletions(-)", "diff": "diff --git a/docs/devel/qapi-code-gen.rst b/docs/devel/qapi-code-gen.rst\nindex 06ab3547fdc..e575b54128e 100644\n--- a/docs/devel/qapi-code-gen.rst\n+++ b/docs/devel/qapi-code-gen.rst\n@@ -1048,6 +1048,24 @@ definition.\n QMP). In other sections, the text is formatted, and rST markup can be\n used.\n \n+In cases where documentation consists of several paragraphs of text with\n+no intervening sections to delineate them, it may become necessary to\n+explicitly declare the start of the details section by using a\n+\"Details:\" marker. For example::\n+\n+ ##\n+ # @foobar\n+ #\n+ # foobar is an example definition.\n+ #\n+ # Details:\n+ #\n+ # Since there are no other sections in this documentation, the above\n+ # \"Details:\" marker is required to mark this and subsequent paragraphs\n+ # as the \"Details\" section. Any automatically generated documentation\n+ # sections will be inserted above this point instead of below.\n+ ##\n+\n QMP Examples can be added by using the ``.. qmp-example::`` directive.\n In its simplest form, this can be used to contain a single QMP code\n block which accepts standard JSON syntax with additional server\ndiff --git a/qapi/machine.json b/qapi/machine.json\nindex 685e4e29b87..bc2279b2526 100644\n--- a/qapi/machine.json\n+++ b/qapi/machine.json\n@@ -1259,7 +1259,7 @@\n # Return the amount of initially allocated and present hotpluggable\n # (if enabled) memory in bytes.\n #\n-# TODO: This line is a hack to separate the example from the body\n+# Details:\n #\n # .. qmp-example::\n #\ndiff --git a/qapi/migration.json b/qapi/migration.json\nindex 7134d4ce47e..2142f74e3c7 100644\n--- a/qapi/migration.json\n+++ b/qapi/migration.json\n@@ -1633,7 +1633,7 @@\n #\n # Query replication status while the vm is running.\n #\n-# TODO: This line is a hack to separate the example from the body\n+# Details:\n #\n # .. qmp-example::\n #\n@@ -1687,7 +1687,7 @@\n #\n # Query COLO status while the vm is running.\n #\n-# TODO: This line is a hack to separate the example from the body\n+# Details:\n #\n # .. qmp-example::\n #\ndiff --git a/qapi/net.json b/qapi/net.json\nindex 118bd349651..c011d6dc1a9 100644\n--- a/qapi/net.json\n+++ b/qapi/net.json\n@@ -1070,7 +1070,7 @@\n # switches. This can be useful when network bonds fail-over the\n # active slave.\n #\n-# TODO: This line is a hack to separate the example from the body\n+# Details:\n #\n # .. qmp-example::\n #\ndiff --git a/qapi/yank.json b/qapi/yank.json\nindex f3cd5c15d60..2854a8a9d2a 100644\n--- a/qapi/yank.json\n+++ b/qapi/yank.json\n@@ -104,7 +104,7 @@\n #\n # Query yank instances. See `YankInstance` for more information.\n #\n-# TODO: This line is a hack to separate the example from the body\n+# Details:\n #\n # .. qmp-example::\n #\ndiff --git a/scripts/qapi/parser.py b/scripts/qapi/parser.py\nindex 8a21e9e8b56..1d52d80e672 100644\n--- a/scripts/qapi/parser.py\n+++ b/scripts/qapi/parser.py\n@@ -590,6 +590,14 @@ def _tag_check(this: Union['QAPIDoc.Kind', str]) -> None:\n raise QAPIParseError(\n self, 'feature descriptions expected')\n have_tagged = True\n+ elif line == 'Details:':\n+ _tag_check(\"Details\")\n+ self.accept(False)\n+ line = self.get_doc_line()\n+ while line == '':\n+ self.accept(False)\n+ line = self.get_doc_line()\n+ have_tagged = True\n elif match := self._match_at_name_colon(line):\n # description\n if have_tagged:\n", "prefixes": [ "v2", "03/10" ] }