From patchwork Thu Feb 29 03:07:41 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Lukas Bulwahn X-Patchwork-Id: 208190 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7301:2097:b0:108:e6aa:91d0 with SMTP id gs23csp146586dyb; Wed, 28 Feb 2024 19:08:55 -0800 (PST) X-Forwarded-Encrypted: i=3; AJvYcCUcIUsILW9lVJpLhjYTIDqW5bpbV7hpPJwcVt9OpwxMf/odY/ArZL5jq4Zn3XCROEHTIQDoK3G1lEl1CvgcUOEhZ2j/8w== X-Google-Smtp-Source: AGHT+IEVGWmYDMA5anjfZqfLz4PaIR+zahmbK6wjZdf67sgUnsCoc7NL7JPvp4bDNxFzmzzRt/2n X-Received: by 2002:a92:c264:0:b0:365:a65f:8008 with SMTP id h4-20020a92c264000000b00365a65f8008mr1344776ild.18.1709176135442; Wed, 28 Feb 2024 19:08:55 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1709176135; cv=pass; d=google.com; s=arc-20160816; b=Dg32w+vWntVAulcvCm9ZmFcS2sCAQxAjcM+j1itNqocuKq7tDorSP+LCCC8LOGW1J2 4udxbM1JOdnpj4MnslXPrJLq/PuIo9MyQVssib3ZoEYVs339Tc4HpT5r95KLM9Tcmakm ETe7TF2Nlx0M73UuFjd9WmTb27PVB6icFD0AVi9DU18LuBmrLiKbUUrTzv/d0x9PJTSA N3BxgM/wjr07dVZj3CxZuH6aIirFQknYJIWTiGoqzhkcQ0x3IyYGFqi1i9EuXZNPpTby yLcy2L+q/ZtIRrdUe27j/7evGcLi8dUSt2RKPnL9abrjPWDFNO/hJ9V/RL72Ld18a289 fHSw== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=8c5OMLwHZp9ihvaBqRpMZQP7KGXLqJLRTQO586mYvq4=; fh=oxUlxRGNsA5YbdIJBszI4bSEOrS3c4e/x9JytRkBj/U=; b=LMjyQIJ2Fkl6tnidlPZzB1vsSWQzZzsv5nDl4EeE3hJykkFFW65nMHKDTbSLn8Kv70 2TUA/prPLcLJAXCz+WGF1hsxgDUJOkRx9HHQ8AShebLd6rhxDgLNSfFmxYvm5YoQ4Mcm 5XOP+AyQcLq9XSoHpjO35GgES1a2j4r5Qq3+6xKFD5xZNMRKcPUpLkY6o3vHuF9mXjzz FJhHs9zqVhR+Uaq+onqx3mO1FWja0pJIysHkikJl+U31L6T801c00LBkaaKRv8Kh/kzr byW7jArRtLdnQR3rK//9+EgkU9GEHNDrF1cy5LoPhUTcIPNO97tCg+0YqX6JwxReoqks 8oQw==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=NTgGUJ7o; arc=pass (i=1 spf=pass spfdomain=gmail.com dkim=pass dkdomain=gmail.com dmarc=pass fromdomain=gmail.com); spf=pass (google.com: domain of linux-kernel+bounces-86080-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-86080-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org. [139.178.88.99]) by mx.google.com with ESMTPS id t13-20020a6564cd000000b005dbd0d798a7si443579pgv.558.2024.02.28.19.08.55 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Feb 2024 19:08:55 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-86080-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=NTgGUJ7o; arc=pass (i=1 spf=pass spfdomain=gmail.com dkim=pass dkdomain=gmail.com dmarc=pass fromdomain=gmail.com); spf=pass (google.com: domain of linux-kernel+bounces-86080-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-86080-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sv.mirrors.kernel.org (Postfix) with ESMTPS id 3B9E3284596 for ; Thu, 29 Feb 2024 03:08:55 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id E9E8C383A3; Thu, 29 Feb 2024 03:08:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="NTgGUJ7o" Received: from mail-wr1-f43.google.com (mail-wr1-f43.google.com [209.85.221.43]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 5C73433CF1; Thu, 29 Feb 2024 03:08:05 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.221.43 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709176087; cv=none; b=n3Mpd+x8FanCQxBdK5MjD0l7tX48/Im2q04D65armqPbytaLkU3V2AxnKcRSOXzKLrp9nR1/bSxdqxt+vAD/Hg9kMGBm8k5w0k60YxXmkOY1gtPPEnaHQsamfOXIHEyfKTdHfchI12hcLawsOBChTxu3vLSyPeMJ7F5uib69RII= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709176087; c=relaxed/simple; bh=QcAUxCzYfP6556O97wVS0e4m5bGKL6XPEjLA4wHJ8cU=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Qxpc+64r1HqFvE8tDmDqOTF4NKA0AO0oE0dfq1G/Hqu5HN9nX3k6XuJo0kc4vSjIk3p8CP/Ws/BbuOPmlniF/tGfL+3hRo+iJdCjrF21f2Ld6h80jPmEwummwuA/hzcX53IUBEHUduKYu5t2Jav8OV6YfVIUlgRDcWCzWlMtV8c= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=NTgGUJ7o; arc=none smtp.client-ip=209.85.221.43 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Received: by mail-wr1-f43.google.com with SMTP id ffacd0b85a97d-33d36736d4eso300556f8f.1; Wed, 28 Feb 2024 19:08:05 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1709176084; x=1709780884; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=8c5OMLwHZp9ihvaBqRpMZQP7KGXLqJLRTQO586mYvq4=; b=NTgGUJ7odCxM5Xr2mSQV7pskjiNExMr+Jl2CVKsSO4p1gqhZYXxDSRSJ1IP39hfDJP 0WucxIs2PBSLmsNM+IIwXQiM2iSraEyDNSRf04f3rU3+cZmNQ/j/fSMd5fX7Y65dw3ut qkJtgG2MC2o+FZTR43ZYmP8TU7inmHd+FWNz2SZYW3R5ZKfc9V503+XJWmH7rISD8w5g P8pz8lJ9c20WKX3nMHSvAijjx/+3uKc2HUVry0wKymFvOh1It/F6ydd4FvtNRPlHq5mG diDwkJvZfsLdgq5cPFPvOg2JwykBt53Q3F5iz1HwsStH2SOlH8NSj1XdwPgAihxUPBCo 868A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709176084; x=1709780884; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=8c5OMLwHZp9ihvaBqRpMZQP7KGXLqJLRTQO586mYvq4=; b=qQ4Y7DJvF+JYFh/iU6EZrwgrbYPHoaj8o+9GlyffoVXeWZhVHI7ouc7KK1/VgPtx86 gZgvwLEnkH2g+Wsm6n1srs+4qVRLsRLDSxeUsa0I4DUSNQWVFGFRDcg8TU+jibz9nmih 9QKBoR42kiaNDNKjETc0nVuczXVfDzmUPTTRfm+mev9pKVuPXmemUNu4vrRLwMl3pOTY /ShXNmXoZhnVcDjCz5EPVI6avseJtHz/5XXnIVx6Xhr8g1mWUpDHIEXsh02PE/4BIZcb fEVSmLvuWC3e+3QisoSm7QWZVRqInz+RgNmT/Y3rEt4Lu50Ot2XaLoL3mULa9IvaVbKU JJVQ== X-Forwarded-Encrypted: i=1; AJvYcCU/7ZnFwFTq68DEktQpfqgUrC6EUJHTYmnqWDiQVyGYwe2+ZRtxEBs/l0CRsNvxTa4nU7rUictwpsp8wQBML09tW6LcxtzuTMDt7R3VPbXpM3AvFpe5lR6hJPR53v7C2MM5PZAL1rhZSMt9+Ey/2LF1k/eGchRQAlzhF9pC1h5GLqit X-Gm-Message-State: AOJu0YwfP0ojPswWduGGnB9fEin7nIXmYIA/yIIuUxPzNMf11XLPRO4s mPV1TWnoQ2YuwNSQXSQFZTx+pISmolFVxCv5tVePLSpb444VrX8g X-Received: by 2002:adf:e0cc:0:b0:33d:6bd3:9e28 with SMTP id m12-20020adfe0cc000000b0033d6bd39e28mr380462wri.70.1709176083361; Wed, 28 Feb 2024 19:08:03 -0800 (PST) Received: from lola.. ([2a02:810d:7e40:14b0:d371:e319:5dd0:9b35]) by smtp.gmail.com with ESMTPSA id u1-20020adfb201000000b0033b1c321070sm417512wra.31.2024.02.28.19.08.02 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Feb 2024 19:08:03 -0800 (PST) From: Lukas Bulwahn To: Jonathan Corbet , Jani Nikula , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org Cc: kernel-janitors@vger.kernel.org, linux-kernel@vger.kernel.org, Lukas Bulwahn Subject: [PATCH v2 1/3] docs: submit-checklist: structure by category Date: Thu, 29 Feb 2024 04:07:41 +0100 Message-ID: <20240229030743.9125-2-lukas.bulwahn@gmail.com> X-Mailer: git-send-email 2.43.2 In-Reply-To: <20240229030743.9125-1-lukas.bulwahn@gmail.com> References: <20240229030743.9125-1-lukas.bulwahn@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1792200662635418148 X-GMAIL-MSGID: 1792201075438454011 While going through the submit checklist, the list order seemed rather random, probably just by historical coincidences of always adding yet the next point someone thought of at the end of the list. Structure and order them by the category of such activity, reviewing, documenting, checking with tools, building and testing. As the diff of the reordering is large: Review code now includes previous points 1, 5 and 22. Review Kconfig includes previous 6, 7 and 8. Documenting includes previous 11, 15, 16, 17, 18 and 23. Checking with tools includes previous 5, 9 and 10. Building includes previous 2, 3, 20 and 24. Testing includes previous 12, 13, 14, 19 and 21. Previous point 4 (compile for ppc64) was merged into point 3 (build for many architectures), as it was just a further note to cross-compiling. Previous point 5 was split into one in review and one in checking to have every previous point in the right category. Point 11 was shortened, as building documentation is mentioned already in Build your code, 1d. A note that was presented visually much too aggressive in the HTML view was turned into a simple "Note that..." sentence in the enumeration. The recommendation to test with the -mm patchset (previous 21, now testing, point 5) was updated to the current state of affairs to test with a recent tag of linux-next. Note that the previous first point still remains the first list even after reordering. Randy confirmed that it was important to Stephen Rothwell to keep 'include what you use' to be the first in the list. While at it, replace the reference to the obsolete CONFIG_DEBUG_SLAB with CONFIG_SLUB_DEBUG. Reviewed-by: Randy Dunlap Tested-by: Randy Dunlap Signed-off-by: Lukas Bulwahn --- Documentation/process/submit-checklist.rst | 157 +++++++++++---------- 1 file changed, 84 insertions(+), 73 deletions(-) diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index b1bc2d37bd0a..7d8dba942fe8 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -11,110 +11,121 @@ These are all above and beyond the documentation that is provided in and elsewhere regarding submitting Linux kernel patches. +*Review your code:* + 1) If you use a facility then #include the file that defines/declares that facility. Don't depend on other header files pulling in ones that you use. -2) Builds cleanly: +2) Check your patch for general style as detailed in + :ref:`Documentation/process/coding-style.rst `. - a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and - ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. +3) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a + comment in the source code that explains the logic of what they are doing + and why. - b) Passes ``allnoconfig``, ``allmodconfig`` - c) Builds successfully when using ``O=builddir`` +*Review Kconfig changes:* - d) Any Documentation/ changes build successfully without new warnings/errors. - Use ``make htmldocs`` or ``make pdfdocs`` to check the build and - fix any issues. +1) Any new or modified ``CONFIG`` options do not muck up the config menu and + default to off unless they meet the exception criteria documented in + ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. -3) Builds on multiple CPU architectures by using local cross-compile tools - or some other build farm. +2) All new ``Kconfig`` options have help text. -4) ppc64 is a good architecture for cross-compilation checking because it - tends to use ``unsigned long`` for 64-bit quantities. +3) Has been carefully reviewed with respect to relevant ``Kconfig`` + combinations. This is very hard to get right with testing---brainpower + pays off here. -5) Check your patch for general style as detailed in - :ref:`Documentation/process/coding-style.rst `. - Check for trivial violations with the patch style checker prior to - submission (``scripts/checkpatch.pl``). - You should be able to justify all violations that remain in - your patch. +*Provide documentation:* -6) Any new or modified ``CONFIG`` options do not muck up the config menu and - default to off unless they meet the exception criteria documented in - ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. +1) Include :ref:`kernel-doc ` to document global kernel APIs. + (Not required for static functions, but OK there also.) -7) All new ``Kconfig`` options have help text. +2) All new ``/proc`` entries are documented under ``Documentation/`` -8) Has been carefully reviewed with respect to relevant ``Kconfig`` - combinations. This is very hard to get right with testing -- brainpower - pays off here. +3) All new kernel boot parameters are documented in + ``Documentation/admin-guide/kernel-parameters.rst``. + +4) All new module parameters are documented with ``MODULE_PARM_DESC()`` -9) Check cleanly with sparse. +5) All new userspace interfaces are documented in ``Documentation/ABI/``. + See ``Documentation/ABI/README`` for more information. + Patches that change userspace interfaces should be CCed to + linux-api@vger.kernel.org. -10) Use ``make checkstack`` and fix any problems that it finds. +6) If any ioctl's are added by the patch, then also update + ``Documentation/userspace-api/ioctl/ioctl-number.rst``. - .. note:: - ``checkstack`` does not point out problems explicitly, - but any one function that uses more than 512 bytes on the stack is a - candidate for change. +*Check your code with tools:* -11) Include :ref:`kernel-doc ` to document global kernel APIs. - (Not required for static functions, but OK there also.) Use - ``make htmldocs`` or ``make pdfdocs`` to check the - :ref:`kernel-doc ` and fix any issues. +1) Check for trivial violations with the patch style checker prior to + submission (``scripts/checkpatch.pl``). + You should be able to justify all violations that remain in + your patch. -12) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, - ``CONFIG_DEBUG_SLAB``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, - ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, - ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all - simultaneously enabled. +2) Check cleanly with sparse. -13) Has been build- and runtime tested with and without ``CONFIG_SMP`` and - ``CONFIG_PREEMPT.`` +3) Use ``make checkstack`` and fix any problems that it finds. + Note that ``checkstack`` does not point out problems explicitly, + but any one function that uses more than 512 bytes on the stack is a + candidate for change. -14) All codepaths have been exercised with all lockdep features enabled. -15) All new ``/proc`` entries are documented under ``Documentation/`` +*Build your code:* + +1) Builds cleanly: + + a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and + ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. + + b) Passes ``allnoconfig``, ``allmodconfig`` + + c) Builds successfully when using ``O=builddir`` + + d) Any Documentation/ changes build successfully without new warnings/errors. + Use ``make htmldocs`` or ``make pdfdocs`` to check the build and + fix any issues. -16) All new kernel boot parameters are documented in - ``Documentation/admin-guide/kernel-parameters.rst``. +2) Builds on multiple CPU architectures by using local cross-compile tools + or some other build farm. Note that ppc64 is a good architecture for + cross-compilation checking because it tends to use ``unsigned long`` for + 64-bit quantities. -17) All new module parameters are documented with ``MODULE_PARM_DESC()`` +3) Newly-added code has been compiled with ``gcc -W`` (use + ``make KCFLAGS=-W``). This will generate lots of noise, but is good + for finding bugs like "warning: comparison between signed and unsigned". -18) All new userspace interfaces are documented in ``Documentation/ABI/``. - See ``Documentation/ABI/README`` for more information. - Patches that change userspace interfaces should be CCed to - linux-api@vger.kernel.org. +4) If your modified source code depends on or uses any of the kernel + APIs or features that are related to the following ``Kconfig`` symbols, + then test multiple builds with the related ``Kconfig`` symbols disabled + and/or ``=m`` (if that option is available) [not all of these at the + same time, just various/random combinations of them]: -19) Has been checked with injection of at least slab and page-allocation - failures. See ``Documentation/fault-injection/``. + ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, + ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, + ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). - If the new code is substantial, addition of subsystem-specific fault - injection might be appropriate. -20) Newly-added code has been compiled with ``gcc -W`` (use - ``make KCFLAGS=-W``). This will generate lots of noise, but is good - for finding bugs like "warning: comparison between signed and unsigned". +*Test your code:* -21) Tested after it has been merged into the -mm patchset to make sure - that it still works with all of the other queued patches and various - changes in the VM, VFS, and other subsystems. +1) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, + ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, + ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, + ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all + simultaneously enabled. -22) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a - comment in the source code that explains the logic of what they are doing - and why. +2) Has been build- and runtime tested with and without ``CONFIG_SMP`` and + ``CONFIG_PREEMPT.`` -23) If any ioctl's are added by the patch, then also update - ``Documentation/userspace-api/ioctl/ioctl-number.rst``. +3) All codepaths have been exercised with all lockdep features enabled. -24) If your modified source code depends on or uses any of the kernel - APIs or features that are related to the following ``Kconfig`` symbols, - then test multiple builds with the related ``Kconfig`` symbols disabled - and/or ``=m`` (if that option is available) [not all of these at the - same time, just various/random combinations of them]: +4) Has been checked with injection of at least slab and page-allocation + failures. See ``Documentation/fault-injection/``. + If the new code is substantial, addition of subsystem-specific fault + injection might be appropriate. - ``CONFIG_SMP``, ``CONFIG_SYSFS``, ``CONFIG_PROC_FS``, ``CONFIG_INPUT``, ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, - ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). +5) Tested with the most recent tag of linux-next to make sure that it still + works with all of the other queued patches and various changes in the VM, + VFS, and other subsystems. From patchwork Thu Feb 29 03:07:42 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Lukas Bulwahn X-Patchwork-Id: 208191 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7301:2097:b0:108:e6aa:91d0 with SMTP id gs23csp146650dyb; Wed, 28 Feb 2024 19:09:03 -0800 (PST) X-Forwarded-Encrypted: i=3; AJvYcCUMlocXmf0Lg442owmFi/rSiB4TvrzMWwySHWSfcgiMgrmxpUxUFOufZSO1++Un2RK2X4KoNs8iEPOiEPZzgclPZby3rw== X-Google-Smtp-Source: AGHT+IGFReM89Wuc9h+6YmSP58aviXRTNWjWcRzab7g9oY4hcDa0kkX1IOF8YhEwSiHm9jyhQVQQ X-Received: by 2002:a05:6214:14ee:b0:68f:3a65:e01a with SMTP id k14-20020a05621414ee00b0068f3a65e01amr1035369qvw.11.1709176143417; Wed, 28 Feb 2024 19:09:03 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1709176143; cv=pass; d=google.com; s=arc-20160816; b=uea5WdX1yB1hpRE/Cr/zZj4GLXJpFwgVJGRoiv1sq7Z3B1zDwb5X+POywX2TSMXc+u Aei3aSkhU4W1yyOFCqZOx2YTV9UYFhs3uWsck8aKaDIWDePlb96hwxYCtvQllJkosda8 tjZ3QdgKDbZ1lpe6ERO3ZDrPoshcIKXBwZeFEQTBx/4LVTDoRSINZdzDyqWo+g18T7IL 0o5pWcuWr6JVTQBPeTle6TkYEbJuFJQIozI+Xou+ntRK/onAkTghi/taJjPK5AclR9u+ 70CflP5Wx858ol11UISluFeTfnRwW7GdBaSEa2jqBPUBg7cmKjK6B9CI+kuYzYr3MxgZ UrJw== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=hS0LEDmNn2urbgs7Rk9ueAuKUUBQ5p1mwcNjc8V2Cu8=; fh=f+91erKFJyEE6gUKBwlJu7qGPrLwSX6HUx2nf3yVjPQ=; b=kErJFO+wbxWu+QiTD677iYEib2iEPrzDaVQeX1iYWTkvmmMWLASOIQ7Qz/cH4PEaIP az0CXUon5PB3E4bN5/TV3nPjTtAwoQtphx8701MBtFEl3LuKBBg4KKRvx9863n7Lc7Qn IZsR3nfOfIqPL/FNcqfdm506Z2qm91WQ3Ll8XnUcn+fhq2Efbc0oaMT4QPjjxKe+FyFg 1AH6nmLDGx9xy16roeamV9h1INs6huU7zSdJ70RxuScR1VnRsY561XJhWhecLvvVew5X 1E4sV3Dho+p08myFmVAmlSIyOhnmgUBUW8UaMJvdPbS2ZNaPLnj960HnEoqVHDJJ9Ws0 23dQ==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=dZYC4tSo; arc=pass (i=1 spf=pass spfdomain=gmail.com dkim=pass dkdomain=gmail.com dmarc=pass fromdomain=gmail.com); spf=pass (google.com: domain of linux-kernel+bounces-86081-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) smtp.mailfrom="linux-kernel+bounces-86081-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from ny.mirrors.kernel.org (ny.mirrors.kernel.org. [147.75.199.223]) by mx.google.com with ESMTPS id oj9-20020a056214440900b0068f5fce66e3si501870qvb.1.2024.02.28.19.09.03 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Feb 2024 19:09:03 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-86081-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) client-ip=147.75.199.223; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=dZYC4tSo; arc=pass (i=1 spf=pass spfdomain=gmail.com dkim=pass dkdomain=gmail.com dmarc=pass fromdomain=gmail.com); spf=pass (google.com: domain of linux-kernel+bounces-86081-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.199.223 as permitted sender) smtp.mailfrom="linux-kernel+bounces-86081-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ny.mirrors.kernel.org (Postfix) with ESMTPS id 2B7781C2181F for ; Thu, 29 Feb 2024 03:09:03 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 310CF38DF1; Thu, 29 Feb 2024 03:08:13 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="dZYC4tSo" Received: from mail-wm1-f44.google.com (mail-wm1-f44.google.com [209.85.128.44]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id 56608364A4; Thu, 29 Feb 2024 03:08:08 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.44 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709176090; cv=none; b=PlKCc4HEFnOIw4PtADmcBydw69FC0UTlq/po7p/POtNt18YSnyjg1+42je14mVNR6BYoz1modi6hCgGe8/vfbueTcksRUliCt/NEspF+ls+G7GdTZR/pODeYgQTUIwGTF5pXKnnAZzE14whUMVXrqUsUNGX1K0Hj64jyvMIQE9Q= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709176090; c=relaxed/simple; bh=ht433vMi1TOdghnnmW8mJ+u5PWJCJikJmYtSS+v9v1Q=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=i3EZRuHwR4pnMIJefuu676JBJOFUGkA+u1iw6kWYW5b3jfFt1wijKdUgcj6EezmT5xF+Bn0rFXP1uFIeFoU4G2w/XfXDINorS8N72fu61KO4NJgcytirf6OfquUTT0Wg3KWwRuFVCWN4k0Igg8zu3JBedSIYCVcTXTk5Fl/KW5o= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=dZYC4tSo; arc=none smtp.client-ip=209.85.128.44 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Received: by mail-wm1-f44.google.com with SMTP id 5b1f17b1804b1-412b5a9916eso3266735e9.1; Wed, 28 Feb 2024 19:08:08 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1709176087; x=1709780887; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=hS0LEDmNn2urbgs7Rk9ueAuKUUBQ5p1mwcNjc8V2Cu8=; b=dZYC4tSomKhh9Uq9/Ge5z8ryXKUJZl9g/vTh/eerSgVnfa44INrWTS/IN0DW5vW4Ct tSoXv/oI/5zTd3CEkXlqZF5nMRz/Y+kmH4NidZvRzyBLIJB46rWEGhtZ04JyuYkcKMe4 Qovht4PGYqcqiRmV7h8x0aZyJ3CxBQtebA+z/XNI3mdEolfMsxVvPAMJ7ya3Ql9Mn8JT oeYVsEyWiTkUnQi5Fetsd4boM2Gr73pVYxLVaNXAB3jRGYs08lSwWaxk1JG61xEdmfKj vXpEmxA0cAntkwENjj00YTom7NdlLTBfOh8wC3Lw2UGIc4UVPvs86xPD0O1Jr0yn6lDO WrNQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709176087; x=1709780887; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=hS0LEDmNn2urbgs7Rk9ueAuKUUBQ5p1mwcNjc8V2Cu8=; b=BUDxlcf5OmXZfrYa8dLyL9lERKrSERiXqw8Zq6j9kV71Pd/cFzGYqLzRTZsnsfe6M5 LfExciPcvafZtyPcLjYvXPJPWuN9wc6R0uFkiPLGzcoII+4J/yXS1X9HmhsOB0M9bWVR VONyO0JR+3EIQzXUBo0Oa1PuobNXUUlwFd4/l+kR4bnbo7s3IwfqYNtjbrBULrpq8VHU 68WRE/J3aN1kudFAfVmVAplOmhg7ih+VxM6rCqpHDYd5W0fmObe8qAo+2jXsPPa9NEcL 7uiOKWGYiUj27VMPPnj3yjoIY1V85TBgf0FJSWfw7wZ8QQ8pP915mFVuoG4zzaL9QPsV kaiQ== X-Forwarded-Encrypted: i=1; AJvYcCVeTwPPkocY3W7W7TYZDN9Sa0RZOsP4xPZ0iuRH0f5I49MpKQHiT30EpKOPAwMoMknAfvuPjcXSRyasuOHMqCSKsmsnsoPw4lzhwdrhUkQqmd3e5nVrhItqpH3KEu3eXVSk62c7G9tXAZH/vpzunnWDNrHRPyCtDOEtNnT+z+xeOGyW X-Gm-Message-State: AOJu0YzhxfztFG4yPLwoBVofPAFriNWxwssZxTVR1dtuSUseLkv+aOoJ /0DkkhPZw84NgWUBTVQ/pBcSiyvYQK9EoGZesHNTbE/8EExn+rtv X-Received: by 2002:adf:f684:0:b0:33d:f473:89d0 with SMTP id v4-20020adff684000000b0033df47389d0mr406556wrp.62.1709176086660; Wed, 28 Feb 2024 19:08:06 -0800 (PST) Received: from lola.. ([2a02:810d:7e40:14b0:d371:e319:5dd0:9b35]) by smtp.gmail.com with ESMTPSA id u1-20020adfb201000000b0033b1c321070sm417512wra.31.2024.02.28.19.08.06 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Feb 2024 19:08:06 -0800 (PST) From: Lukas Bulwahn To: Jonathan Corbet , Jani Nikula , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org Cc: kernel-janitors@vger.kernel.org, linux-kernel@vger.kernel.org, Lukas Bulwahn Subject: [PATCH v2 2/3] docs: submit-checklist: use subheadings Date: Thu, 29 Feb 2024 04:07:42 +0100 Message-ID: <20240229030743.9125-3-lukas.bulwahn@gmail.com> X-Mailer: git-send-email 2.43.2 In-Reply-To: <20240229030743.9125-1-lukas.bulwahn@gmail.com> References: <20240229030743.9125-1-lukas.bulwahn@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1792201083734036932 X-GMAIL-MSGID: 1792201083734036932 During review (see Link), Jani Nikula suggested to use proper subheadings instead of using italics to indicate the different new top-level categories in the checklist. Further the top heading should follow the common scheme. Use subheadings. Adjust to common heading adornment. Link: https://lore.kernel.org/linux-doc/87o7c3mlwb.fsf@intel.com/ Signed-off-by: Lukas Bulwahn Reviewed-by: Randy Dunlap --- Documentation/process/submit-checklist.rst | 26 ++++++++++++---------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index 7d8dba942fe8..e531dd504b6c 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -1,7 +1,8 @@ .. _submitchecklist: +======================================= Linux Kernel patch submission checklist -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +======================================= Here are some basic things that developers should do if they want to see their kernel patch submissions accepted more quickly. @@ -10,8 +11,8 @@ These are all above and beyond the documentation that is provided in :ref:`Documentation/process/submitting-patches.rst ` and elsewhere regarding submitting Linux kernel patches. - -*Review your code:* +Review your code +================ 1) If you use a facility then #include the file that defines/declares that facility. Don't depend on other header files pulling in ones @@ -24,8 +25,8 @@ and elsewhere regarding submitting Linux kernel patches. comment in the source code that explains the logic of what they are doing and why. - -*Review Kconfig changes:* +Review Kconfig changes +====================== 1) Any new or modified ``CONFIG`` options do not muck up the config menu and default to off unless they meet the exception criteria documented in @@ -37,7 +38,8 @@ and elsewhere regarding submitting Linux kernel patches. combinations. This is very hard to get right with testing---brainpower pays off here. -*Provide documentation:* +Provide documentation +===================== 1) Include :ref:`kernel-doc ` to document global kernel APIs. (Not required for static functions, but OK there also.) @@ -57,8 +59,8 @@ and elsewhere regarding submitting Linux kernel patches. 6) If any ioctl's are added by the patch, then also update ``Documentation/userspace-api/ioctl/ioctl-number.rst``. - -*Check your code with tools:* +Check your code with tools +========================== 1) Check for trivial violations with the patch style checker prior to submission (``scripts/checkpatch.pl``). @@ -72,8 +74,8 @@ and elsewhere regarding submitting Linux kernel patches. but any one function that uses more than 512 bytes on the stack is a candidate for change. - -*Build your code:* +Build your code +=============== 1) Builds cleanly: @@ -107,8 +109,8 @@ and elsewhere regarding submitting Linux kernel patches. ``CONFIG_PCI``, ``CONFIG_BLOCK``, ``CONFIG_PM``, ``CONFIG_MAGIC_SYSRQ``, ``CONFIG_NET``, ``CONFIG_INET=n`` (but latter with ``CONFIG_NET=y``). - -*Test your code:* +Test your code +============== 1) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, From patchwork Thu Feb 29 03:07:43 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Lukas Bulwahn X-Patchwork-Id: 208192 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7301:2097:b0:108:e6aa:91d0 with SMTP id gs23csp146755dyb; Wed, 28 Feb 2024 19:09:24 -0800 (PST) X-Forwarded-Encrypted: i=3; AJvYcCU75TDkDTiOIU34dTt5oN8DxFCRNex8T+PTnuD4K4t/zE+NtmnHRob+XkdKdJSsNreWoxG0+uGndhPhM/23dthFfvPI0Q== X-Google-Smtp-Source: AGHT+IFvF1v4G7YokRur70kgjWW7BFk+8/7fIgiPAZZM/z5ZzTwa0T822LyzsKxXwnuCRLiTDAgK X-Received: by 2002:a05:6870:420f:b0:21f:dc6e:e4dc with SMTP id u15-20020a056870420f00b0021fdc6ee4dcmr832078oac.5.1709176164555; Wed, 28 Feb 2024 19:09:24 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1709176164; cv=pass; d=google.com; s=arc-20160816; b=mLzdjXVWS/QdkgbM/PGTgCu5wvVN7y4XJNABAgbS5LGRTJqlGJrxv4L3L850jOzT88 21iO5C5yp7hPsCf+MksOBnGktddIdWmVT7lUhmQOz/DAPFjQT9kz2NHM1FSkgpZYX51c WOFsEtegvB+JcIzS8UEcMdyAQDTr63UXndppuWoNhXUeNjY37NWm/x0smRulCGqrK2aO TyTO+oOp/eJVETJG/EaeDipN0cXgqF34voNKpdRlCxFJLU+kTH8rWmL7T+sjDMdFlAxJ ZVHjRt6QbHkY6jCv9CRAKcTr0b/hsYhiXtkwnjjt9HHhViMDuF6qoN+7qyuOSF3z7MJZ m64w== ARC-Message-Signature: i=2; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=content-transfer-encoding:mime-version:list-unsubscribe :list-subscribe:list-id:precedence:references:in-reply-to:message-id :date:subject:cc:to:from:dkim-signature; bh=w9qU0UCk8gIG4bcK7mpR2nYnDILfB/g3vlRutl/cxbE=; fh=oQUTfqqpt6/OgRqpbisVjSJakI2gX+TeQNxLhqS9zl4=; b=GK72zI4Lux2rizwaDKZQXGnEYvkh1si0WH3HefcIA+b486QhheAvGdnHUyO9NzO2zb fThQHDouxePmqw26cvYfFUALSU5uNytXicAoeYJz0Jly2GoH2b3VmAKScu7Lk679NTBm BsrjqnwxWzE7p8Qq2CK+KePousRTe2KayVQ10njvTugmJgbpQS2k2sDAis6mAHNX+LOV MgDuDSUA0aEGI2vMPFkR02GOpA5EXwVY1/iNZL2X7Cat6S+3F1aRw2fNMPLDCTTI1Mep Vx2X5RoVeNtcLO5bWlHjqN47JeeG1pqirShmOgNpMZoVkaf1amZG/WWFIq9WV2PLxIZl eRUw==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=Q78TqmbO; arc=pass (i=1 spf=pass spfdomain=gmail.com dkim=pass dkdomain=gmail.com dmarc=pass fromdomain=gmail.com); spf=pass (google.com: domain of linux-kernel+bounces-86082-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-86082-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from sv.mirrors.kernel.org (sv.mirrors.kernel.org. [139.178.88.99]) by mx.google.com with ESMTPS id k5-20020a6568c5000000b005dc82d9ff85si455052pgt.599.2024.02.28.19.09.24 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Feb 2024 19:09:24 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-86082-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) client-ip=139.178.88.99; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=Q78TqmbO; arc=pass (i=1 spf=pass spfdomain=gmail.com dkim=pass dkdomain=gmail.com dmarc=pass fromdomain=gmail.com); spf=pass (google.com: domain of linux-kernel+bounces-86082-ouuuleilei=gmail.com@vger.kernel.org designates 139.178.88.99 as permitted sender) smtp.mailfrom="linux-kernel+bounces-86082-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from smtp.subspace.kernel.org (wormhole.subspace.kernel.org [52.25.139.140]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by sv.mirrors.kernel.org (Postfix) with ESMTPS id 22B152862F7 for ; Thu, 29 Feb 2024 03:09:24 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 49E87374C2; Thu, 29 Feb 2024 03:08:17 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Q78TqmbO" Received: from mail-wm1-f46.google.com (mail-wm1-f46.google.com [209.85.128.46]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by smtp.subspace.kernel.org (Postfix) with ESMTPS id ED2A3383A6; Thu, 29 Feb 2024 03:08:11 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.128.46 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709176093; cv=none; b=siaOKr5FmKb8yGyLOoek4FgxE3xIuBt9vh0khR++bteAP3dHfAc5DrDbSMB5JKld4QwWmvh/OvW4EkMwq/lJuTNuVbjWAoqb0zqW3lqTQhc2dDPjoPGmQQ8Xvc8PwLuCKxRnOTRrw4CKSksdWgBA2c+ouhB1v7muHP2U3jLv2UI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709176093; c=relaxed/simple; bh=h8Fxr5NUFoLpC353g62oc1r7IAnypkRWof+Jd0EtDyM=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=KuHMLKHS4/+6f3N10eXvj3tbS1RJoua26rKiOglO5TizT5QO2LwW+W2aaxixdoXXu/HLID+BpnUHA+oWkTLiw9nUTRpNww5g+Wg5J85h6+/ugvjiuqKP6FB9fHU8cKB71DzFgr6m9Aa5jXdUv94AwE9nYDyICtsGNtXQ4RUDT6I= ARC-Authentication-Results: i=1; smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com; spf=pass smtp.mailfrom=gmail.com; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b=Q78TqmbO; arc=none smtp.client-ip=209.85.128.46 Authentication-Results: smtp.subspace.kernel.org; dmarc=pass (p=none dis=none) header.from=gmail.com Authentication-Results: smtp.subspace.kernel.org; spf=pass smtp.mailfrom=gmail.com Received: by mail-wm1-f46.google.com with SMTP id 5b1f17b1804b1-412ae15b06fso2847175e9.1; Wed, 28 Feb 2024 19:08:11 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1709176090; x=1709780890; darn=vger.kernel.org; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:from:to:cc:subject:date :message-id:reply-to; bh=w9qU0UCk8gIG4bcK7mpR2nYnDILfB/g3vlRutl/cxbE=; b=Q78TqmbO127GL4gf2doJH0Oq+1t6AegEI6QYqXUkSEmKzCbn3zvexsB/tur/bWT1tf N/oKXYyfVzHg0mviNWoAt9jXPpP+oihSS73jns/HQEgYvUhfc4jHRtyrxvW/VCQ+jRDv 2po8MFXumtl9bN4Sbc+0ST0ABCBsKY3u0n1715iB/qysUCSL1RKWJt/lY8vW5fvxnU+p cqdVBIG6X5qq/xTVI9wLz0L3MZ8ve9Q8mLACzTJbvGUFPGCakaqqmvHh2zFgFCw2Cb8X s7aq5J/Xc+D/CONYnjE7K0lfHCgtrmmWpvIfaSnxnyKntfw3lzCQIJI9WVyXtVjFZQD7 AGXw== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709176090; x=1709780890; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-message-state:from:to:cc :subject:date:message-id:reply-to; bh=w9qU0UCk8gIG4bcK7mpR2nYnDILfB/g3vlRutl/cxbE=; b=SRa2rbdwOWv/uxoosCpPrNRLkpAZfntOP4DKYu7g/fPbUtH2Ss+YCoaD2342z/4RLS 8Ha3U8skNWnah4KiZt3afFNWVZSjx/mhVinBTCmX90dEFYRoMZqH1MubMr++la9kfjGH dTohEYHPc8wYSjcWkeTnWzqJ9l9QGCPzXtmQNcooau9Dmf3tl2/cjpknXvqo8axBtaq0 45evEpQ2CeVJASoRunTtl1iB1/RlGxZTvHUruXgF6YCPPS1eRX0G74TYboyRx9PrKUfw 51K+nwgYBgIzLjQ78QejyqO5D8XXe0M1ZSicVBwwFcA+LjmP3cxMM0cf0E8FCWE/7BDc 8YPg== X-Forwarded-Encrypted: i=1; AJvYcCWQGmCEmrAOFJlBb45c5DSLi5Hwd+Fkgj/xQx7E6CKXoB8TkiQMeNR9r0Jp41z0YN5+9R5jYof/HrnxM2CqhOURnlrzjTJs9PFyxe0Ey4wQeVQCO76iSp2S3AeO44XcPxyjqVdJEOl7FECjG+pr/+feK72Jx6+A1772ZT2pWFZ4SwQG X-Gm-Message-State: AOJu0YxiQt1nxzLKz0Jk2f+SdvtJG2nE8l0GWZIrRlNZQwtnVgUnl5Vz lw6hTlTBMafeNNDjXBXOzNxicj5YaAU7UOhaWDH8Jya5nZl/slsNJ43MHrBlScA= X-Received: by 2002:a5d:58fb:0:b0:33d:9c56:37f4 with SMTP id f27-20020a5d58fb000000b0033d9c5637f4mr443986wrd.46.1709176090184; Wed, 28 Feb 2024 19:08:10 -0800 (PST) Received: from lola.. ([2a02:810d:7e40:14b0:d371:e319:5dd0:9b35]) by smtp.gmail.com with ESMTPSA id u1-20020adfb201000000b0033b1c321070sm417512wra.31.2024.02.28.19.08.09 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 28 Feb 2024 19:08:10 -0800 (PST) From: Lukas Bulwahn To: Jonathan Corbet , Jani Nikula , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org Cc: kernel-janitors@vger.kernel.org, linux-kernel@vger.kernel.org, Lukas Bulwahn Subject: [PATCH v2 3/3] docs: submit-checklist: change to autonumbered lists Date: Thu, 29 Feb 2024 04:07:43 +0100 Message-ID: <20240229030743.9125-4-lukas.bulwahn@gmail.com> X-Mailer: git-send-email 2.43.2 In-Reply-To: <20240229030743.9125-1-lukas.bulwahn@gmail.com> References: <20240229030743.9125-1-lukas.bulwahn@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 X-getmail-retrieved-from-mailbox: INBOX X-GMAIL-THRID: 1792201105830407083 X-GMAIL-MSGID: 1792201105830407083 During review (see Link), Jani Nikula suggested to use autonumbered lists instead of manually-maintained bullet numbering. Turn all lists into autonumbered lists. Link: https://lore.kernel.org/linux-doc/87o7c3mlwb.fsf@intel.com/ Signed-off-by: Lukas Bulwahn Reviewed-by: Randy Dunlap Reviewed-by: Akira Yokosawa --- Documentation/process/submit-checklist.rst | 48 +++++++++++----------- 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/Documentation/process/submit-checklist.rst b/Documentation/process/submit-checklist.rst index e531dd504b6c..c984b747a755 100644 --- a/Documentation/process/submit-checklist.rst +++ b/Documentation/process/submit-checklist.rst @@ -14,62 +14,62 @@ and elsewhere regarding submitting Linux kernel patches. Review your code ================ -1) If you use a facility then #include the file that defines/declares +#. If you use a facility then #include the file that defines/declares that facility. Don't depend on other header files pulling in ones that you use. -2) Check your patch for general style as detailed in +#. Check your patch for general style as detailed in :ref:`Documentation/process/coding-style.rst `. -3) All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a +#. All memory barriers {e.g., ``barrier()``, ``rmb()``, ``wmb()``} need a comment in the source code that explains the logic of what they are doing and why. Review Kconfig changes ====================== -1) Any new or modified ``CONFIG`` options do not muck up the config menu and +#. Any new or modified ``CONFIG`` options do not muck up the config menu and default to off unless they meet the exception criteria documented in ``Documentation/kbuild/kconfig-language.rst`` Menu attributes: default value. -2) All new ``Kconfig`` options have help text. +#. All new ``Kconfig`` options have help text. -3) Has been carefully reviewed with respect to relevant ``Kconfig`` +#. Has been carefully reviewed with respect to relevant ``Kconfig`` combinations. This is very hard to get right with testing---brainpower pays off here. Provide documentation ===================== -1) Include :ref:`kernel-doc ` to document global kernel APIs. +#. Include :ref:`kernel-doc ` to document global kernel APIs. (Not required for static functions, but OK there also.) -2) All new ``/proc`` entries are documented under ``Documentation/`` +#. All new ``/proc`` entries are documented under ``Documentation/`` -3) All new kernel boot parameters are documented in +#. All new kernel boot parameters are documented in ``Documentation/admin-guide/kernel-parameters.rst``. -4) All new module parameters are documented with ``MODULE_PARM_DESC()`` +#. All new module parameters are documented with ``MODULE_PARM_DESC()`` -5) All new userspace interfaces are documented in ``Documentation/ABI/``. +#. All new userspace interfaces are documented in ``Documentation/ABI/``. See ``Documentation/ABI/README`` for more information. Patches that change userspace interfaces should be CCed to linux-api@vger.kernel.org. -6) If any ioctl's are added by the patch, then also update +#. If any ioctl's are added by the patch, then also update ``Documentation/userspace-api/ioctl/ioctl-number.rst``. Check your code with tools ========================== -1) Check for trivial violations with the patch style checker prior to +#. Check for trivial violations with the patch style checker prior to submission (``scripts/checkpatch.pl``). You should be able to justify all violations that remain in your patch. -2) Check cleanly with sparse. +#. Check cleanly with sparse. -3) Use ``make checkstack`` and fix any problems that it finds. +#. Use ``make checkstack`` and fix any problems that it finds. Note that ``checkstack`` does not point out problems explicitly, but any one function that uses more than 512 bytes on the stack is a candidate for change. @@ -77,7 +77,7 @@ Check your code with tools Build your code =============== -1) Builds cleanly: +#. Builds cleanly: a) with applicable or modified ``CONFIG`` options ``=y``, ``=m``, and ``=n``. No ``gcc`` warnings/errors, no linker warnings/errors. @@ -90,16 +90,16 @@ Build your code Use ``make htmldocs`` or ``make pdfdocs`` to check the build and fix any issues. -2) Builds on multiple CPU architectures by using local cross-compile tools +#. Builds on multiple CPU architectures by using local cross-compile tools or some other build farm. Note that ppc64 is a good architecture for cross-compilation checking because it tends to use ``unsigned long`` for 64-bit quantities. -3) Newly-added code has been compiled with ``gcc -W`` (use +#. Newly-added code has been compiled with ``gcc -W`` (use ``make KCFLAGS=-W``). This will generate lots of noise, but is good for finding bugs like "warning: comparison between signed and unsigned". -4) If your modified source code depends on or uses any of the kernel +#. If your modified source code depends on or uses any of the kernel APIs or features that are related to the following ``Kconfig`` symbols, then test multiple builds with the related ``Kconfig`` symbols disabled and/or ``=m`` (if that option is available) [not all of these at the @@ -112,22 +112,22 @@ Build your code Test your code ============== -1) Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, +#. Has been tested with ``CONFIG_PREEMPT``, ``CONFIG_DEBUG_PREEMPT``, ``CONFIG_SLUB_DEBUG``, ``CONFIG_DEBUG_PAGEALLOC``, ``CONFIG_DEBUG_MUTEXES``, ``CONFIG_DEBUG_SPINLOCK``, ``CONFIG_DEBUG_ATOMIC_SLEEP``, ``CONFIG_PROVE_RCU`` and ``CONFIG_DEBUG_OBJECTS_RCU_HEAD`` all simultaneously enabled. -2) Has been build- and runtime tested with and without ``CONFIG_SMP`` and +#. Has been build- and runtime tested with and without ``CONFIG_SMP`` and ``CONFIG_PREEMPT.`` -3) All codepaths have been exercised with all lockdep features enabled. +#. All codepaths have been exercised with all lockdep features enabled. -4) Has been checked with injection of at least slab and page-allocation +#. Has been checked with injection of at least slab and page-allocation failures. See ``Documentation/fault-injection/``. If the new code is substantial, addition of subsystem-specific fault injection might be appropriate. -5) Tested with the most recent tag of linux-next to make sure that it still +#. Tested with the most recent tag of linux-next to make sure that it still works with all of the other queued patches and various changes in the VM, VFS, and other subsystems.