From patchwork Fri Mar 1 13:46:35 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Lukas Bulwahn X-Patchwork-Id: 208860 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7301:2097:b0:108:e6aa:91d0 with SMTP id gs23csp1086571dyb; Fri, 1 Mar 2024 05:47:26 -0800 (PST) X-Forwarded-Encrypted: i=3; AJvYcCUZ6HulNzh7GuU1M57uZXjEKqI3s3D9qzhFjaOfAVohJJoFRaR0+X0/CR0tChNm7S5fQc1rtnYou64rzPWXQBudFtRGhA== X-Google-Smtp-Source: AGHT+IEfVjJbxEuYL823kRf6t4ytCyvVEfK/NthU7Y++U2V1ss8JgStGTqtlPqBX4n9uBw2TQrw0 X-Received: by 2002:a05:6402:5c3:b0:565:7edf:41b0 with SMTP id n3-20020a05640205c300b005657edf41b0mr1356954edx.6.1709300846731; Fri, 01 Mar 2024 05:47:26 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1709300846; cv=pass; d=google.com; s=arc-20160816; b=qA3Kb0kxcHg9cSoAAEwKd4wCjCjZk8vCK8jloyC/wNtQD7OtRI2iFSff4gpaueJ9na vGf8m/wYKKXnUxPBCp2BgFhwCR241GjCmcDEHDtABL/pfie04uyUduf0H+bKOI84v7Pq LDdIacC4myVzXUs17osk0Wd/tcRhCd/GToTneSswQKX3p8MZSNebs+mGHbjE+S19wG6L RsYf3n+rzOnITKcPrxm+7ElqwHV7VI2cisCCFSzx88UO/mkuATO4v5sClzoVOu7hNMdv EZC6Yx5zK4CYdY40zgEMg8JXfGfhGs8SgO+HevkVDh9XCB+EhjFFPONYI1ruAkmAexNz zAOg== 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=umwFC7DE96xZZ1X/nt8K0ZM1RN381g70mq+QxdOjW8Y=; fh=/nmZxP5I/ATr7jmLPEkatU9Fy68kskMurTKTDpK7mX4=; b=hGKZYaPdHRNVBybtHofDKMioNzm2t3TgR+gHHCX2yJPJy2UeHYhqLhKQQzWcn/zn9G b5FDgAPoAY+VmgQM1tRWVty75neqKMci8Mjn1L409ZwJtIn52SDE1BwHtGMthyTR/ad2 /5ouiKWlwinizWQraaj18n3nf7dhXQ1UqB8SgB7cwqiC567ETPHnoYQjPpRAQvqAtaVK XHEol6lkcbEePtJAQwcXdoTjAcMIwNSrGSnw1TfLoP1lgx2NVdTwnl03QrAhUtNZzlX5 9S7M56EnflywI3QwzIRSmKuNZduKGFPpZNoLT8zLLEP3id7tEhaN7sJ4DBnHLzXQH6KP V7nw==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=ecGGc9Ds; 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-88512-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) smtp.mailfrom="linux-kernel+bounces-88512-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from am.mirrors.kernel.org (am.mirrors.kernel.org. [2604:1380:4601:e00::3]) by mx.google.com with ESMTPS id n20-20020aa7c694000000b00564409f2e72si1479170edq.673.2024.03.01.05.47.26 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 01 Mar 2024 05:47:26 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-88512-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) client-ip=2604:1380:4601:e00::3; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=ecGGc9Ds; 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-88512-ouuuleilei=gmail.com@vger.kernel.org designates 2604:1380:4601:e00::3 as permitted sender) smtp.mailfrom="linux-kernel+bounces-88512-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 am.mirrors.kernel.org (Postfix) with ESMTPS id 54BF81F24A74 for ; Fri, 1 Mar 2024 13:47:26 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id B68EA6F08A; Fri, 1 Mar 2024 13:46:55 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="ecGGc9Ds" Received: from mail-ed1-f49.google.com (mail-ed1-f49.google.com [209.85.208.49]) (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 6920A6EB5D; Fri, 1 Mar 2024 13:46:51 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709300813; cv=none; b=VtwOpzuqbeIf5Sf2XDPLH9cLspnvJ4yLNZFrTFUFas/+Z6BwqcisqcRdVgalXNq82z1P2zF/GBIrgW1Fse7qOYp231/5JGIKGbtpPC/kIyDs4H9x+Zvxjnm10A5lloliDpeZqGHBheAWHM62MNlC5svq4NY0AYN0wv5I7EFpQCY= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709300813; c=relaxed/simple; bh=5+tsegm35mr2mrlHcxRD4tBazE0gM93OVZb3DJC9fZ0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=kURZ2uWRyZrGxRchR1LU1gtcZNkn2eoZmNGtTZEI2HMho2e0K5+RYC/wRP1c9XgF1kSOnB7KoAAMIrK2TftjGi9HuFAQu5OutNBY2vSfGcn+oWMtMsKET3k6z5k3DWBBeG/nnM0qpSROFzyf5XljxhgONFhtD/qqbKo6xG3E+qo= 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=ecGGc9Ds; arc=none smtp.client-ip=209.85.208.49 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-ed1-f49.google.com with SMTP id 4fb4d7f45d1cf-563b7b3e3ecso3485153a12.0; Fri, 01 Mar 2024 05:46:51 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1709300810; x=1709905610; 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=umwFC7DE96xZZ1X/nt8K0ZM1RN381g70mq+QxdOjW8Y=; b=ecGGc9DsJs/WI8cUoYzJ3KzCYmHJ1xsmMkpj6A4byyozqFvgxXMoLJsEwibPFfjcWI Ij8B6zX3cll5MziBVjXXRKqqdmhq9u/QBztALWrgMn18wxtx2VSMHs86VLovJBh2/KdX TEqbQZbPykGc7uQnrUB0tvDOyTFj0nyhGIAg+86QQOuS9KqUGtrTabgFbqtWuwSlfaK2 kdy5CFIldNCWGhFJRdOQeDL2URGflK16RJPjV0cyUAFwxlcEKRe0Dk9Sl7UWdRSor0VA 6seSfYc00H2zDjJGVOscnTtiBh5Tg8CrA07GlDI80NNekoq9UR/oaxgFs+Tba0JfU2h+ si6A== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709300810; x=1709905610; 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=umwFC7DE96xZZ1X/nt8K0ZM1RN381g70mq+QxdOjW8Y=; b=hc7NB+khKWXY1daJpvAJdaPivD/Wxp6P90dRGtqRksFFNZhb7SC+GonIftcYnHPI+N 9rc7TN+53xLwyHusvtMA4PXRYjunHi5YujNokTiGyabgUu9vHMxBw+2k1WsUzMpLik7a t6dlGRgCR+3+0gTZvIi2W+A8SQ1wI5K1VbwN+MpHJPtGXiYAmgD97Bc66pwn8O3H1+E+ ZNZcqEHq8pw4rwX8QdfeQyUg2M+b7dxm0dSFav9MocF3ZuNfi/aRlWCuTCQuOEjPfid9 IHlXhfVMC7zUfzm/zSrxtO+UdPvTdshfP6Db89E4lDsCQw8hd8Jp+C2WGmrdF43rSVEv wbIA== X-Forwarded-Encrypted: i=1; AJvYcCX9m4ja6A5Ader+41EkFch1LDjERE7oKcszss4WesENPYvTrle8bvJLhIC4RRN5ZgUL6o0H7g3cRRWlZeLnxzD1zvscGiFeAzNj+ZM1aorJ4fih9TJGkUu6NK7l1um7lht0tcPBe77yPIR7y+lgQO5Q+q9pswlRx1HpUc1tkvQKQgv5 X-Gm-Message-State: AOJu0YzSnhkmCuNsgd7zL409wwfN1gXVJnEfEr5hMLQn5pugiz4N06fz qWnud1ZqJBMY8hId/r0wAjW7q8+U7Gy6gccivZ8N49rn/cXThYDzjQ0bh3jE4uU= X-Received: by 2002:a50:c943:0:b0:566:14e3:2262 with SMTP id p3-20020a50c943000000b0056614e32262mr1271351edh.36.1709300809753; Fri, 01 Mar 2024 05:46:49 -0800 (PST) Received: from lola.. ([2a02:810d:7e40:14b0:d371:e319:5dd0:9b35]) by smtp.gmail.com with ESMTPSA id fj10-20020a0564022b8a00b00563f8233ba8sm1584107edb.7.2024.03.01.05.46.49 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 01 Mar 2024 05:46:49 -0800 (PST) From: Lukas Bulwahn To: Jonathan Corbet , workflows@vger.kernel.org, linux-doc@vger.kernel.org Cc: kernel-janitors@vger.kernel.org, linux-kernel@vger.kernel.org, Lukas Bulwahn Subject: [PATCH 1/3] docs: submitting-patches: divert focus from PATCH in the subject line Date: Fri, 1 Mar 2024 14:46:35 +0100 Message-ID: <20240301134637.27880-2-lukas.bulwahn@gmail.com> X-Mailer: git-send-email 2.43.2 In-Reply-To: <20240301134637.27880-1-lukas.bulwahn@gmail.com> References: <20240301134637.27880-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: 1792331844559630070 X-GMAIL-MSGID: 1792331844559630070 Submitting-patches is already assuming that git is used to prepare patches. So, developers will use git format-patch and git send-email, and this will take care that PATCH is usually in the subject line. Hence, the 'include PATCH in the subject' does not deserve be an own section. Move this note into 'the canonical patch format' section, where it currently fits best. Signed-off-by: Lukas Bulwahn --- Documentation/process/submitting-patches.rst | 14 ++++---------- 1 file changed, 4 insertions(+), 10 deletions(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 66029999b587..2ec0c0d7d68f 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -384,16 +384,6 @@ patch or patch series which have not been modified in any way from the previous submission. -Include PATCH in the subject ------------------------------ - -Due to high e-mail traffic to Linus, and to linux-kernel, it is common -convention to prefix your subject line with [PATCH]. This lets Linus -and other kernel developers more easily distinguish patches from other -e-mail discussions. - -``git send-email`` will do this for you automatically. - Sign your work - the Developer's Certificate of Origin ------------------------------------------------------ @@ -616,6 +606,10 @@ The canonical patch subject line is:: Subject: [PATCH 001/123] subsystem: summary phrase +Prefix your subject line with [PATCH]. This allows to distinguish patches +from other e-mail discussions. ``git send-email`` will do this for you +automatically. + The canonical patch message body contains the following: - A ``from`` line specifying the patch author, followed by an empty From patchwork Fri Mar 1 13:46:36 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Lukas Bulwahn X-Patchwork-Id: 208861 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7301:2097:b0:108:e6aa:91d0 with SMTP id gs23csp1088074dyb; Fri, 1 Mar 2024 05:50:13 -0800 (PST) X-Forwarded-Encrypted: i=3; AJvYcCXlrIE7/A3XtXaKNujEzQWPPJXRfoAPBlv7B3oU7EGM7R68OrPoUW+a6060yuLCSpO7vgrxDKP4Chm2fqg6tveG88b2rw== X-Google-Smtp-Source: AGHT+IGqcDIVUudiPONOO+ov6xUedqu3Iz4V8oVmYy12OPhJ7pTeG9nQLq1qRtlNOWBGdDfwl9Vi X-Received: by 2002:a05:6a00:1898:b0:6e5:138:acf with SMTP id x24-20020a056a00189800b006e501380acfmr1783223pfh.10.1709301013432; Fri, 01 Mar 2024 05:50:13 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1709301013; cv=pass; d=google.com; s=arc-20160816; b=Kkg7IN4ROrOC4kLlgUNSLPOy1Dz96qTbWIxAQQwOEHlUKR1bjhtRbMunvfD3+xdmks 6wvoFwnpEJYe/XrZ6zS45/44Wyvq+p48YRUTlyDctA2+oDI3k8trPWQxHmtrf0pf6jFY LQxPWtX0JSS3ixm8a5+f3NMjVg2EBFNt0Yv/6kImeRwRTggOiN4/HgUybPcWXHaJCwkY GQbBN6Mlb1AitFi/kufK4EXzFW4pGog6jAEuHuv3wCfO1PVZo3NU2PhkK/xPLXtmMhWY gI/PKp+3Cggr/vP58HemfUK1qC4rMHur/M9OD7GFHptlrOYdw47CHRd6RLoLmu/DliFN 6kXA== 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=Qv07MvdmzdWImM+lzkVs9nrKyyN8RT3mxKng/XcK/HY=; fh=4k9sYtmMB5DGLyHYq0hi5lStylRWhhV0Igkvsj+5Olg=; b=jDtZC3f2IP4stg5LsrnjeXgMZSykvpZE6eEGUs04n6+jQh9FlnS5sd/UP0wsIMyIG4 kkCdJTGKVyQGOpxKJO1+373VEQtvN9gA4XXeSmW0CMBondjw8v+vE57g57b8JnNqVn0M wQEUKxs5aYCVU+e5Kg+PcjzXzXmcl6Tkme3/lJpoEezwmT1EbeY+jTfqawpyPl/vMCsQ 6GvE5vOmEYu4sXbdDVv8T6JgUvxlBIc4LO/EdYYsbXP3EJjLwYzG80EIEWT1bFpJU+wY G8FpLCVr7wroztW4mMUBiUTinwfecBEvtdOa45K99IUMSafBCOhmYL53boQA8VgyISG0 VRjg==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=lIRWvoZI; 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-88513-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-88513-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from sy.mirrors.kernel.org (sy.mirrors.kernel.org. [147.75.48.161]) by mx.google.com with ESMTPS id c13-20020a63d50d000000b005d66232593dsi3707259pgg.868.2024.03.01.05.50.13 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 01 Mar 2024 05:50:13 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-88513-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) client-ip=147.75.48.161; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=lIRWvoZI; 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-88513-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-88513-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 sy.mirrors.kernel.org (Postfix) with ESMTPS id 1AB66B21676 for ; Fri, 1 Mar 2024 13:47:44 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id E92C96F530; Fri, 1 Mar 2024 13:47:01 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="lIRWvoZI" Received: from mail-ed1-f46.google.com (mail-ed1-f46.google.com [209.85.208.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 2D11F6F506; Fri, 1 Mar 2024 13:46:56 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.46 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709300818; cv=none; b=Ufm8EvC7sUC9DZYREl1rvVrqQiOhtKMJq0a1ISM0EJXlUUy7sXu2hMHMO9QuHpyVZDPtI50Ppl4u62vRmhJR9HWpPxIJGx7Qih51ADrZLx+22FPy6qqvyr7zqNy4q+Ap6lZ84sa5fd6/Uxucin1POKzQeOIjiD1rHkUr7KIcTrA= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709300818; c=relaxed/simple; bh=g9uDef4vVL6k6nFEC5av3vPwaQXbIVgn1scOl2YNKpQ=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=jUR8rLZZ9rxl1d19z4ObIOrDBqGc4CloQOk5AQ0fK/e36qLZzmepUl+vAMpcmvvuZNPw6zGBHB2kMAjKJ1itcozeWWHtkO5+oP3Sz1CtNACDSih9duS2wFE5pOCY8RsUa4lK1ywKJnmsVJdy9GktmzNN39J54wapkWEdKzTZioI= 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=lIRWvoZI; arc=none smtp.client-ip=209.85.208.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-ed1-f46.google.com with SMTP id 4fb4d7f45d1cf-5640fef9fa6so2936150a12.0; Fri, 01 Mar 2024 05:46:56 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1709300815; x=1709905615; 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=Qv07MvdmzdWImM+lzkVs9nrKyyN8RT3mxKng/XcK/HY=; b=lIRWvoZIiR/VxwHoe+nl7qWe84tjQKi4WMRbHCyTEJKjlR2US25lV7yGVR6W/aulNa jD3qH0r8aNvhLq4r8pRY7tS0AW9vI/MWmxT92bzOawexTRmp72UIxkYsMySaLQ/Ite3P yfwRn2WKCAnpkTXMkTsOLrpqTKsqukU/+wJQxRG/YgOxKgdIVAUaO35W6VIwXFOPIgiE hEGq1aDW9ioHjYNddDNW1EHrUqQy7b/r6xpudRwdFc/2V//pfdTv6pOYbXamQvB7+UqX fG/SkowulRAeRk1DFywEl6de4YL0sYlh6lhKL2PRSNVeUx6WFn24YBOv74rJ7YATsH/n nD0g== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709300815; x=1709905615; 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=Qv07MvdmzdWImM+lzkVs9nrKyyN8RT3mxKng/XcK/HY=; b=dEBX3n7rn363uxlSKBc2UjPw8VTyjottvlN6lDswbNdrDzY0AtZzqiO4Okx4ySu7fM HHkcnFFjtsChUWecr29pVYaWuHidPcqvxyz2PzOeDoA0FPux7YufBqWfThMRco6S2VI7 HlL9PQagJ2j+QY4X+BLDF40fjTv7KV6jdboB5UfIPLmOpHB/eE+Vy/NGFNZtL9youChC ubSiE6g7ZVVnLVEuviEEb4CEel372WvBw5d3aDqwnnFdpVMdmKn3TZ75WJNQEjBygqpl xZoAa7C2AHtFAE3aGauJvbfIdWyxXW6LhInEoarIqDaEycqtt4WQBGQV79geeHQX8pbR MjCg== X-Forwarded-Encrypted: i=1; AJvYcCVMNeft6dkxcUZq89Vr5YqztQtOA1JwUWC7HIv0hosMhSIwrRpL+JS8nAopQjl1jvqoKVE7MK4EVBSBjAF5aKyhbrzWHHFBIfeqVFJDjw6vu2XyN4rjGmdg8JUQGs8zj/tpOzzRmWLztIWxJOthAkH4DSw6+VWRKKD8TfadGJg/P+vX X-Gm-Message-State: AOJu0YxV5/UnoFP5b1+1cF7/Uzuf14orWro/sMgrK8m/g7MnOhUJzoKG AjrFBvGsa/+ELJL0RaB9EC4VboTpCJDvVgMiOm5D16/PtgK5GVjq X-Received: by 2002:a50:cac7:0:b0:564:ded0:6072 with SMTP id f7-20020a50cac7000000b00564ded06072mr1322911edi.1.1709300815510; Fri, 01 Mar 2024 05:46:55 -0800 (PST) Received: from lola.. ([2a02:810d:7e40:14b0:d371:e319:5dd0:9b35]) by smtp.gmail.com with ESMTPSA id fj10-20020a0564022b8a00b00563f8233ba8sm1584107edb.7.2024.03.01.05.46.55 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 01 Mar 2024 05:46:55 -0800 (PST) From: Lukas Bulwahn To: Jonathan Corbet , workflows@vger.kernel.org, linux-doc@vger.kernel.org Cc: kernel-janitors@vger.kernel.org, linux-kernel@vger.kernel.org, Lukas Bulwahn Subject: [PATCH 2/3] docs: submitting-patches: move split_changes before describe_change Date: Fri, 1 Mar 2024 14:46:36 +0100 Message-ID: <20240301134637.27880-3-lukas.bulwahn@gmail.com> X-Mailer: git-send-email 2.43.2 In-Reply-To: <20240301134637.27880-1-lukas.bulwahn@gmail.com> References: <20240301134637.27880-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: 1792332019267060732 X-GMAIL-MSGID: 1792332019267060732 The top-level structure should basically be along the temporal order of things: Prepare a patch, Post a patch, Respond to review, Send reworked patches, Be patient before resending. Start bringing submitting-patches into this clear temporal flow. Move 'Separate your changes' before 'Describe your changes'. Note that this is also the order in 5.Posting. The same content is there covered in Patch preparation and Patch formatting. Signed-off-by: Lukas Bulwahn --- Documentation/process/submitting-patches.rst | 68 ++++++++++---------- 1 file changed, 34 insertions(+), 34 deletions(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 2ec0c0d7d68f..37925cacc5cc 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -40,6 +40,40 @@ patches prepared against those trees. See the **T:** entry for the subsystem in the MAINTAINERS file to find that tree, or simply ask the maintainer if the tree is not listed there. +.. _split_changes: + +Separate your changes +--------------------- + +Separate each **logical change** into a separate patch. + +For example, if your changes include both bug fixes and performance +enhancements for a single driver, separate those changes into two +or more patches. If your changes include an API update, and a new +driver which uses that new API, separate those into two patches. + +On the other hand, if you make a single change to numerous files, +group those changes into a single patch. Thus a single logical change +is contained within a single patch. + +The point to remember is that each patch should make an easily understood +change that can be verified by reviewers. Each patch should be justifiable +on its own merits. + +If one patch depends on another patch in order for a change to be +complete, that is OK. Simply note **"this patch depends on patch X"** +in your patch description. + +When dividing your change into a series of patches, take special care to +ensure that the kernel builds and runs properly after each patch in the +series. Developers using ``git bisect`` to track down a problem can end up +splitting your patch series at any point; they will not thank you if you +introduce bugs in the middle. + +If you cannot condense your patch set into a smaller set of patches, +then only post say 15 or so at a time and wait for review and integration. + + .. _describe_changes: Describe your changes @@ -163,40 +197,6 @@ An example call:: $ git log -1 --pretty=fixes 54a4f0239f2e Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") -.. _split_changes: - -Separate your changes ---------------------- - -Separate each **logical change** into a separate patch. - -For example, if your changes include both bug fixes and performance -enhancements for a single driver, separate those changes into two -or more patches. If your changes include an API update, and a new -driver which uses that new API, separate those into two patches. - -On the other hand, if you make a single change to numerous files, -group those changes into a single patch. Thus a single logical change -is contained within a single patch. - -The point to remember is that each patch should make an easily understood -change that can be verified by reviewers. Each patch should be justifiable -on its own merits. - -If one patch depends on another patch in order for a change to be -complete, that is OK. Simply note **"this patch depends on patch X"** -in your patch description. - -When dividing your change into a series of patches, take special care to -ensure that the kernel builds and runs properly after each patch in the -series. Developers using ``git bisect`` to track down a problem can end up -splitting your patch series at any point; they will not thank you if you -introduce bugs in the middle. - -If you cannot condense your patch set into a smaller set of patches, -then only post say 15 or so at a time and wait for review and integration. - - Style-check your changes ------------------------ From patchwork Fri Mar 1 13:46:37 2024 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Lukas Bulwahn X-Patchwork-Id: 208862 Return-Path: Delivered-To: ouuuleilei@gmail.com Received: by 2002:a05:7301:2097:b0:108:e6aa:91d0 with SMTP id gs23csp1088353dyb; Fri, 1 Mar 2024 05:50:39 -0800 (PST) X-Forwarded-Encrypted: i=3; AJvYcCXNMXbY8lzBf3bEY0jFCLfzArytu1tg3jwrlGvhOmZ4HuBklkPDNPix5jy8dnlTNhLfTTMHpdXSUoycwV6d5YESeCBs7Q== X-Google-Smtp-Source: AGHT+IENMn8J8KhEZKIltF32cBnTwi1kQlslOVQGfY4rLNlz0lbbcLGEt5jIi8hnVgx9b6lR5Gev X-Received: by 2002:a17:902:eac4:b0:1dc:adda:6d45 with SMTP id p4-20020a170902eac400b001dcadda6d45mr1322392pld.18.1709301039486; Fri, 01 Mar 2024 05:50:39 -0800 (PST) ARC-Seal: i=2; a=rsa-sha256; t=1709301039; cv=pass; d=google.com; s=arc-20160816; b=OWriXgm5FIS8ItpG2MhloDBUvqwnZou0s7h77Afl0j2/dIHxGOTn8FeFZKcaoFJEUB DDv81EgiOpXo8C8wO9d5oCJMXhiOwnImHP1+1U5z6RueHpcPTteoWKXUcbN8qQvxq3FR gZ3yfzYP65Fxl4S6HUEn06PDud3s953oVZrhD3l3TRH9VraUejAFAO1NvW7jnT7678xA 2r4OBaZAcOrN7xS6MkxerIaL6Gp/VqsiRZkyC2CDVBBng6KjwN1sWjK7jrJ+I5ePVP8P EKsUhhjEz1rqodgW6iTNmFCE8Mrc19HjZpWkLctcEWaEU7hbMb6LABY/xdAXRHYMdk8+ DXhw== 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=QDm5k9rOGj0cj/KUk66W2xhuESI746YZPYTqLDHnmNc=; fh=SkY/kPUj6Fzc+5DcBE0T9/J4Npz1b2IcZD2/1iycKWI=; b=KCQ+B4Y5IEufNahzw4+iIYEe1n2uT6oxULdqVvAt6UF4ica+ZZMG9uJxfObQON3ToM bVrHEOuIx7KQ6wM7hIfG+53ZsNuReGESmMyEJZpFXkAX/TzjV/OBXbonxVpOWsIPMsvT pbJwjfuiKhcFf8JrPCWdKInebSuiQYraf/I+07kx0zYkzi3IYr2Rz2kY1hb6kihbfJof TLTzCwuhy7ziJGFx/eWWRJG33595qjlO0EINRuVuTLsaErLB35vIicdW/LU2uTU0FhPl HEFUJam5eA1DIg2EVtBf7NE6wr0rljAdtJgrfzXFwwSwQLXQfecgl+PMDUKOUZk0cMOE hN2Q==; dara=google.com ARC-Authentication-Results: i=2; mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=g6mXlCCM; 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-88514-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-88514-ouuuleilei=gmail.com@vger.kernel.org"; dmarc=pass (p=NONE sp=QUARANTINE dis=NONE) header.from=gmail.com Received: from sy.mirrors.kernel.org (sy.mirrors.kernel.org. [147.75.48.161]) by mx.google.com with ESMTPS id u9-20020a170902e5c900b001dbc04cf96dsi3650422plf.20.2024.03.01.05.50.39 for (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 01 Mar 2024 05:50:39 -0800 (PST) Received-SPF: pass (google.com: domain of linux-kernel+bounces-88514-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) client-ip=147.75.48.161; Authentication-Results: mx.google.com; dkim=pass header.i=@gmail.com header.s=20230601 header.b=g6mXlCCM; 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-88514-ouuuleilei=gmail.com@vger.kernel.org designates 147.75.48.161 as permitted sender) smtp.mailfrom="linux-kernel+bounces-88514-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 sy.mirrors.kernel.org (Postfix) with ESMTPS id 8E84DB22EC2 for ; Fri, 1 Mar 2024 13:48:02 +0000 (UTC) Received: from localhost.localdomain (localhost.localdomain [127.0.0.1]) by smtp.subspace.kernel.org (Postfix) with ESMTP id 0377270AEA; Fri, 1 Mar 2024 13:47:07 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="g6mXlCCM" Received: from mail-ed1-f50.google.com (mail-ed1-f50.google.com [209.85.208.50]) (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 5BBA16F535; Fri, 1 Mar 2024 13:47:02 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.208.50 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709300824; cv=none; b=CVXvTHF7sb9kDeuHr0ZDUVdlmtaFrTWl79kV5gMHklZ8Q/jmCeKMJZzP1HmUfSAuCHxSOC72Vqg4Gev0v2a1GJ/sS1iFPViOfc7cqq90Zg0hnaitAxt/rj85Q6dVPkETbu7d3qqXJE+5W/mA/YeOT8tgZXCqfWjnumI/MXkcU4g= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1709300824; c=relaxed/simple; bh=vOW0UB9ncHeY6Hu9BHeSk0oc30qDNRInvrcsREBGnFs=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=nR+8lJtLwnNWSxumTxXxaRUrp3671lwUtsqUIf0vvH6Wn+9G3y5fV4ou1P6LCcb4nsHL9WJHzDrpn4mAsjlkBNbInyG1RFta7bmIS40scJySVPztLDVCzXm+gjytDPTpQj08i2l3n4+6gfNB+9K37O82wn0qg9abHr41nXOlswM= 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=g6mXlCCM; arc=none smtp.client-ip=209.85.208.50 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-ed1-f50.google.com with SMTP id 4fb4d7f45d1cf-56648955ac5so2987710a12.3; Fri, 01 Mar 2024 05:47:02 -0800 (PST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1709300821; x=1709905621; 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=QDm5k9rOGj0cj/KUk66W2xhuESI746YZPYTqLDHnmNc=; b=g6mXlCCMT0ypylCZNy3m3eHnuxWE9Q71CzA2RfMAWWu4wMANKGbHTFcY0JUtgH3d0M 7+e5irAnmYaqh2+Co8RleIEDh65IEx4l/BwAIu5SMAgQJft6TJmp3Cygqb6ZKbmsGDH2 ZXYcF+XDCgHy0wAOqtz77UtDVbt71uJFoGlEpSO//inhMG35CDOOdYUEwPWNC4b1mjq5 0XLHMe+vE4hQV0F1Lu/RlYrzQFOTPB7nmv3mXQ8gVvjIiGEYAn8Z9myC2XaJyI5Fdd4j gQWFLTxVuBY69p0/CatNMzkfgn47G3t9UB9boy9gepdJg7LBVpL0JWQf9Y8K762ou7ev tdmg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1709300821; x=1709905621; 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=QDm5k9rOGj0cj/KUk66W2xhuESI746YZPYTqLDHnmNc=; b=hQEdDL63MecmxgZT936FSf4Lx3gOdrEPIP72mjFkC52djMAYsWwkr0dgvcv6yhyb3M gc8M4YgLVweWqxDZdNn1aIHqyfn3mfIacYKZfsV0MsRONMuQo4k0DvP24bgguAu3voWg gafE2WDVPicEt6rYxFg7JP1CPc6wZsRtJGGWRBYUBnuaWHKte/kkpP2P4+MnYAp6hr15 xMmAe9bZJQYJSKRpMU+0BozB40P/vZYnuqOKR+vEWf3CUXJJVYp/44W0rv3FKYkyxI6n T8H5r6feHDZoYfoUaq/abTDeBchvnkbwBWTs+24/02SHoglmzumgYvGmYSmA8GWI7YKl X8Dg== X-Forwarded-Encrypted: i=1; AJvYcCUn623tJ0OOA7msP7YR2JBtlwODqMXNKNtjFn4bmpFN5sgfXTueBpEjJCl6vgZ0M6cFesu2dw1fR+y+QDEixbKLj67UBsvadNE6MsVbazgQJgSDv6G7i+WeUiesYvt3aWL48KfOM4QcWaGYj3MagMlQHB3eCAMbiAqODpNysD2EwWFm X-Gm-Message-State: AOJu0Yx+knNEsu+iAFOUplPCknz3h9cnesLp271Y+LnWNkVr6jAk3Yyn /l6BtwXEK2IeGHknXnquuTTSyQl4dnpNdn/NzMzXeEfiBuy4S7u0Alo8y7HKJD4= X-Received: by 2002:a05:6402:5c3:b0:565:7edf:41b0 with SMTP id n3-20020a05640205c300b005657edf41b0mr1356102edx.6.1709300820610; Fri, 01 Mar 2024 05:47:00 -0800 (PST) Received: from lola.. ([2a02:810d:7e40:14b0:d371:e319:5dd0:9b35]) by smtp.gmail.com with ESMTPSA id fj10-20020a0564022b8a00b00563f8233ba8sm1584107edb.7.2024.03.01.05.46.59 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Fri, 01 Mar 2024 05:47:00 -0800 (PST) From: Lukas Bulwahn To: Jonathan Corbet , workflows@vger.kernel.org, linux-doc@vger.kernel.org Cc: kernel-janitors@vger.kernel.org, linux-kernel@vger.kernel.org, Lukas Bulwahn Subject: [PATCH 3/3] docs: submitting-patches: move backtraces to patch description Date: Fri, 1 Mar 2024 14:46:37 +0100 Message-ID: <20240301134637.27880-4-lukas.bulwahn@gmail.com> X-Mailer: git-send-email 2.43.2 In-Reply-To: <20240301134637.27880-1-lukas.bulwahn@gmail.com> References: <20240301134637.27880-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: 1792332046909281400 X-GMAIL-MSGID: 1792332046909281400 The top-level structure should basically be along the temporal order of things: Prepare a patch, Post a patch, Respond to review, Send reworked patches, Be patient before resending. For that, content from the canonical patch format needs to dissolve into the pieces along the temporal order. Move the subsection on backtraces in the canonical patch format into the 'describe your change' section. As we would like to keep backtraces as a subsection (maintainer-tip.rst refers to it), let us add another subsection in the 'describe your change' section and turn the title into imperative form. Signed-off-by: Lukas Bulwahn --- Documentation/process/submitting-patches.rst | 47 +++++++++++--------- 1 file changed, 25 insertions(+), 22 deletions(-) diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index 37925cacc5cc..584bcd8638ea 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -130,6 +130,9 @@ instead of "[This patch] makes xyzzy do frotz" or "[I] changed xyzzy to do frotz", as if you are giving orders to the codebase to change its behaviour. +Refer to URLs and commits in common style +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + If you want to refer to a specific commit, don't just refer to the SHA-1 ID of the commit. Please also include the oneline summary of the commit, to make it easier for reviewers to know what it is about. @@ -197,6 +200,28 @@ An example call:: $ git log -1 --pretty=fixes 54a4f0239f2e Fixes: 54a4f0239f2e ("KVM: MMU: make kvm_mmu_zap_page() return the number of pages it actually freed") +.. _backtraces: + +Distill backtraces +~~~~~~~~~~~~~~~~~~ + +Backtraces help document the call chain leading to a problem. However, +not all backtraces are helpful. For example, early boot call chains are +unique and obvious. Copying the full dmesg output verbatim, however, +adds distracting information like timestamps, module lists, register and +stack dumps. + +Therefore, the most useful backtraces should distill the relevant +information from the dump, which makes it easier to focus on the real +issue. Here is an example of a well-trimmed backtrace:: + + unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) + at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) + Call Trace: + mba_wrmsr + update_domains + rdtgroup_mkdir + Style-check your changes ------------------------ @@ -742,28 +767,6 @@ patch:: See more details on the proper patch format in the following references. -.. _backtraces: - -Backtraces in commit messages -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - -Backtraces help document the call chain leading to a problem. However, -not all backtraces are helpful. For example, early boot call chains are -unique and obvious. Copying the full dmesg output verbatim, however, -adds distracting information like timestamps, module lists, register and -stack dumps. - -Therefore, the most useful backtraces should distill the relevant -information from the dump, which makes it easier to focus on the real -issue. Here is an example of a well-trimmed backtrace:: - - unchecked MSR access error: WRMSR to 0xd51 (tried to write 0x0000000000000064) - at rIP: 0xffffffffae059994 (native_write_msr+0x4/0x20) - Call Trace: - mba_wrmsr - update_domains - rdtgroup_mkdir - .. _explicit_in_reply_to: Explicit In-Reply-To headers