From nobody Sat Sep 26 11:01:25 2026 Received: from mail-pg1-f174.google.com (mail-pg1-f174.google.com [209.85.215.174]) (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 843DC3EF0A0 for ; Wed, 2 Sep 2026 08:44:46 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.174 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338691; cv=none; b=SVb8KWtnn2SD1OGomCNhBdwXfbb7zxSpJbs607zlx772bWu2chcndY+O6cAFgHzOdvfxfjHL8xOGpvs9swzma/BIaBRRrxp26C8mPit3n+B6gHSodWpD4W8pfiCu5Ttf9Owq+efTouxzxFdnw3Y571DuEGgcmOvEeo60mXP1FOI= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338691; c=relaxed/simple; bh=y3564IyB3FL0gx6xFJeHm1YTmss9kUj4skLIm9wvdhE=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=LH0yIAEPNrg0XcAjwoH5it+/2zF08iXF8mZXOpKMToMTEqiuZ7i23f1skzt4CPOb5KRspoTm57maShKPCAX6MvGTGJC2lfU5EN+8lTdn8CQ43UR2Dxbtp7DSk0w2P5nmQiVQ8c3JiHHJUQUBOAGZSnBQJz32PP4qGmg/gO459Uc= 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=VfbMlKeX; arc=none smtp.client-ip=209.85.215.174 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 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="VfbMlKeX" Received: by mail-pg1-f174.google.com with SMTP id 41be03b00d2f7-cc1cc97b84bso695161a12.1 for ; Wed, 02 Sep 2026 01:44:46 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1788338684; x=1788943484; 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:content-type; bh=lEDK+6s8EUU2Oy7vTke/AIdPRfzFNyY3UuiurUasEcA=; b=VfbMlKeX6wUeZyjW3zBejfCjYMT1uYr2DJnVVaz6jJEmQuZe5c++F9e3BWu5XctUGK Xcwf75AI5qLUL44syDZ3FcsmzWWZ3LlVG+6SgQU71fXN/cIScoB5tSg2iHmT+m/Yz1pc 0hV8DKlsK0DCvhT+vCoD/2e119PK/ephmZxVBZCAZG7lhlAwmEYVKAM52TWhMmtXIpqv eDuXVisYq0DdTugwKnooDZ9YTIgaB3FR8oRCHwwt1MKLqfjSyOxDa+HuzabfXKIajtL0 tXv7g5TkxI6tc6OhAh/Ix4DW+VRXo6hwCKV33ck+Yma6Mlx6pTcoVYXA+d5zkrZRdZOC aIYQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1788338684; x=1788943484; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=lEDK+6s8EUU2Oy7vTke/AIdPRfzFNyY3UuiurUasEcA=; b=ccbTq5ToyTwaCSFJiMrfrKCWvnobW/n1sAtIiG+ys/quQsXjF9NeiXl4GaHjlDbaYk D4GzUykmbp8edrbMnAUEGNn5r8RVFfPE9EJEg3j+aWPF+BXvc2C8QidirM7wpZdaihGL X9RUv7LElA8cCgfKUW403GnUf96d3NO4YO4k9E+Sjyq06vsamTW6E17d3e0nHRPMuALL ZoX40TqEEULrU/v850KVd9fwVtOEVvJAy4tiTRL6IPdNVlh2+3Gw0S8YsRfb1ZsHv8aT ALyjUgCzzhc1QzuLxBRalpzRnDBCTlHhLt7dTkgWXkDV39J3FhrNBJ/YMRkdRFkZq+HH Gm4w== X-Forwarded-Encrypted: i=1; AKwUvBw1FJNsFeYJmIgo9vYUQGTCT42f3IQ3/OCBHthrGrT2udqxTUFsdSvBz9LTTh+Ns2fnP+HPDsY95k8aMic=@vger.kernel.org X-Gm-Message-State: AFuF++kE+p2QcuDQs9EC8tIAQMpgEldolr2i7TvlMn/15zVka0c4dm2m SMvP37o8JZsUaFhouGx/L4QF2+pVWoh0tfSq79J61FfXajezIuy4rUid X-Gm-Gg: AYBFou2cm/SFYRdTUd1qbAHJO+yyTa/Q3fi1C3L2unCVcWYgHcbaODwX03pU/93khSp 7gasvEqazBGHIlKApZ9RcUm7+5HjMyClLgRkiWKAsVbdpqiG+qzgIPSObrI5nfbCU5TaUtz7XpI DHi6/jAoL7/QeWrC9OHgU1u7yhQnZW7VX5pSqCmHWgCBNb9TicHx1Dp+bmmOcjTwJH5sM8DKmbD wPp9YEDK5DbCfqCvtiqBPKMaEP8UfcjvZFCL5Bwb8pVtHNC09EbxizYTeuOpjRfNKgBsQNPNwAn g3pcEvy4Rffz1Rz411saBEwCz7mRA2ltN7bgjluR9rC2pO1Z2PoyUNa1dCE/H5ShZJ/jajOcNxN vDna1I/wivIVBaRRk50l2w6foxMQqHmQvQPqt6nWdkYp2yt7bAECbut8AIdZ6kxlEdxYIFnPjNu V0BlwgcL9lkWjuzat3TftLboREDznIq5WR1sAY4olNeKfuw3lABYEiHaXWlCOnHUY3i48YuXmR1 jvKb3UOsNMD6pBuLfA= X-Received: by 2002:a17:90b:1d4c:b0:398:a145:5d3d with SMTP id 98e67ed59e1d1-39aedf0956bmr4779488a91.6.1788338684396; Wed, 02 Sep 2026 01:44:44 -0700 (PDT) Received: from localhost.localdomain ([222.254.211.218]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-39ae3c6f337sm4845289a91.16.2026.09.02.01.44.41 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 02 Sep 2026 01:44:43 -0700 (PDT) From: Nguyen Duc Thinh To: Jonathan Corbet Cc: Weijie Yuan , Shuah Khan , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Nguyen Duc Thinh Subject: [PATCH v2 1/5] Documentation: process: Clean up grammar, tone, and contractions in core files Date: Wed, 2 Sep 2026 15:43:59 +0700 Message-ID: <20260902084430.17248-2-ducthinh100812@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260902084430.17248-1-ducthinh100812@gmail.com> References: <20260902084430.17248-1-ducthinh100812@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Update three process documentation files to improve text consistency and professional tone. Expand informal contractions like "don't" to "do not", resolve minor punctuation errors, and refine the voice for better readability. Signed-off-by: Nguyen Duc Thinh --- Documentation/process/1.Intro.rst | 18 +++++++++--------- Documentation/process/3.Early-stage.rst | 14 +++++++------- Documentation/process/6.Followthrough.rst | 16 ++++++++-------- 3 files changed, 24 insertions(+), 24 deletions(-) diff --git a/Documentation/process/1.Intro.rst b/Documentation/process/1.In= tro.rst index 847fbe76b6a44..0c95239eadda8 100644 --- a/Documentation/process/1.Intro.rst +++ b/Documentation/process/1.Intro.rst @@ -24,7 +24,7 @@ initial exercise. :ref:`development_early_stage` covers early-stage project planning, with an emphasis on involving the development community as soon as possible. =20 -:ref:`development_coding` is about the coding process; several pitfalls wh= ich +:ref:`development_coding` is about the coding process; several pitfalls th= at have been encountered by other developers are discussed. Some requirement= s for patches are covered, and there is an introduction to some of the tools which can help to ensure that kernel patches are correct. @@ -53,7 +53,7 @@ What this document is about The Linux kernel, at over 8 million lines of code and well over 1000 contributors to each release, is one of the largest and most active free software projects in existence. Since its humble beginning in 1991, this -kernel has evolved into a best-of-breed operating system component which +kernel has evolved into a best-of-breed operating system component that runs on pocket-sized digital music players, desktop PCs, the largest supercomputers in existence, and all types of systems in between. It is a robust, efficient, and scalable solution for almost any situation. @@ -84,7 +84,7 @@ difficulties when trying to do kernel work. The kernel c= ommunity has evolved its own distinct ways of operating which allow it to function smoothly (and produce a high-quality product) in an environment where thousands of lines of code are being changed every day. So it is not -surprising that Linux kernel development process differs greatly from +surprising that the Linux kernel development process differs greatly from proprietary development methods. =20 The kernel's development process may come across as strange and @@ -95,8 +95,8 @@ have a frustrating experience in store. The development = community, while being helpful to those who are trying to learn, has little time for those who will not listen or who do not care about the development process. =20 -It is hoped that those who read this document will be able to avoid that -frustrating experience. There is a lot of material here, but the effort +Those who read this document should be able to avoid that frustrating +experience. There is a lot of material here, but the effort involved in reading it will be repaid in short order. The development community is always in need of developers who will help to make the kernel better; the following text should help you - or those who work for you - @@ -145,7 +145,7 @@ discussed in greater detail later in this document. Co= nsider: out-of-tree code requires significant amounts of work just to keep that code working. =20 - Code which is in the mainline, instead, does not require this work as the + By contrast, code in the mainline does not require this work as the result of a simple rule requiring any developer who makes an API change to also fix any code that breaks as the result of that change. So code which has been merged into the mainline has significantly lower @@ -176,7 +176,7 @@ discussed in greater detail later in this document. Co= nsider: out of tree indefinitely, or (2) abandoning your code and migrating your users over to the in-tree version. =20 -- Contribution of code is the fundamental action which makes the whole +- Contribution of code is the fundamental action that makes the whole process work. By contributing your code you can add new functionality to the kernel and provide capabilities and examples which are of use to other kernel developers. If you have developed code for Linux (or are @@ -194,7 +194,7 @@ include: are cloudy at best; quite a few kernel copyright holders believe that most binary-only modules are derived products of the kernel and that, as a result, their distribution is a violation of the GNU General Public - License (about which more will be said below). Your author is not a + License (about which more will be said below). The author is not a=20 lawyer, and nothing in this document can possibly be considered to be legal advice. The true legal status of closed-source modules can only be determined by the courts. But the uncertainty which haunts those modules @@ -233,7 +233,7 @@ Licensing Code is contributed to the Linux kernel under a number of licenses, but all code must be compatible with version 2 of the GNU General Public License (GPLv2), which is the license covering the kernel distribution as a whole. -In practice, that means that all code contributions are covered either by +In practice, this means all code contributions are covered either by GPLv2 (with, optionally, language allowing distribution under later versions of the GPL) or the three-clause BSD license. Any contributions which are not covered by a compatible license will not be accepted into the diff --git a/Documentation/process/3.Early-stage.rst b/Documentation/proces= s/3.Early-stage.rst index 87fa7875e3369..06f9adcd1f833 100644 --- a/Documentation/process/3.Early-stage.rst +++ b/Documentation/process/3.Early-stage.rst @@ -58,7 +58,7 @@ creation of a body of code. So, when contemplating a kernel development project, one should obtain answers to a short set of questions: =20 - - What, exactly, is the problem which needs to be solved? + - What, exactly, is the problem that needs to be solved? =20 - Who are the users affected by this problem? Which use cases should the solution address? @@ -75,7 +75,7 @@ When planning a kernel development project, it makes grea= t sense to hold discussions with the community before launching into implementation. Early communication can save time and trouble in a number of ways: =20 - - It may well be that the problem is addressed by the kernel in ways which + - It may well be that the problem is addressed by the kernel in ways that you have not understood. The Linux kernel is large and has a number of features and capabilities which are not immediately obvious. Not all kernel capabilities are documented as well as one might like, and it is @@ -136,7 +136,7 @@ relevant subsystem and the environment may be more supp= ortive. Finding maintainers can be a bit harder. Again, the MAINTAINERS file is the place to start. That file tends to not always be up to date, though, and not all subsystems are represented there. The person listed in the -MAINTAINERS file may, in fact, not be the person who is actually acting in +MAINTAINERS file may not, in fact, be the person who is actually acting in that role currently. So, when there is doubt about who to contact, a useful trick is to use Git (and "git log" in particular) to see who is currently active within the subsystem of interest. Look at who is writing @@ -168,12 +168,12 @@ When to post? ------------- =20 If possible, posting your plans during the early stages can only be -helpful. Describe the problem being solved and any plans that have been -made on how the implementation will be done. Any information you can +helpful. Describe the problem being solved and how you plan to +implement the solution. Any information you can provide can help the development community provide useful input on the project. =20 -One discouraging thing which can happen at this stage is not a hostile +One discouraging thing that can happen at this stage is not a hostile reaction, but, instead, little or no reaction at all. The sad truth of the matter is (1) kernel developers tend to be busy, (2) there is no shortage of people with grand plans and little code (or even prospect of code) to @@ -217,7 +217,7 @@ a non-disclosure agreement. The Linux Foundation opera= tes an NDA program designed to help with this sort of situation; more information can be found at: =20 - https://www.linuxfoundation.org/nda/ + https://www.linuxfoundation.org/legal/nda/ =20 This kind of review is often enough to avoid serious problems later on without requiring public disclosure of the project. diff --git a/Documentation/process/6.Followthrough.rst b/Documentation/proc= ess/6.Followthrough.rst index 66fa400c6d940..ba145b705df02 100644 --- a/Documentation/process/6.Followthrough.rst +++ b/Documentation/process/6.Followthrough.rst @@ -10,7 +10,7 @@ developers can make is to conclude that their work is now= done. In truth, posting patches indicates a transition into the next stage of the process, with, possibly, quite a bit of work yet to be done. =20 -It is a rare patch which is so good at its first posting that there is no +It is a rare patch that is so good at its first posting that there is no room for improvement. The kernel development process recognizes this fact, and, as a result, is heavily oriented toward the improvement of posted code. You, as the author of that code, will be expected to work with the @@ -60,8 +60,8 @@ mind: =20 What all of this comes down to is that, when reviewers send you comments, you need to pay attention to the technical observations that they are -making. Do not let their form of expression or your own pride keep that -from happening. When you get review comments on a patch, take the time to +making. Do not let their tone or your own pride prevent that. +When you get review comments on a patch, take the time to understand what the reviewer is trying to say. If possible, fix the things that the reviewer is asking you to fix. And respond back to the reviewer: thank them, and describe how you will answer their questions. @@ -96,7 +96,7 @@ through list archives to familiarize themselves with what= was said last time; if you help them get a running start, they will be in a better mood when they revisit your code. =20 -What if you've tried to do everything right and things still aren't going +What if you've tried to do everything right and things still are not going anywhere? Most technical disagreements can be resolved through discussion, but there are times when somebody simply has to make a decision. If you honestly believe that this decision is going against you wrongly, you can @@ -128,7 +128,7 @@ Inclusion into a subsystem tree can bring a higher leve= l of visibility to a patch. Now other developers working with that tree will get the patch by default. Subsystem trees typically feed linux-next as well, making their contents visible to the development community as a whole. At this point, -there's a good chance that you will get more comments from a new set of +there is a good chance that you will get more comments from a new set of reviewers; these comments need to be answered as in the previous round. =20 What may also happen at this point, depending on the nature of your patch, @@ -142,7 +142,7 @@ blessings: before the advent of the linux-next tree, th= ese conflicts often only turned up during the merge window and had to be addressed in a hurry. Now they can be resolved at leisure, before the merge window opens. =20 -Some day, if all goes well, you'll log on and see that your patch has been +Someday, if all goes well, you will log on and see that your patch has been merged into the mainline kernel. Congratulations! Once the celebration is complete (and you have added yourself to the MAINTAINERS file), though, it is worth remembering an important little fact: the job still is not done. @@ -174,7 +174,7 @@ After any regressions have been dealt with, there may b= e other, ordinary bugs to deal with. The stabilization period is your best opportunity to fix these bugs and ensure that your code's debut in a mainline kernel release is as solid as possible. So, please, answer bug reports, and fix -the problems if at all possible. That's what the stabilization period is +the problems if at all possible. That is what the stabilization period is for; you can start creating cool new patches once any problems with the old ones have been taken care of. =20 @@ -208,7 +208,7 @@ far. If you are seen as needlessly blocking good work,= those patches will eventually flow around you and get into the mainline anyway. In the Linux kernel, nobody has absolute veto power over any code. Except maybe Linus. =20 -On very rare occasion, you may see something completely different: another +On very rare occasions, you may see something completely different: another developer posts a different solution to your problem. At that point, chances are that one of the two patches will not be merged, and "mine was here first" is not considered to be a compelling technical argument. If --=20 2.50.1 (Apple Git-155) From nobody Sat Sep 26 11:01:25 2026 Received: from mail-pj1-f49.google.com (mail-pj1-f49.google.com [209.85.216.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 73CEC3EF0BE for ; Wed, 2 Sep 2026 08:44:53 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.49 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338697; cv=none; b=nUeHp/rKIr7GDoHem2a2lWHCugaLRuhz8wsFCRXUFCZXSSX2zz7gnqS8g5AroUDH1cc5tBTia2jIJEPGBpSIwOTWePeUSwts1yJXUdUogWigBRqg8Er/2Fj82klCzXJd1v6uwfyM8qYOHP/zuxupY5Ku5R0uvuuHwpHURbreQr4= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338697; c=relaxed/simple; bh=z5iMusljCvnT4Da+gKyPl5dWGfWHAHZDl+AnXXtfb/0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=J3nGLQFU+AFHUJS6qNygwXzJifa1MyNkmnPX+1XKqmDARAm2JuX4fwzzTdrfCVNsvKPEh5xcSDWvuhKIIO1BFL2kcuy2j0a+OgpPbIIQ3knh4KrzKupF9dCxrIIM9olYHundvEKKY1x8RAbWnzcjOufzScGIJKtM3L432k7DYcA= 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=aNrpfKxH; arc=none smtp.client-ip=209.85.216.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 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="aNrpfKxH" Received: by mail-pj1-f49.google.com with SMTP id 98e67ed59e1d1-3966791a6eeso979894a91.3 for ; Wed, 02 Sep 2026 01:44:52 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1788338690; x=1788943490; 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:content-type; bh=nQcGZ0F2oJgL1FAwfbiq3IvyL2PT64kaQuA2R1hyPdE=; b=aNrpfKxH4n/gP5Tu7rcAGHkW76H0Y9hAJ9KcUaRyXQxunueUEPyKFZvZcJrgvBDE/0 kSD6yfPIcKyuMpNI9JvC4qz7QG2R5atvCmFVXwIDBdY+hBMtLmGG9N8OC4xIrT7GUp2f x9EzgWsSRvBwtp7hKQlGwPerbQh9Nc8pPtrdzgixUCopB+KVxaLijCyCSl5yPuxuC5Y2 M5GhxdksPtM0jLoKWITeGEWqTziiEBMyDZG/Drss4Itg+CPHsFKvxvfO8fYfBDm1ikUD Gw6pU6rGWasT5FNcQpO8vb23w2QqPWWyjUB+eDH6JQwIZzA5Yjz6SVlIoy4/n1Zuwz3W Iazg== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1788338690; x=1788943490; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=nQcGZ0F2oJgL1FAwfbiq3IvyL2PT64kaQuA2R1hyPdE=; b=ZxsKVXOVeQeUsLjeXsOi6H379JAakrAIJdQbWr7wOpduTTGMH2ivH6jtYOh1HgwTd+ ua6yzStralJvWJ2zCvbCvRdvB+dt3eEv8cXvyekOV8DM7RmtvAF5enj5qSrMTohd6AS7 A0qo4NanDHv9tULc3a4a/0ktNWcvM9qxsqd8qqkNUwT1JqlnzKGKuhSB2a9jKeQPET4F SERAgTxsI3xJPqmmMdcHJWPJmplHBUuMtgNFcb9dp6DR194scA4KNpp1uHYOuOmPqvze yw234ua9b/1l6EO9ebavOAllfy4ym6mEmCkC5HVaAqKn9e01SiK6gOBFyNpEGrk29uHp tMCw== X-Forwarded-Encrypted: i=1; AKwUvBw/LUXTvIc8z9PZNic7mc7xiE7E6sGqwczNmBwLUKixXfafoPp1S18IT/aBe5v8tfH+w9QK7vKxmKRYlHQ=@vger.kernel.org X-Gm-Message-State: AFuF++mfbtXu7KwfQ9vi1SSqCsEn6dnY0meArkyyK2YgJFpKK/WQZxxg xbPI1m5iZ6vC+jvD/Yt3iNygfb9A+coCZV4KExZejm9bcE0jNqULgjDk X-Gm-Gg: AYBFou3EwvePHzFvOlLT3/3IIKTpz9DndjM2N2CHIpiaP/sXGAb+283hB7VU+NZanvg X2qFKpJ9v36sS1rTeTcTb2TbIwzuPI170/+mkCAc6+E7f+RoT7N0UR2AoRa0xAwaRuGzfIi+6Rg BtzGzJNJ49CBApCa+YqdKG/zaB1b8j71eXYDPw10sdPO9x8FYYtRAkCNv7pBh0NTrZXvyRXbTc7 Yp8bfYpUXhXAInLoQXXa/zm03s8tRDXbfS2j8oJjLXNk40fmheRJTBecdOSVjpGRjrxiUPcZebQ yfiU6WLn/a0ij21B9fOAxJiOZpV6n0iJdO1cHixACAi7+t5oT+gtJkfK5oEe2Sd2x6wtS576rFJ 8UG7gD8naeRWyN/pZxWNNBvLWJT/cUd6HyIEKi8yR5XNJrXulbr/yUcwlbQ7LZlAmWsA8p54GSb vfnHEUn4GEGOVhJxE341q+yrgHAkHz7OwHo4r6A4LHBNIVazcEEiycq4PRlzjxR3XzTDwL1gvgm Q3WnwVE59RqAJdfbsU= X-Received: by 2002:a17:90b:268d:b0:398:ab03:95b2 with SMTP id 98e67ed59e1d1-39aee023191mr5375943a91.10.1788338690056; Wed, 02 Sep 2026 01:44:50 -0700 (PDT) Received: from localhost.localdomain ([222.254.211.218]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-39ae3c6f337sm4845289a91.16.2026.09.02.01.44.47 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 02 Sep 2026 01:44:49 -0700 (PDT) From: Nguyen Duc Thinh To: Jonathan Corbet Cc: Weijie Yuan , Shuah Khan , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Nguyen Duc Thinh Subject: [PATCH v2 2/5] Documentation: process: Clean up grammar and tone in next guide files Date: Wed, 2 Sep 2026 15:44:00 +0700 Message-ID: <20260902084430.17248-3-ducthinh100812@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260902084430.17248-1-ducthinh100812@gmail.com> References: <20260902084430.17248-1-ducthinh100812@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Perform a thorough copy-editing pass across three more files in the process documentation directory. Expand informal contractions, correct minor punctuation oversights, and refine the voice to maintain a professional tone, especially replacing "which" with "that" in restrictive clauses. Signed-off-by: Nguyen Duc Thinh --- Documentation/process/2.Process.rst | 22 ++++++------- Documentation/process/4.Coding.rst | 48 ++++++++++++++--------------- Documentation/process/5.Posting.rst | 34 ++++++++++---------- 3 files changed, 52 insertions(+), 52 deletions(-) diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.= Process.rst index d09fa23d6c42a..2443e0eca3525 100644 --- a/Documentation/process/2.Process.rst +++ b/Documentation/process/2.Process.rst @@ -29,7 +29,7 @@ releases, along with their dates, can be found at `Wikipe= dia =20 A relatively straightforward discipline is followed with regard to the merging of patches for each release. At the beginning of each development -cycle, the "merge window" is said to be open. At that time, code which is +cycle, the "merge window" is said to be open. At that time, code that is deemed to be sufficiently stable (and which is accepted by the development community) is merged into the mainline kernel. The bulk of changes for a new development cycle (and all of the major changes) will be merged during @@ -49,7 +49,7 @@ be called 9.x-rc1. The -rc1 release is the signal that t= he time to merge new features has passed, and that the time to stabilize the next kernel has begun. =20 -Over the next six to ten weeks, only patches which fix problems should be +Over the next six to ten weeks, only patches that fix problems should be submitted to the mainline. On occasion a more significant change will be allowed, but such occasions are rare; developers who try to merge new features outside of the merge window tend to get an unfriendly reception. @@ -99,7 +99,7 @@ go out with a handful of known regressions, though, hopef= ully, none of them are serious. =20 Once a stable release is made, its ongoing maintenance is passed off to the -"stable team," currently consists of Greg Kroah-Hartman and Sasha Levin. T= he +"stable team," which currently consists of Greg Kroah-Hartman and Sasha Le= vin. The stable team will release occasional updates to the stable release using the 9.x.y numbering scheme. =20 @@ -140,7 +140,7 @@ The lifecycle of a patch Patches do not go directly from the developer's keyboard into the mainline kernel. There is, instead, a somewhat involved (if somewhat informal) process designed to ensure that each patch is reviewed for quality and that -each patch implements a change which is desirable to have in the mainline. +each patch implements a change that is desirable to have in the mainline. This process can happen quickly for minor fixes, or, in the case of large and controversial changes, go on for years. Much developer frustration comes from a lack of understanding of this process or from attempts to @@ -185,7 +185,7 @@ The stages that a patch goes through are, generally: - Merging into the mainline. Eventually, a successful patch will be merged into the mainline repository managed by Linus Torvalds. More comments and/or problems may surface at this time; it is important that - the developer be responsive to these and fix any issues which arise. + the developer be responsive to these and fix any issues that arise. =20 - Stable release. The number of users potentially affected by the patch is now large, so, once again, new problems may arise. @@ -208,7 +208,7 @@ How patches get into the Kernel =20 There is exactly one person who can merge patches into the mainline kernel repository: Linus Torvalds. But, for example, of the over 9,500 patches -which went into the 2.6.38 kernel, only 112 (around 1.3%) were directly +that went into the 2.6.38 kernel, only 112 (around 1.3%) were directly chosen by Linus himself. The kernel project has long since grown to a size where no single developer could possibly inspect and select every patch unassisted. The way the kernel developers have addressed this growth is @@ -235,7 +235,7 @@ Linus agrees, the stream of patches will flow up into h= is repository, becoming part of the mainline kernel. The amount of attention that Linus pays to specific patches received in a pull operation varies. It is clear that, sometimes, he looks quite closely. But, as a general rule, Linus -trusts the subsystem maintainers to not send bad patches upstream. +trusts subsystem maintainers not to send bad patches upstream. =20 Subsystem maintainers, in turn, can pull patches from other maintainers. For example, the networking tree is built from patches which accumulated @@ -255,7 +255,7 @@ Next trees =20 The chain of subsystem trees guides the flow of patches into the kernel, but it also raises an interesting question: what if somebody wants to look -at all of the patches which are being prepared for the next merge window? +at all of the patches that are being prepared for the next merge window? Developers will be interested in what other changes are pending to see whether there are any conflicts to worry about; a patch which changes a core kernel function prototype, for example, will conflict with any other @@ -310,7 +310,7 @@ The kernel source tree contains the drivers/staging/ di= rectory, where many sub-directories for drivers or filesystems that are on their way to being added to the kernel tree live. They remain in drivers/staging while they still need more work; once complete, they can be moved into the -kernel proper. This is a way to keep track of drivers that aren't +kernel proper. This is a way to keep track of drivers that are not up to Linux kernel coding or quality standards, but people may want to use them and track development. =20 @@ -349,7 +349,7 @@ for kernel development, in that it performs quite well = when dealing with large repositories and large numbers of patches. It also has a reputation for being difficult to learn and use, though it has gotten better over time. Some sort of familiarity with Git is almost a requirement for kernel -developers; even if they do not use it for their own work, they'll need Git +developers; even if they do not use it for their own work, they will need = Git to keep up with what other developers (and the mainline) are doing. =20 Git is now packaged by almost all Linux distributions. There is a home @@ -483,7 +483,7 @@ Andrew Morton gives this advice for aspiring kernel dev= elopers that the kernel runs perfectly at all times on all machines which you can lay your hands on". Usually the way to do this is to work with others on getting things fixed up (this can require - persistence!) but that's fine - it's a part of kernel development. + persistence!) but that is fine - it is a part of kernel development. =20 (https://lwn.net/Articles/283982/). =20 diff --git a/Documentation/process/4.Coding.rst b/Documentation/process/4.C= oding.rst index c0f57d0c4f733..bdc389f164a0e 100644 --- a/Documentation/process/4.Coding.rst +++ b/Documentation/process/4.Coding.rst @@ -5,11 +5,11 @@ Getting the code right =20 While there is much to be said for a solid and community-oriented design process, the proof of any kernel development project is in the resulting -code. It is the code which will be examined by other developers and merged -(or not) into the mainline tree. So it is the quality of this code which +code. It is the code that will be examined by other developers and merged +(or not) into the mainline tree. So it is the quality of this code that will determine the ultimate success of the project. =20 -This section will examine the coding process. We'll start with a look at a +This section will examine the coding process. We will start with a look a= t a number of ways in which kernel developers can go wrong. Then the focus will shift toward doing things right and the tools which can help in that quest. @@ -25,7 +25,7 @@ The kernel has long had a standard coding style, describe= d in :ref:`Documentation/process/coding-style.rst `. For much of that time, the policies described in that file were taken as being, at mos= t, advisory. As a result, there is a substantial amount of code in the kernel -which does not meet the coding style guidelines. The presence of that code +that does not meet the coding style guidelines. The presence of that code leads to two independent hazards for kernel developers. =20 The first of these is to believe that the kernel coding standards do not @@ -43,7 +43,7 @@ win before the code can be merged. Putting code into the= kernel means giving up a degree of control in a number of ways - including control over how the code is formatted. =20 -The other trap is to assume that code which is already in the kernel is +The other trap is to assume that code that is already in the kernel is urgently in need of coding style fixes. Developers may start to generate reformatting patches as a way of gaining familiarity with the process, or as a way of getting their name into the kernel changelogs - or both. But @@ -82,10 +82,10 @@ But experience has shown that excessive or premature ab= straction can be just as harmful as premature optimization. Abstraction should be used to the level required and no further. =20 -At a simple level, consider a function which has an argument which is +At a simple level, consider a function that has an argument that is always passed as zero by all callers. One could retain that argument just in case somebody eventually needs to use the extra flexibility that it -provides. By that time, though, chances are good that the code which +provides. By that time, though, chances are good that the code that implements this extra argument has been broken in some subtle way which was never noticed - because it has never been used. Or, when the need for extra flexibility arises, it does not do so in a way which matches the @@ -111,12 +111,12 @@ replicating the same code throughout the kernel. The C preprocessor seems to present a powerful temptation to some C programmers, who see it as a way to efficiently encode a great deal of flexibility into a source file. But the preprocessor is not C, and heavy -use of it results in code which is much harder for others to read and +use of it results in code that is much harder for others to read and harder for the compiler to check for correctness. Heavy preprocessor use -is almost always a sign of code which needs some cleanup work. +is almost always a sign of code that needs some cleanup work. =20 Conditional compilation with #ifdef is, indeed, a powerful feature, and it -is used within the kernel. But there is little desire to see code which is +is used within the kernel. But there is little desire to see code that is sprinkled liberally with #ifdef blocks. As a general rule, #ifdef use should be confined to header files whenever possible. Conditionally-compiled code can be confined to functions which, if the code @@ -127,7 +127,7 @@ code which is easier to follow. C preprocessor macros present a number of hazards, including possible multiple evaluation of expressions with side effects and no type safety. If you are tempted to define a macro, consider creating an inline function -instead. The code which results will be the same, but inline functions are +instead. The code that results will be the same, but inline functions are easier to read, do not evaluate their arguments multiple times, and allow the compiler to perform type checking on the arguments and return value. =20 @@ -149,7 +149,7 @@ example of premature optimization. In general, kernel programmers ignore cache effects at their peril. The classic time/space tradeoff taught in beginning data structures classes often does not apply to contemporary hardware. Space *is* time, in that a -larger program will run slower than one which is more compact. +larger program will run slower than one that is more compact. =20 More recent compilers take an increasingly active role in deciding whether a given function should actually be inlined or not. So the liberal @@ -181,12 +181,12 @@ single-processor systems, work being done to improve = responsiveness will raise the level of concurrency within the kernel. The days when kernel code could be written without thinking about locking are long past. =20 -Any resource (data structures, hardware registers, etc.) which could be +Any resource (data structures, hardware registers, etc.) that could be accessed concurrently by more than one thread must be protected by a lock. New code should be written with this requirement in mind; retrofitting locking after the fact is a rather more difficult task. Kernel developers should take the time to understand the available locking primitives well -enough to pick the right tool for the job. Code which shows a lack of +enough to pick the right tool for the job. Code that shows a lack of attention to concurrency will have a difficult path into the mainline. =20 =20 @@ -194,10 +194,10 @@ Regressions *********** =20 One final hazard worth mentioning is this: it can be tempting to make a -change (which may bring big improvements) which causes something to break +change (which may bring big improvements) that causes something to break for existing users. This kind of change is called a "regression," and regressions have become most unwelcome in the mainline kernel. With few -exceptions, changes which cause regressions will be backed out if the +exceptions, changes that cause regressions will be backed out if the regression cannot be fixed in a timely manner. Far better to avoid the regression in the first place. =20 @@ -232,8 +232,8 @@ For now, at least, the writing of error-free code remai= ns an ideal that few of us can reach. What we can hope to do, though, is to catch and fix as many of those errors as possible before our code goes into the mainline kernel. To that end, the kernel developers have put together an impressive -array of tools which can catch a wide variety of obscure problems in an -automated way. Any problem caught by the computer is a problem which will +array of tools that can catch a wide variety of obscure problems in an +automated way. Any problem caught by the computer is a problem that will not afflict a user later on, so it stands to reason that the automated tools should be used whenever possible. =20 @@ -248,7 +248,7 @@ its cause. Note that not all compiler warnings are enabled by default. Build the kernel with "make KCFLAGS=3D-W" to get the full set. =20 -The kernel provides several configuration options which turn on debugging +The kernel provides several configuration options that turn on debugging features; most of these are found in the "kernel hacking" submenu. Several of these options should be turned on for any kernel used for development or testing purposes. In particular, you should turn on: @@ -259,7 +259,7 @@ testing purposes. In particular, you should turn on: =20 - DEBUG_OBJECTS will add code to track the lifetime of various objects created by the kernel and warn when things are done out of order. If - you are adding a subsystem which creates (and exports) complex objects + you are adding a subsystem that creates (and exports) complex objects of its own, consider adding support for the object debugging infrastructure. =20 @@ -288,13 +288,13 @@ locking should be run with lockdep enabled before bei= ng submitted for inclusion. =20 As a diligent kernel programmer, you will, beyond doubt, check the return -status of any operation (such as a memory allocation) which can fail. The +status of any operation (such as a memory allocation) that can fail. The fact of the matter, though, is that the resulting failure recovery paths are, probably, completely untested. Untested code tends to be broken code; you could be much more confident of your code if all those error-handling paths had been exercised a few times. =20 -The kernel provides a fault injection framework which can do exactly that, +The kernel provides a fault injection framework that can do exactly that, especially where memory allocations are involved. With fault injection enabled, a configurable percentage of memory allocations will be made to fail; these failures can be restricted to a specific range of code. @@ -348,7 +348,7 @@ understand the patch. Be sure that the changelog says = *why* the patch is worth applying; a surprising number of developers fail to provide that information. =20 -Any code which adds a new user-space interface - including new sysfs or +Any code that adds a new user-space interface - including new sysfs or /proc files - should include documentation of that interface which enables user-space developers to know what they are working with. See Documentation/ABI/README for a description of how this documentation should @@ -385,7 +385,7 @@ be accompanied by a line explaining why the barrier is = necessary. The locking rules for data structures generally need to be explained somewhere. Major data structures need comprehensive documentation in general. Non-obvious dependencies between separate bits of code should be pointed -out. Anything which might tempt a code janitor to make an incorrect +out. Anything that might tempt a code janitor to make an incorrect "cleanup" needs a comment saying why it is done the way it is. And so on. =20 =20 diff --git a/Documentation/process/5.Posting.rst b/Documentation/process/5.= Posting.rst index b8a449980452e..b33d9563f69bb 100644 --- a/Documentation/process/5.Posting.rst +++ b/Documentation/process/5.Posting.rst @@ -6,7 +6,7 @@ Posting patches Sooner or later, the time comes when your work is ready to be presented to the community for review and, eventually, inclusion into the mainline kernel. Unsurprisingly, the kernel development community has evolved a set -of conventions and procedures which are used in the posting of patches; +of conventions and procedures that are used in the posting of patches; following them will make life much easier for everybody involved. This document will attempt to cover these expectations in reasonable detail; more information can also be found in the files @@ -24,17 +24,17 @@ feedback from the community before the work is complete= . So you should consider posting in-progress work, or even making a Git tree available so that interested developers can catch up with your work at any time. =20 -When posting code which is not yet considered ready for inclusion, it is a +When posting code that is not yet considered ready for inclusion, it is a good idea to say so in the posting itself. Also mention any major work -which remains to be done and any known problems. Fewer people will look at -patches which are known to be half-baked, but those who do will come in +that remains to be done and any known problems. Fewer people will look at +patches that are known to be half-baked, but those who do will come in with the idea that they can help you drive the work in the right direction. =20 =20 Before creating patches ----------------------- =20 -There are a number of things which should be done before you consider +There are a number of things that should be done before you consider sending patches to the development community. These include: =20 - Test the code to the extent that you can. Make use of the kernel's @@ -85,12 +85,12 @@ Only the most simple changes should be formatted as a s= ingle patch; everything else should be made as a logical series of changes. Splitting up patches is a bit of an art; some developers spend a long time figuring out how to do it in the way that the community expects. There are a few -rules of thumb, however, which can help considerably: +rules of thumb, however, that can help considerably: =20 - The patch series you post will almost certainly not be the series of changes found in your working revision control system. Instead, the changes you have made need to be considered in their final form, then - split apart in ways which make sense. The developers are interested in + split apart in ways that make sense. The developers are interested in discrete, self-contained changes, not the path you took to get to those changes. =20 @@ -98,7 +98,7 @@ rules of thumb, however, which can help considerably: patch. These changes can be small ("add a field to this structure") or large (adding a significant new driver, for example), but they should be conceptually small and amenable to a one-line description. Each patch - should make a specific change which can be reviewed on its own and + should make a specific change that can be reviewed on its own and verified to do what it says it does. =20 - As a way of restating the guideline above: do not mix different types of @@ -107,7 +107,7 @@ rules of thumb, however, which can help considerably: good chance that it will be passed over and the important fix will be lost. =20 - - Each patch should yield a kernel which builds and runs properly; if your + - Each patch should yield a kernel that builds and runs properly; if your patch series is interrupted in the middle, the result should still be a working kernel. Partial application of a patch series is a common scenario when the "git bisect" tool is used to find regressions; if the @@ -115,7 +115,7 @@ rules of thumb, however, which can help considerably: users who are engaging in the noble work of tracking down problems. =20 - Do not overdo it, though. One developer once posted a set of edits - to a single file as 500 separate patches - an act which did not make him + to a single file as 500 separate patches - an act that did not make him the most popular person on the kernel mailing list. A single patch can be reasonably large as long as it still contains a single *logical* change. @@ -125,11 +125,11 @@ rules of thumb, however, which can help considerably: in the series enables the whole thing. This temptation should be avoided if possible; if that series adds regressions, bisection will finger the last patch as the one which caused the problem, even though - the real bug is elsewhere. Whenever possible, a patch which adds new + the real bug is elsewhere. Whenever possible, a patch that adds new code should make that code active immediately. =20 Working to create the perfect patch series can be a frustrating process -which takes quite a bit of time and thought after the "real work" has been +that takes quite a bit of time and thought after the "real work" has been done. When done properly, though, it is time well spent. =20 =20 @@ -137,7 +137,7 @@ Patch formatting and changelogs ------------------------------- =20 So now you have a perfect series of patches for posting, but the work is -not done quite yet. Each patch needs to be formatted into a message which +not done quite yet. Each patch needs to be formatted into a message that quickly and clearly communicates its purpose to the rest of the world. To that end, each patch will be composed of the following: =20 @@ -164,7 +164,7 @@ that end, each patch will be composed of the following: the author of the patch. Tags will be described in more detail below. =20 The items above, together, form the changelog for the patch. Writing good -changelogs is a crucial but often-neglected art; it's worth spending +changelogs is a crucial but often-neglected art; it is worth spending another moment discussing this issue. When writing a changelog, you should bear in mind that a number of different people will be reading your words. These include subsystem maintainers and reviewers who need to decide @@ -274,7 +274,7 @@ The tags in common use are: =20 Be careful in the addition of the aforementioned tags to your patches, as = all except for Cc:, Reported-by:, and Suggested-by: need explicit permission o= f the -person named. For those three implicit permission is sufficient if the per= son +person named. For those three, implicit permission is sufficient if the pe= rson contributed to the Linux kernel using that name and email address according to the lore archives or the commit history -- and in case of Reported-by: and Suggested-by: did the reporting or suggestion in public. Note, @@ -303,7 +303,7 @@ take care of: comes up with. Please bear in mind that checkpatch.pl, while being the embodiment of a fair amount of thought about what kernel patches should look like, is not smarter than you. If fixing a checkpatch.pl complaint - would make the code worse, don't do it. + would make the code worse, do not do it. =20 Patches should always be sent as plain text. Please do not send them as attachments; that makes it much harder for reviewers to quote sections of @@ -312,7 +312,7 @@ message. =20 When mailing patches, it is important to send copies to anybody who might be interested in it. Unlike some other projects, the kernel encourages -people to err on the side of sending too many copies; don't assume that the +people to err on the side of sending too many copies; do not assume that t= he relevant people will see your posting on the mailing lists. In particular, copies should go to: =20 --=20 2.50.1 (Apple Git-155) From nobody Sat Sep 26 11:01:25 2026 Received: from mail-pg1-f179.google.com (mail-pg1-f179.google.com [209.85.215.179]) (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 3A9CC3F076C for ; Wed, 2 Sep 2026 08:44:57 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.215.179 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338701; cv=none; b=qrQFKx12ZWMHCUqVKjvOk7p0EXm9NnuYDRFAoQ8CU8Ye+MOFpl5VIRFEX45VtYTl+b1NfEStJBKb5oY+6UcrUE2WXRHLq0CTbyr+JwlzU2JuaLlb+hFKisV1pru3tCf5Uie6j7nLqxMYBcz6ooIQuAYoPU3aP0Y9t0/b6bXEL6U= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338701; c=relaxed/simple; bh=hTfSR6lRRTgHCfvXNSsQon3UjqxmuaAmVRnqcmQJa+c=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version; b=Svmp0ZO9UmDcJbnXJtiBtv4jNj65OyJLQ6uV3YkZqpsg4Q52ITitoA1s1CF7QjgrDoMzwRt/gpitUfI3lBt3Bb8fQqgW2agrSVZQJ06YgGW9sB2BLj3X2rzkb7RHNpKsu8gVVJ+ufgEEPbZTokohOD0rnO/n8OQj8pQu4+oPFlo= 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=Nmkr953q; arc=none smtp.client-ip=209.85.215.179 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 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="Nmkr953q" Received: by mail-pg1-f179.google.com with SMTP id 41be03b00d2f7-cc1cc97b84bso695320a12.1 for ; Wed, 02 Sep 2026 01:44:57 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1788338696; x=1788943496; 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:content-type; bh=ezxtdztmw1JvTNP/EpaDJJlpXXjoASMUAtdTi0A+/qQ=; b=Nmkr953qrCipNecQr3UqqT0DbcASU8ViUBU7LgRz+IUMpEgfctam35LjaGJTdm+mKn pH/PPW0/MICcLJBotE1ZxVbPIj6EWSbSGalTtp9i3FoiloTnz7k97xypvXx67mRmJd5K g+BpVN5fzC5PCMHEgW3UdNCRSM1Lbkgnw3K98BwhAeBNQyGPMlyQHuykuHHOWsdzzcGb OyQsBo6Brh6BwXxmYH7S7O8tyYW3fW9hKAxOMU1LcIVNMa67G+bny6eiuW0niic/LtRT Q8gne9EVuOe0ZzielKN7uG4ADHvTxvUz9v+M51mcuLdY7wgd93BYWLA3ODugCtytD9EG KpgA== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1788338696; x=1788943496; h=content-transfer-encoding:mime-version:references:in-reply-to :message-id:date:subject:cc:to:from:x-gm-gg:x-gm-message-state:from :to:cc:subject:date:message-id:reply-to:content-type; bh=ezxtdztmw1JvTNP/EpaDJJlpXXjoASMUAtdTi0A+/qQ=; b=hS1weHvHNXuueEGoggnoWkC97qR8+dQSE4wmg80n12cT3OoiMtQpLpeHUpy3AjH6+L iRvCNC9l3I6JEmcDJw+fM6YjR/tkfAbSm8dsQ1Y2dunOLnDTx3GLhhW0B+wyWbTb/Svm LrcKTTWD/L4YkscKEb40/ecCPY2JJPRQH9YLnGyZC9eXL/esr79obJsaFKhbzBKJzHOr BahXSOOo2w5p0+BdkfTEu9eY1mUcD/uAsv6PAWMnlJVRqtrEQ1JkjKmdfT6KrT12rQFi mT44ywMu1Nkbn9UcHUC8OL9/089RhdKfXWAP3eVM4n8TNI4FO5vsFPXop3M6u32r7AFm IewA== X-Forwarded-Encrypted: i=1; AKwUvBylblHYmj3seBTdo16SNFs+N9gXLk/uqQFJvCa8L0+CVrdjNbTZwkUygA9psIl7u/NacbkcbRA1dyhTQXw=@vger.kernel.org X-Gm-Message-State: AFuF++lpR714WRSzCTqk+DJf6gVwfdyfTStZQUyg0SBFQLXLhbcPK8HZ 8jwKPB7WS3MUkRMePJ9c1Cotw211Xl6+/N8WR7QDxKRIiH7t9f5VpRvC X-Gm-Gg: AYBFou1XEOmMcA7PvCzHhh6EdgVz+m1ryrCDbW4yAwNqIoMZW+S3IzUYmCfT+GL/3kh jctGNM/37Re5zOErMGtmmPcCqPnYH08YQCjxfYXxeg7Bp6tQ32TtAxdLCMl20pMbVOWhsF2nD6x eP5vCsW2BGISdYSdB5DoEWx3XLQii2MnBylLS21G0mARCKDYB54TClBs3wEzoJfUHq5JPxC9XFt 4eds4S05mMR8UXWdbDc9UHBZGvqDl/IEUX6MzUqL+Q05/6YNOHH76XAcKgAkS+Zull8N2N0S1+n BY2ctfKcaZ/8KMayZeQlLG8Ihh2cb3qAon97+k+nkmVzLVh/0ULs1LgzcbyL6KLbhFROW8apUTd UaHrhxoCzj0FRgiXsJa4P/tEv9UNocrQt8zHDJOnbWffklHdLqQlYJQrMHTfwKV6tfymwHbeam+ BlRfOizzPI2qXYFREjSYHZ8HH3RC7jGIkje6Z0gxl5Z03bnPqD7DGFQqnSqlBLq8bK1DtDGRkpY eyTEtB83ilSgEAyC9a3e0/ZUVtDLQ== X-Received: by 2002:a17:90b:35d0:b0:398:b46d:48c0 with SMTP id 98e67ed59e1d1-39aee10890cmr5011923a91.18.1788338696036; Wed, 02 Sep 2026 01:44:56 -0700 (PDT) Received: from localhost.localdomain ([222.254.211.218]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-39ae3c6f337sm4845289a91.16.2026.09.02.01.44.51 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 02 Sep 2026 01:44:54 -0700 (PDT) From: Nguyen Duc Thinh To: Jonathan Corbet Cc: Weijie Yuan , Shuah Khan , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Nguyen Duc Thinh Subject: [PATCH v2 3/5] Documentation: process: Refine language, tone, and grammar in subsequent files Date: Wed, 2 Sep 2026 15:44:01 +0700 Message-ID: <20260902084430.17248-4-ducthinh100812@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260902084430.17248-1-ducthinh100812@gmail.com> References: <20260902084430.17248-1-ducthinh100812@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" Apply a sweep across four additional process documentation files. Expand conversational contractions to their formal forms, correct minor punctuation faults, and polish the phrasing to ensure a clear, consistent tone. Signed-off-by: Nguyen Duc Thinh --- Documentation/process/7.AdvancedTopics.rst | 32 ++++++------ Documentation/process/8.Conclusion.rst | 4 +- Documentation/process/applying-patches.rst | 20 ++++---- Documentation/process/botching-up-ioctls.rst | 54 ++++++++++---------- 4 files changed, 55 insertions(+), 55 deletions(-) diff --git a/Documentation/process/7.AdvancedTopics.rst b/Documentation/pro= cess/7.AdvancedTopics.rst index 066655e5d536c..e85a4f33795f1 100644 --- a/Documentation/process/7.AdvancedTopics.rst +++ b/Documentation/process/7.AdvancedTopics.rst @@ -5,7 +5,7 @@ Advanced topics =20 At this point, hopefully, you have a handle on how the development process works. There is still more to learn, however! This section will cover a -number of topics which can be helpful for developers wanting to become a +number of topics that can be helpful for developers wanting to become a regular part of the Linux kernel development process. =20 Managing patches with Git @@ -52,23 +52,23 @@ exercise while coming up to speed. When you are ready to start putting up Git trees for others to look at, you will, of course, need a server that can be pulled from. Setting up such a server with git-daemon is relatively straightforward if you have a system -which is accessible to the Internet. Otherwise, free, public hosting sites +that is accessible to the Internet. Otherwise, free, public hosting sites (GitHub, for example) are starting to appear on the net. Established developers can get an account on kernel.org, but those are not easy to come by; see https://kernel.org/faq/ for more information. =20 The normal Git workflow involves the use of a lot of branches. Each line of development can be separated into a separate "topic branch" and -maintained independently. Branches in Git are cheap, there is no reason to -not make free use of them. And, in any case, you should not do your -development in any branch which you intend to ask others to pull from. +maintained independently. Branches in Git are cheap, there is no reason n= ot +to make free use of them. And, in any case, you should not do your +development in any branch that you intend to ask others to pull from. Publicly-available branches should be created with care; merge in patches from development branches when they are in complete form and ready to go - not before. =20 Git provides some powerful tools which can allow you to rewrite your -development history. An inconvenient patch (one which breaks bisection, -say, or which has some other sort of obvious bug) can be fixed in place or +development history. An inconvenient patch (one that breaks bisection, +say, or that has some other sort of obvious bug) can be fixed in place or made to disappear from the history entirely. A patch series can be rewritten as if it had been written on top of today's mainline, even though you have been working on it for months. Changes can be transparently @@ -81,22 +81,22 @@ a simple obsession for the creation of the perfect proj= ect history. Rewriting history will rewrite the changes contained in that history, turning a tested (hopefully) kernel tree into an untested one. But, beyond that, developers cannot easily collaborate if they do not have a shared -view of the project history; if you rewrite history which other developers +view of the project history; if you rewrite history that other developers have pulled into their repositories, you will make life much more difficult for those developers. So a simple rule of thumb applies here: history -which has been exported to others should generally be seen as immutable +that has been exported to others should generally be seen as immutable thereafter. =20 So, once you push a set of changes to your publicly-available server, those changes should not be rewritten. Git will attempt to enforce this rule if -you try to push changes which do not result in a fast-forward merge +you try to push changes that do not result in a fast-forward merge (i.e. changes which do not share the same history). It is possible to override this check, and there may be times when it is necessary to rewrite an exported tree. Moving changesets between trees to avoid conflicts in linux-next is one example. But such actions should be rare. This is one of the reasons why development should be done in private branches (which can be rewritten if necessary) and only moved into public branches when -it's in a reasonably advanced state. +it is in a reasonably advanced state. =20 As the mainline (or other tree upon which a set of changes is based) advances, it is tempting to merge with that tree to stay on the leading @@ -109,11 +109,11 @@ generally only at specific release points (such as a = mainline -rc release). If you are nervous about specific changes, you can always perform test merges in a private branch. The git "rerere" tool can be useful in such situations; it remembers how merge conflicts were resolved -so that you don't have to do the same work twice. +so that you do not have to do the same work twice. =20 One of the biggest recurring complaints about tools like Git is this: the mass movement of patches from one repository to another makes it easy to -slip in ill-advised changes which go into the mainline below the review +slip in ill-advised changes that go into the mainline below the review radar. Kernel developers tend to get unhappy when they see that kind of thing happening; putting up a Git tree with unreviewed or off-topic patches can affect your ability to get trees pulled in the future. Quoting Linus: @@ -135,7 +135,7 @@ occasional summary of the tree to the relevant list, an= d, when the time is right, request that the tree be included in linux-next. =20 If and when others start to send patches for inclusion into your tree, -don't forget to review them. Also ensure that you maintain the correct +do not forget to review them. Also ensure that you maintain the correct authorship information; the git "am" tool does its best in this regard, but you may have to add a "From:" line to the patch if it has been relayed to you via a third party. @@ -161,7 +161,7 @@ whole. =20 Reviewing code can be an intimidating prospect, especially for a new kernel developer who may well feel nervous about questioning code - in public - -which has been posted by those with more experience. Even code written by +that has been posted by those with more experience. Even code written by the most experienced developers can be improved, though. Perhaps the best piece of advice for reviewers (all reviewers) is this: phrase review comments as questions rather than criticisms. Asking "how does the lock @@ -191,6 +191,6 @@ submission and it looks good to me." Some form of a review message or reply is obviously necessary otherwise maintainers will not know that the reviewer has looked at the patch at all! =20 -Last but not least patch review may become a negative process, focused +Last but not least, patch review may become a negative process, focused on pointing out problems. Please throw in a compliment once in a while, particularly for newbies! diff --git a/Documentation/process/8.Conclusion.rst b/Documentation/process= /8.Conclusion.rst index 8c847dffe76b2..10b6fed20a4be 100644 --- a/Documentation/process/8.Conclusion.rst +++ b/Documentation/process/8.Conclusion.rst @@ -4,7 +4,7 @@ For more information =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 There are numerous sources of information on Linux kernel development and -related topics. First among those will always be the Documentation +related topics. First among these will always be the Documentation directory found in the kernel source distribution. Start with the top-level :ref:`process/howto.rst `; also read :ref:`process/submitting-patches.rst `. Many internal @@ -56,7 +56,7 @@ Congratulations to anybody who has made it through this l= ong-winded document. Hopefully it has provided a helpful understanding of how the Linux kernel is developed and how you can participate in that process. =20 -In the end, it's the participation that matters. Any open source software +In the end, it is the participation that matters. Any open source software project is no more than the sum of what its contributors put into it. The Linux kernel has progressed as quickly and as well as it has because it has been helped by an impressively large group of developers, all of whom are diff --git a/Documentation/process/applying-patches.rst b/Documentation/pro= cess/applying-patches.rst index c269f5e1a0a3b..5b8cbf3375655 100644 --- a/Documentation/process/applying-patches.rst +++ b/Documentation/process/applying-patches.rst @@ -9,7 +9,7 @@ Original by: .. note:: =20 This document is obsolete. In most cases, rather than using ``patch`` - manually, you'll almost certainly want to look at using Git instead. + manually, you will almost certainly want to look at using Git instead. =20 A frequently asked question on the Linux Kernel Mailing List is how to app= ly a patch to the kernel or, more specifically, what base kernel a patch for @@ -28,7 +28,7 @@ A patch is a small text document containing a delta of ch= anges between two different versions of a source tree. Patches are created with the ``diff`` program. =20 -To correctly apply a patch you need to know what base it was generated from +To correctly apply a patch, you need to know what base it was generated fr= om and what new version the patch will change the source tree into. These should both be present in the patch file metadata or be possible to deduce from the filename. @@ -75,7 +75,7 @@ via stdin using the following syntax:: =20 patch -p1 < path/to/patch-x.y.z =20 -If you just want to be able to follow the examples below and don't want to +If you just want to be able to follow the examples below and do not want to know of more than one way to use patch, then you can stop reading this section here. =20 @@ -84,7 +84,7 @@ this:: =20 patch -p1 -i path/to/patch-x.y.z =20 -If your patch file is compressed with gzip or xz and you don't want to +If your patch file is compressed with gzip or xz and you do not want to uncompress it before applying it, then you can feed it to patch like this instead:: =20 @@ -104,7 +104,7 @@ patch via stdin or the ``-i`` argument, as you prefer. A few other nice arguments for patch are ``-s`` which causes patch to be s= ilent except for errors which is nice to prevent errors from scrolling out of the screen too fast, and ``--dry-run`` which causes patch to just print a list= ing of -what would happen, but doesn't actually make any changes. Finally ``--verb= ose`` +what would happen, but does not actually make any changes. Finally ``--ver= bose`` tells patch to print more information about the work being done. =20 =20 @@ -118,7 +118,7 @@ Checking that the file looks like a valid patch file an= d checking the code around the bits being modified matches the context provided in the patch a= re just two of the basic sanity checks patch does. =20 -If patch encounters something that doesn't look quite right it has two +If patch encounters something that does not look quite right it has two options. It can either refuse to apply the changes and abort or it can try to find a way to make the patch apply with a few minor changes. =20 @@ -133,7 +133,7 @@ usually adjust the line numbers and apply the patch. Whenever patch applies a patch that it had to modify a bit to make it fit it'll tell you about it by saying the patch applied with **fuzz**. You should be wary of such changes since even though patch probably got it -right it doesn't /always/ get it right, and the result will sometimes be +right it does not /always/ get it right, and the result will sometimes be wrong. =20 When patch encounters a change that it can't fix up with fuzz it rejects it @@ -141,7 +141,7 @@ outright and leaves a file with a ``.rej`` extension (a= reject file). You can read this file to see exactly what change couldn't be applied, so you can go fix it up by hand if you wish. =20 -If you don't have any third-party patches applied to your kernel source, b= ut +If you do not have any third-party patches applied to your kernel source, = but only patches from kernel.org and you apply the patches in the correct orde= r, and have made no modifications yourself to the source files, then you shou= ld never see a fuzz or reject message from patch. If you do see such messages @@ -154,7 +154,7 @@ Let's look a bit more at some of the messages patch can= produce. =20 If patch stops and presents a ``File to patch:`` prompt, then patch could = not find a file to be patched. Most likely you forgot to specify -p1 or you are -in the wrong directory. Less often, you'll find patches that need to be +in the wrong directory. Less often, you will find patches that need to be applied with ``-p0`` instead of ``-p1`` (reading the patch file should rev= eal if this is the case -- if so, then this is an error by the person who created the patch but is not fatal). @@ -412,7 +412,7 @@ tree. The Subsystem maintainers push their patches firs= t to linux-next, and, during the merge window, sends them directly to Linus. =20 The -mm patches serve as a sort of proving ground for new features and oth= er -experimental patches that aren't merged via a subsystem tree. +experimental patches that are not merged via a subsystem tree. Once such patches has proved its worth in -mm for a while Andrew pushes it on to Linus for inclusion in mainline. =20 diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/p= rocess/botching-up-ioctls.rst index a05e8401de1c7..d9f9d4450debb 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -10,8 +10,8 @@ One clear insight kernel graphics hackers gained in the p= ast few years is that trying to come up with a unified interface to manage the execution units a= nd memory on completely different GPUs is a futile effort. So nowadays every driver has its own set of ioctls to allocate memory and submit work to the= GPU. -Which is nice, since there's no more insanity in the form of fake-generic,= but -actually only used once interfaces. But the clear downside is that there's= much +Which is nice, since there is no more insanity in the form of fake-generic=20 +interfaces that are actually used only once. But the clear downside is tha= t there is much more potential to screw things up. =20 To avoid repeating all the same mistakes again I've written up some of the @@ -24,14 +24,14 @@ something every GPU driver has to do on its own. Prerequisites ------------- =20 -First the prerequisites. Without these you have already failed, because you +First, the prerequisites. Without these you have already failed, because y= ou will need to add a 32-bit compat layer: =20 * Only use fixed sized integers. To avoid conflicts with typedefs in user= space the kernel has special types like __u32, __s64. Use them. =20 * Align everything to the natural size and use explicit padding. 32-bit - platforms don't necessarily align 64-bit values to 64-bit boundaries, b= ut + platforms do not necessarily align 64-bit values to 64-bit boundaries, = but 64-bit platforms do. So we always need padding to the natural size to g= et this right. =20 @@ -58,18 +58,18 @@ pain. And since getting things wrong on the first attem= pt is guaranteed you will have a second iteration or at least an extension for any given interf= ace. =20 * Have a clear way for userspace to figure out whether your new ioctl or = ioctl - extension is supported on a given kernel. If you can't rely on old kern= els + extension is supported on a given kernel. If you cannot rely on old ker= nels rejecting the new flags/modes or ioctls (since doing that was botched i= n the past) then you need a driver feature flag or revision number somewhere. =20 * Have a plan for extending ioctls with new flags or new fields at the en= d of the structure. The drm core checks the passed-in size for each ioctl ca= ll and zero-extends any mismatches between kernel and userspace. That help= s, - but isn't a complete solution since newer userspace on older kernels wo= n't - notice that the newly added fields at the end get ignored. So this still + but is not a complete solution since newer userspace on older kernels w= on't + notice that the newly added fields at the end that get ignored. So this= still needs a new driver feature flags. =20 - * Check all unused fields and flags and all the padding for whether it's = 0, + * Check all unused fields, flags and padding to verify that they are 0, and reject the ioctl if that's not the case. Otherwise your nice plan f= or future extensions is going right down the gutters since someone will su= bmit an ioctl struct with random stack garbage in the yet unused parts. Which @@ -84,7 +84,7 @@ will have a second iteration or at least an extension for= any given interface. Fun with Error Paths -------------------- =20 -Nowadays we don't have any excuse left any more for drm drivers being neat +Nowadays we do not have any excuse left any more for drm drivers being neat little root exploits. This means we both need full input validation and so= lid error handling paths - GPUs will die eventually in the oddmost corner cases anyway: @@ -100,27 +100,27 @@ anyway: Check that the error code matches your expectations. And finally make s= ure that you only test for one single error path in each subtest by submitt= ing otherwise perfectly valid data. Without this an earlier check might rej= ect - the ioctl already and shadow the codepath you actually want to test, hi= ding + the ioctl already and shadow the code path that you actually want to te= st, hiding bugs and regressions. =20 * Make all your ioctls restartable. First X really loves signals and seco= nd this will allow you to test 90% of all error handling paths by just interrupting your main test suite constantly with signals. Thanks to X's - love for signal you'll get an excellent base coverage of all your error + love for signal you will get an excellent base coverage of all your err= or paths pretty much for free for graphics drivers. Also, be consistent wi= th how you handle ioctl restarting - e.g. drm has a tiny drmIoctl helper i= n its userspace library. The i915 driver botched this with the set_tiling ioc= tl, now we're stuck forever with some arcane semantics in both the kernel a= nd userspace. =20 - * If you can't make a given codepath restartable make a stuck task at lea= st - killable. GPUs just die and your users won't like you more if you hang = their + * If you cannot make a given codepath restartable make a stuck task at le= ast + killable. GPUs just die and your users will not like you more if you ha= ng their entire box (by means of an unkillable X process). If the state recovery= is still too tricky have a timeout or hangcheck safety net as a last-ditch effort in case the hardware has gone bananas. =20 * Have testcases for the really tricky corner cases in your error recover= y code - - it's way too easy to create a deadlock between your hangcheck code and + - it is way too easy to create a deadlock between your hangcheck code a= nd waiters. =20 =20 @@ -129,10 +129,10 @@ Time, Waiting and Missing it =20 GPUs do most everything asynchronously, so we have a need to time operatio= ns and wait for outstanding ones. This is really tricky business; at the moment n= one of -the ioctls supported by the drm/i915 get this fully right, which means the= re's -still tons more lessons to learn here. +the ioctls supported by the drm/i915 get this fully right, which means the= re are +still many lessons to learn here. =20 - * Use CLOCK_MONOTONIC as your reference time, always. It's what alsa, drm= and + * Use CLOCK_MONOTONIC as your reference time, always. It is what alsa, dr= m and v4l use by default nowadays. But let userspace know which timestamps are derived from different clock domains like your main system clock (provi= ded by the kernel) or some independent hardware counter somewhere else. Clo= cks @@ -141,8 +141,8 @@ still tons more lessons to learn here. get at the raw values of some clocks (e.g. through in-command-stream performance counter sampling instructions) consider exposing those also. =20 - * Use __s64 seconds plus __u64 nanoseconds to specify time. It's not the = most - convenient time specification, but it's mostly the standard. + * Use __s64 seconds plus __u64 nanoseconds to specify time. It is not the= most + convenient time specification, but it is mostly the standard. =20 * Check that input time values are normalized and reject them if not. Note that the kernel native struct ktime has a signed integer for both secon= ds @@ -152,7 +152,7 @@ still tons more lessons to learn here. ioctl restartable relative timeouts tend to be too coarse and can indefinitely extend your wait time due to rounding on each restart. Especially if your reference clock is something really slow like the di= splay - frame counter. With a spec lawyer hat on this isn't a bug since timeout= s can + frame counter. With a spec lawyer hat on this is not a bug since timeou= ts can always be extended - but users will surely hate you if their neat anima= tions starts to stutter due to this. =20 @@ -185,17 +185,17 @@ entails its own little set of pitfalls: explicitly. Only go with a more global per-device namespace if the obje= cts are truly device-unique. One counterexample in the drm modeset interfac= es is that the per-device modeset objects like connectors share a namespace w= ith - framebuffer objects, which mostly are not shared at all. A separate + framebuffer objects that are generally not shared at all. A separate namespace, private by default, for framebuffers would have been more suitable. =20 * Think about uniqueness requirements for userspace handles. E.g. for mos= t drm - drivers it's a userspace bug to submit the same object twice in the same + drivers it is a userspace bug to submit the same object twice in the sa= me command submission ioctl. But then if objects are shareable userspace n= eeds to know whether it has seen an imported object from a different process - already or not. I haven't tried this myself yet due to lack of a new cl= ass + already or not. I have not tried this myself yet due to lack of a new c= lass of objects, but consider using inode numbers on your shared file descri= ptors - as unique identifiers - it's how real files are told apart, too. + as unique identifiers - it is how real files are told apart, too. Unfortunately this requires a full-blown virtual filesystem in the kern= el. =20 =20 @@ -205,10 +205,10 @@ Last, but not Least Not every problem needs a new ioctl: =20 * Think hard whether you really want a driver-private interface. Of course - it's much quicker to push a driver-private interface than engaging in + it is much quicker to push a driver-private interface than engaging in lengthy discussions for a more generic solution. And occasionally doing= a private interface to spearhead a new concept is what's required. But in= the - end, once the generic interface comes around you'll end up maintaining = two + end, once the generic interface comes around you will end up maintainin= g two interfaces. Indefinitely. =20 * Consider other interfaces than ioctls. A sysfs attribute is much better= for @@ -218,7 +218,7 @@ Not every problem needs a new ioctl: disclaimer of not having a stable ABI would be better. =20 Finally, the name of the game is to get it right on the first attempt, sin= ce if -your driver proves popular and your hardware platforms long-lived then you= 'll +your driver proves popular and your hardware platforms long-lived then you= will be stuck with a given ioctl essentially forever. You can try to deprecate horrible ioctls on newer iterations of your hardware, but generally it tak= es years to accomplish this. And then again years until the last user able to --=20 2.50.1 (Apple Git-155) From nobody Sat Sep 26 11:01:25 2026 Received: from mail-pj1-f43.google.com (mail-pj1-f43.google.com [209.85.216.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 B812B3F1AB7 for ; Wed, 2 Sep 2026 08:45:02 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.216.43 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338704; cv=none; b=r3fSRcCXvSrsC8LBFbKWT/f6dFXtkw2k7wN09G95CG5HAxU1isrcrdZdD0KeQO0qaAiR7pb0v+7X0Hak43C+pWQOWfLy5GLpzkGyOqmYp0nUlpRfoEb0yN+FkL/RfPxdnr9pLYXdmDqGnCXB12Tc2ybENoJ6CDg24VgsP60W6oM= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338704; c=relaxed/simple; bh=FgKjhz3mUeEjERAksccr4wk8eWplMtPAxYkqd3ZlHP4=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=dTdq3jizlETdUBh4INFw0fk1do0DVYFF4yxJE/Ut56IRti0qHhZSsfHU9pbXAJSK5MpiMp37YBVR2kCYYfqGrmp/8TrRPmLbIbc2Gll5EY+rdnIVrU8IH+IdKk4byqFSGLKC0Th8f97Ac3U6f00CrMkOEmiIPT+7lKQQHCJ+1UI= 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=U2bWowsY; arc=none smtp.client-ip=209.85.216.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 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="U2bWowsY" Received: by mail-pj1-f43.google.com with SMTP id 98e67ed59e1d1-38e58034d05so647295a91.2 for ; Wed, 02 Sep 2026 01:45:02 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1788338702; x=1788943502; darn=vger.kernel.org; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:from:to:cc:subject :date:message-id:reply-to:content-type; bh=sEzbEUhsLIbV0F6Tu7BYGASiUv49dSXTrGmhReWfJSU=; b=U2bWowsY4mtRhL/iO6NihP8BP5r/wGiYwn1nBQPQBRFQaW4IG1WTT+vifYJkJJ4SE3 lI6qU/nrgty/DSbB2HuaSb7NNLi8v90heBu9JwwB0t2g1oR3rXMvBypHJy2mDsKd1DY/ ZwvVzlqULZiLpUJ2qYaVhHTTeFofFH4abciAGJ+wh7VAxopcZ8xvZPsN785+FCw52VLm R4NJkPrCzqX7LFrhi8F5QMEjKxUZPPAMRkLZdsQH4Yz2+lzTjPRyzQxqL2nVu/E2Mz1X iw82bYiqr7OUtVKvwaM+oBAGYjkWjcG+zDTsyiAEPYLfor+jyITrWHUp2th2z7cBbP4M VAeQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1788338702; x=1788943502; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=sEzbEUhsLIbV0F6Tu7BYGASiUv49dSXTrGmhReWfJSU=; b=X/4Kl3tlFl2qYWxVIVKCgWoMSFn3BlP/2hP22Z004AOj30GZbVd5i0B6fQTxP9SH2i IPZhTrNXkOOL7+LXytRowoqV8gPmoS0lVt3MklnS+beN3c3WphhRro0RX/JxrukmKTYT dLfpeoKLyBcB+VBaFckaW2aPP1k0x3PSmZkd0Ujgn/umckBQhYyDY03M7+dC3awy88DL dF3iIbxX4fA4qCPUfeV6SycNGShejXrV1oDKCTg1Q7cLcpkcMX18duif9wFQuyyEGBd9 Z6mu0s0GGnItq9E1zhIrE/1wS3pWPY1Aoh0yChq0+2dhSLThP/u1Y9z2hjSQ3NczQECb askA== X-Forwarded-Encrypted: i=1; AKwUvBzCiWsuZc60TZ8KSi0zeW7NP5f5rJ+lhH0aEkmst5ruYG9IejoyJh+roeT4A1kjndUiRaz5l0kigWz9yYU=@vger.kernel.org X-Gm-Message-State: AFuF++lHwXnH6/0gBmwPDahado+ZQrvUUr8Uk8tllYvcSPZVHCuv6qVG mIMOyg9jD3HVFEBc/BoMGDXgtK7lI83De1iDyYScmymVLlCVQScEuCGxAhWpn3Rt X-Gm-Gg: AYBFou3wSDZ9/r1wMfteYwkpOaC+vBR4TsmAFGIzbzabPj93iLjZfjy0HnmKl1C+VMf aClj34oxxvAerezgJtisuUXuYnhNN9j4A2XjTtdTslIkfRuwGU3UqmDneZTVBfX18Pt4I+sHqso /zEHYxpUh/cVTIijgPPS/wRmFMgF3t5aGqWI+/Hi/RA+UwlbTrCQbWDCdpnJqiBH75gWC6pj7NH hvLqs7RLrzDFEwZZvS6cjwidNv3CrraWXgb72D76w8jNq38rWvPaZLls9YbbFbvwKlPFFzznQpX 18kd9MNXSryq8SIi4Wa7aN6lO1C6p1r7JcKwn4//W35IeRE1OktzGEWUJWcziMt66Ajw0XGi5NY nfTKDxAcKEtdOtnPxzgS70q0FnbIHLtOgXBm565eSIBZ1paL07UrnImKBP9tM0NEcC2mzCSocbW 7zW+bOKtLwSlJAfeOxvuJXymwBtGNCy5W7VLKCzAvX/r/0Bw6msyMyF6R3BfBSAkV9AlaWOexPw MnYqV34t1a1N0HE55w= X-Received: by 2002:a17:90b:55ce:b0:395:4de5:1054 with SMTP id 98e67ed59e1d1-39aee066e9fmr5203335a91.16.1788338702036; Wed, 02 Sep 2026 01:45:02 -0700 (PDT) Received: from localhost.localdomain ([222.254.211.218]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-39ae3c6f337sm4845289a91.16.2026.09.02.01.44.58 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 02 Sep 2026 01:45:01 -0700 (PDT) From: Nguyen Duc Thinh To: Jonathan Corbet Cc: Weijie Yuan , Shuah Khan , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Nguyen Duc Thinh Subject: [PATCH v2 4/5] Documentation: process: Refine language, tone, and grammar in subsequent files Date: Wed, 2 Sep 2026 15:44:02 +0700 Message-ID: <20260902084430.17248-5-ducthinh100812@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260902084430.17248-1-ducthinh100812@gmail.com> References: <20260902084430.17248-1-ducthinh100812@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Conduct a sweep across four more process documentation files. Replace informal contractions with formal expressions and fix minor grammatical bugs to ensure a highly professional and accessible tone. Signed-off-by: Nguyen Duc Thinh --- Documentation/process/botching-up-ioctls.rst | 2 +- Documentation/process/changes.rst | 20 +++++++++---------- .../code-of-conduct-interpretation.rst | 14 ++++++------- Documentation/process/code-of-conduct.rst | 2 +- 4 files changed, 19 insertions(+), 19 deletions(-) diff --git a/Documentation/process/botching-up-ioctls.rst b/Documentation/p= rocess/botching-up-ioctls.rst index d9f9d4450debb..186749c443fcd 100644 --- a/Documentation/process/botching-up-ioctls.rst +++ b/Documentation/process/botching-up-ioctls.rst @@ -65,7 +65,7 @@ will have a second iteration or at least an extension for= any given interface. * Have a plan for extending ioctls with new flags or new fields at the en= d of the structure. The drm core checks the passed-in size for each ioctl ca= ll and zero-extends any mismatches between kernel and userspace. That help= s, - but is not a complete solution since newer userspace on older kernels w= on't + but is not a complete solution since newer userspace on older kernels w= ill not notice that the newly added fields at the end that get ignored. So this= still needs a new driver feature flags. =20 diff --git a/Documentation/process/changes.rst b/Documentation/process/chan= ges.rst index 0aa232b117b54..f9957a5d46edb 100644 --- a/Documentation/process/changes.rst +++ b/Documentation/process/changes.rst @@ -17,14 +17,14 @@ Axel Boldt, Alessandro Sigala, and countless other user= s all over the Current Minimal Requirements **************************** =20 -Upgrade to at **least** these software revisions before thinking you've -encountered a bug! If you're unsure what version you're currently +Upgrade to at **least** these software revisions before thinking you have +encountered a bug! If you are unsure what version you are currently running, the suggested command should tell you. For a list of the programs -on your system including their version execute ./scripts/ver_linux +on your system, including their versions, execute ./scripts/ver_linux =20 Again, keep in mind that this list assumes you are already functionally running a Linux kernel. Also, not all tools are necessary on all -systems; obviously, if you don't have any PC Card hardware, for example, +systems; obviously, if you do not have any PC Card hardware, for example, you probably do not need to concern yourself with pcmciautils. =20 =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D @@ -83,7 +83,7 @@ Clang/LLVM (optional) =20 The latest formal release of clang and LLVM utils (according to `releases.llvm.org `_) are supported for buildi= ng -kernels. Older releases aren't guaranteed to work, and we may drop workaro= unds +kernels. Older releases are not guaranteed to work, and we may drop workar= ounds from the kernel that were used to support older versions. Please see addit= ional docs on :ref:`Building Linux with Clang/LLVM `. =20 @@ -222,7 +222,7 @@ documentation via specially-formatted comments near the= ir definitions in the source. These comments can be combined with ReST files in the Documentation/ directory to make enriched documentation, whic= h can then be converted to PostScript, HTML, LaTex, ePUB and PDF files. -In order to convert from ReST format to a format of your choice, you'll ne= ed +In order to convert from ReST format to a format of your choice, you will = need Sphinx. =20 Util-linux @@ -231,13 +231,13 @@ Util-linux New versions of util-linux provide ``fdisk`` support for larger disks, support new options to mount, recognize more supported partition types, and similar goodies. -You'll probably want to upgrade. +You will probably want to upgrade. =20 Ksymoops -------- =20 If the unthinkable happens and your kernel oopses, you may need the -ksymoops tool to decode it, but in most cases you don't. +ksymoops tool to decode it, but in most cases you do not. It is generally preferred to build the kernel with ``CONFIG_KALLSYMS`` so that it produces readable dumps that can be used as-is (this also produces better output than ksymoops). If for some reason your kernel @@ -255,7 +255,7 @@ E2fsprogs --------- =20 The latest version of ``e2fsprogs`` fixes several bugs in fsck and -debugfs. Obviously, it's a good idea to upgrade. +debugfs. Obviously, it is a good idea to upgrade. =20 JFSutils -------- @@ -306,7 +306,7 @@ udev you may need to:: mknod /dev/cpu/microcode c 10 184 chmod 0644 /dev/cpu/microcode =20 -as root before you can use this. You'll probably also want to +as root before you can use this. You will probably also want to get the user-space microcode_ctl utility to use with this. =20 udev diff --git a/Documentation/process/code-of-conduct-interpretation.rst b/Doc= umentation/process/code-of-conduct-interpretation.rst index 4cdef83606986..2f070ca1880ec 100644 --- a/Documentation/process/code-of-conduct-interpretation.rst +++ b/Documentation/process/code-of-conduct-interpretation.rst @@ -47,7 +47,7 @@ regarding conduct issues. =20 Maintainers should be willing to help when problems occur, and work with others in the community when needed. Do not be afraid to reach out to -the Technical Advisory Board (TAB) or other maintainers if you're +the Technical Advisory Board (TAB) or other maintainers if you are uncertain how to handle situations that come up. It will not be considered a violation report unless you want it to be. If you are uncertain about approaching the TAB or any other maintainers, please @@ -78,7 +78,7 @@ rejecting unsuitable contributions are not viewed as a vi= olation of the Code of Conduct. =20 While maintainers are in general welcoming to newcomers, their capacity -of helping contributors overcome the entry hurdles is limited, so they +to help contributors overcome the entry hurdles is limited, so they have to set priorities. This, also, is not to be seen as a violation of the Code of Conduct. The kernel community is aware of that and provides entry level programs in various forms like kernelnewbies.org. @@ -123,8 +123,8 @@ Enforcement =20 The address listed in the Code of Conduct goes to the Code of Conduct Committee. The exact members receiving these emails at any given time -are listed at https://kernel.org/code-of-conduct.html. Members can not -access reports made before they joined or after they have left the +are listed at https://kernel.org/code-of-conduct.html. Members cannot +access reports submitted before they joined or after they left the committee. =20 The Code of Conduct Committee consists of volunteer community members @@ -147,7 +147,7 @@ Any decisions regarding enforcement recommendations wil= l be brought to the TAB for implementation of enforcement with the relevant maintainers if needed. Once the TAB approves one or more of the measures outlined in the scope of the ban by two-thirds of the members voting for the -measures, the Code of Conduct Committee will enforce the TAB approved +measures, the Code of Conduct Committee will enforce the TAB-approved measures. Any Code of Conduct Committee members serving on the TAB will not vote on the measures. =20 @@ -177,7 +177,7 @@ Unacceptable behaviors often get resolved when individu= als acknowledge their behavior and make amends for it in the setting the violation has taken pla= ce. =20 The Code of Conduct Committee receives reports about unacceptable behaviors -when they don't get resolved through community discussions. The Code of +when they do not get resolved through community discussions. The Code of Conduct committee takes measures to restore productive and respectful collaboration when an unacceptable behavior has negatively impacted that relationship. @@ -237,7 +237,7 @@ administrators. Any Code of Conduct Committee members = serving on the TAB will not vote on the measures. =20 The Code of Conduct Committee is mindful of the negative impact of seeking -public apology and instituting ban could have on individuals. It is also +a public apology and instituting a ban could have on individuals. It is al= so mindful of the longer term harm to the community that could result from not taking action when such serious public violations occur. =20 diff --git a/Documentation/process/code-of-conduct.rst b/Documentation/proc= ess/code-of-conduct.rst index be50294aebd5d..e5e29c068f2b5 100644 --- a/Documentation/process/code-of-conduct.rst +++ b/Documentation/process/code-of-conduct.rst @@ -34,7 +34,7 @@ Examples of unacceptable behavior by participants include: * Public or private harassment * Publishing others=E2=80=99 private information, such as a physical or el= ectronic address, without explicit permission -* Other conduct which could reasonably be considered inappropriate in a +* Other conduct that could reasonably be considered inappropriate in a professional setting =20 =20 --=20 2.50.1 (Apple Git-155) From nobody Sat Sep 26 11:01:25 2026 Received: from mail-pl1-f178.google.com (mail-pl1-f178.google.com [209.85.214.178]) (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 046383783A0 for ; Wed, 2 Sep 2026 08:45:08 +0000 (UTC) Authentication-Results: smtp.subspace.kernel.org; arc=none smtp.client-ip=209.85.214.178 ARC-Seal: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338711; cv=none; b=enhnUbqFF3uTw+A10JWftecxg44O6HlV5ROOs6UToePL6LdFasntN5aLB33SpRVnkR0+8pSlrPEeH5MwaAqbXjjzeSlVQktmXAauwzuCD9/RYZGqUMY+AmzEk+cmSxcZ/OS5do/XNGm1jZcYwL8xQ4dOnZITx3EPSRrNFTjUP+I= ARC-Message-Signature: i=1; a=rsa-sha256; d=subspace.kernel.org; s=arc-20240116; t=1788338711; c=relaxed/simple; bh=xEZzpXeTW3vt1wTKKg79W/ieHGqqg0JRMuz4PZPsyC0=; h=From:To:Cc:Subject:Date:Message-ID:In-Reply-To:References: MIME-Version:Content-Type; b=GXI6NSgGWNM1cMcM/MMz6pJdp0T2fo5ge7iqq89Iks20awO48aASPv8qDzdMX0W19LpROu4DAlKHoCZelDAxLhoBEE718/1FQmFvGiHrnk4wfUZUxHwokfZSi0gBlw/dUzDhM1LLCvbNgrGfWH+xBqOjlVoDI0qqNjHz7SgKQf4= 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=qqQ9EVyj; arc=none smtp.client-ip=209.85.214.178 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 Authentication-Results: smtp.subspace.kernel.org; dkim=pass (2048-bit key) header.d=gmail.com header.i=@gmail.com header.b="qqQ9EVyj" Received: by mail-pl1-f178.google.com with SMTP id d9443c01a7336-2d9004f39d3so8759745ad.2 for ; Wed, 02 Sep 2026 01:45:08 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20251104; t=1788338708; x=1788943508; darn=vger.kernel.org; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:from:to:cc:subject :date:message-id:reply-to:content-type; bh=XTSGldNko/7onAQ09Dd0jKeRKM/xfLS6joKjag2qTGs=; b=qqQ9EVyjBJmLAS9SdpF8w8U5nnyxJS3CxjOCtcZ1JFf05enDhqR+0H1L1Qg0Q8aJ2d gILegmPdJ+2enajT2Q94+12ApZWU+QWJC/LOQo4yMBhECjvDrWQOBeu/yYUg+SXOoUoh JWv2+50RPsDo4etCp8KVvMdv7FrJgO/DSMywbTCMoB1jZQEeumvCgUSVbYgLwwQs+pk3 vDju+aI7ax5QD9IEYnN0ghPES4iwSw/R8Yu7JfNVKh6ai8UKNUcmqNFF0wWBZCgSDJvz bjSDFo+5E4ZCgYtnd3FXnlaAiQWRM8KWaDwGzeLcFIQm1cIkdmRV1p90cTJd/2wjuiiA yQVQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1788338708; x=1788943508; h=content-transfer-encoding:content-type:mime-version:references :in-reply-to:message-id:date:subject:cc:to:from:x-gm-gg :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to :content-type; bh=XTSGldNko/7onAQ09Dd0jKeRKM/xfLS6joKjag2qTGs=; b=pBAgqV38BnFI+nbrz8UJmFNhV5J8uPb3zR3kQ/udXgod0U7cjtjTztd/C0NIC1dhJv zdDCWepTzTEncLAgYY/wvtv9yLjnw/zebFRTRJPY7cKc+d+erf71lT2+cMNuGmXnSWok maS5JlH8HB5aBKdYIOJWDZZUmeuaLaHCxsOcSxc9hx9glgrCvg+Vp5jEvnmDThSbqS2Y Sz9TdBAX+PfI7wIybaEdsQCjAJRpEcGWEHXvFdGNOXs4KKhNJA5EPTlpNWL+ZZH1Tjxf XFmYU/B2E1kzfdZ8reAS8pfoP00+58L+c/pOinV8gqIMFR7xVQnN84o3LvO0jlFUBJHk +KFw== X-Forwarded-Encrypted: i=1; AKwUvByHyy87fzEqW7QgsKxtTnosyftl/qU/763tG/+ABUxdkXwV6fEZHqhYUN9/oUrp+DkmpK+QxJMOssdOc0c=@vger.kernel.org X-Gm-Message-State: AFuF++lg2vTL1CYZEvASp5Nevy6gBGrTQdgmf4fSOUY3lvvpioCURS0O eO0s/vX1BieRq9pOhpDQ3yEWKZPh8qYMZGWJNN9Wcy+rbvfkvVHn7ffg X-Gm-Gg: AYBFou2ulsj4rGYB19rWCYurTAfhxEwhwwNkw+zRMUtyCKiAggDNDhgVZB72UqCl+qx P0L5QXDF3Svj5Gk5SBYckpoOUXNnk1KGYm8IP6CRRhepH+RGIX3/ZlhgJQ4yRfLsOptpv/WxzH5 uWTFUHIkwuMiSsUlj2mgJKJTAqzcTgADG00Ng0DpNSNzaaJ+esZOfijTnrMFO0+CCt99vk9VgBw 9Co7ZW+xnP8uNmI+rfDk7E953Juy/69koej3iCquk6qo0YZpzGHg5RZTVjZcCxo8Zv/RRsH+nQh LnEwFptraVA5lXEe4/MUNe1v1o8wOd1rHcp673abKGtYoVLLVo6fremIxK4q6yx249q3R0gXr2Y P2MUoBboMZSB9bNFkgkybzjaP9BkuOXEMt5lgE9zOs7tfPThfY1yOs9ejtYyxYBk+p6GVWOM9Ah FRAMe617EcuXswqTziAW3E8MOkmlXdWTFbF+gdhdMh8rNBFD/eiUkzx9K1alBjo4Q4j/Wqf8/6y NxYwBCibCjWSbZXC/M= X-Received: by 2002:a17:90a:e7c9:b0:398:9bd4:d12 with SMTP id 98e67ed59e1d1-39aee219f45mr4475927a91.17.1788338707963; Wed, 02 Sep 2026 01:45:07 -0700 (PDT) Received: from localhost.localdomain ([222.254.211.218]) by smtp.gmail.com with ESMTPSA id 98e67ed59e1d1-39ae3c6f337sm4845289a91.16.2026.09.02.01.45.04 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 02 Sep 2026 01:45:07 -0700 (PDT) From: Nguyen Duc Thinh To: Jonathan Corbet Cc: Weijie Yuan , Shuah Khan , Randy Dunlap , workflows@vger.kernel.org, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, Nguyen Duc Thinh Subject: [PATCH v2 5/5] Documentation: process: Clean up grammar and tone across multiple files Date: Wed, 2 Sep 2026 15:44:03 +0700 Message-ID: <20260902084430.17248-6-ducthinh100812@gmail.com> X-Mailer: git-send-email 2.50.1 In-Reply-To: <20260902084430.17248-1-ducthinh100812@gmail.com> References: <20260902084430.17248-1-ducthinh100812@gmail.com> Precedence: bulk X-Mailing-List: linux-kernel@vger.kernel.org List-Id: List-Subscribe: List-Unsubscribe: MIME-Version: 1.0 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Perform an extensive pass across eight process documentation files. Expand conversational contractions to their formal equivalents, correct minor punctuation faults, and polish the writing style to ensure a clear, consistent tone. Signed-off-by: Nguyen Duc Thinh --- Documentation/process/backporting.rst | 68 +++++++++---------- Documentation/process/coding-assistants.rst | 12 ++-- Documentation/process/conclave.rst | 6 +- .../process/contribution-maturity-model.rst | 4 +- Documentation/process/cve.rst | 8 +-- Documentation/process/deprecated.rst | 14 ++-- Documentation/process/development-process.rst | 6 +- Documentation/process/email-clients.rst | 32 ++++----- 8 files changed, 75 insertions(+), 75 deletions(-) diff --git a/Documentation/process/backporting.rst b/Documentation/process/= backporting.rst index abc5f8925a789..1ba583c89b973 100644 --- a/Documentation/process/backporting.rst +++ b/Documentation/process/backporting.rst @@ -28,14 +28,14 @@ Applying the patch to a tree =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D =20 Sometimes the patch you are backporting already exists as a git commit, -in which case you just cherry-pick it directly using +in that case you just cherry-pick it directly using ``git cherry-pick``. However, if the patch comes from an email, as it often does for the Linux kernel, you will need to apply it to a tree using ``git am``. =20 -If you've ever used ``git am``, you probably already know that it is +If you have ever used ``git am``, you probably already know that it is quite picky about the patch applying perfectly to your source tree. In -fact, you've probably had nightmares about ``.rej`` files and trying to +fact, you have probably had nightmares about ``.rej`` files and trying to edit the patch to make it apply. =20 It is strongly recommended to instead find an appropriate base version @@ -47,9 +47,9 @@ apply a patch that just arrived on LKML to an older stabl= e kernel, you can apply it to the most recent mainline kernel and then cherry-pick it to your older stable branch. =20 -It's generally better to use the exact same base as the one the patch -was generated from, but it doesn't really matter that much as long as it -applies cleanly and isn't too far from the original base. The only +It is generally better to use the exact same base as the one the patch +was generated from, but it does not really matter that much as long as it +applies cleanly and is not too far from the original base. The only problem with applying the patch to the "wrong" base is that it may pull in more unrelated changes in the context of the diff when cherry-picking it to the older branch. @@ -70,7 +70,7 @@ article will assume that you are doing a plain ``git cher= ry-pick``. .. _b4 presentation: https://youtu.be/mF10hgVIx9o?t=3D2996 =20 Once you have the patch in Git, you can go ahead and cherry-pick it into -your source tree. Don't forget to cherry-pick with ``-x`` if you want a +your source tree. Do not forget to cherry-pick with ``-x`` if you want a written record of where the patch came from! =20 Note that if you are submitting a patch for stable, the format is @@ -93,8 +93,8 @@ Uh-oh; the cherry-pick failed with a vaguely threatening = message:: What to do now? =20 In general, conflicts appear when the context of the patch (i.e., the -lines being changed and/or the lines surrounding the changes) doesn't -match what's in the tree you are trying to apply the patch *to*. +lines being changed and/or the lines surrounding the changes) does not +match what is in the tree you are trying to apply the patch *to*. =20 For backports, what likely happened was that the branch you are backporting from contains patches not in the branch you are backporting @@ -113,7 +113,7 @@ editor or using a dedicated conflict resolution tool. Many people prefer to use their regular text editor and edit the conflict directly, as it may be easier to understand what you're doing and to control the final result. There are definitely pros and cons to -each method, and sometimes there's value in using both. +each method, and sometimes there is value in using both. =20 We will not cover using dedicated merge tools here beyond providing some pointers to various tools that you could use: @@ -144,7 +144,7 @@ simply diverged -- perhaps your older branch had some o= ther backports applied to it that themselves needed conflict resolutions, causing a divergence. =20 -It's important to always identify the commit or commits that caused the +It is important to always identify the commit or commits that caused the conflict, as otherwise you cannot be confident in the correctness of your resolution. As an added bonus, especially if the patch is in an area you're not that familiar with, the changelogs of these commits will @@ -155,7 +155,7 @@ git log ~~~~~~~ =20 A good first step is to look at ``git log`` for the file that has the -conflict -- this is usually sufficient when there aren't a lot of +conflict -- this is usually sufficient when there are not a lot of patches to the file, but may get confusing if the file is big and frequently patched. You should run ``git log`` on the range of commits between your currently checked-out branch (``HEAD``) and the parent of @@ -164,7 +164,7 @@ the patch you are picking (````), i.e.:: git log HEAD..^ -- =20 Even better, if you want to restrict this output to a single function -(because that's where the conflict appears), you can use the following +(because that is where the conflict appears), you can use the following syntax:: =20 git log -L:'\': HEAD..^ @@ -236,8 +236,8 @@ not be incidental at all and you need to carefully cons= ider whether the patch adding the function should be cherry-picked first. =20 If you find that there is a necessary prerequisite patch, then you need -to stop and cherry-pick that instead. If you've already resolved some -conflicts in a different file and don't want to do it again, you can +to stop and cherry-pick that instead. If you have already resolved some +conflicts in a different file and do not want to do it again, you can create a temporary copy of that file. =20 To abort the current cherry-pick, go ahead and run @@ -250,7 +250,7 @@ Understanding conflict markers Combined diffs ~~~~~~~~~~~~~~ =20 -Let's say you've decided against picking (or reverting) additional +Let's say you have decided against picking (or reverting) additional patches and you just want to resolve the conflict. Git will have inserted conflict markers into your file. Out of the box, this will look something like:: @@ -365,10 +365,10 @@ part of the conflict, leaving the file essentially un= changed, and apply the changes by hand. Perhaps the patch is changing a function call argument from ``0`` to ``1`` while a conflicting change added an entirely new (and insignificant) parameter to the end of the parameter -list; in that case, it's easy enough to change the argument from ``0`` +list; in that case, it is easy enough to change the argument from ``0`` to ``1`` by hand and leave the rest of the arguments alone. This technique of manually applying changes is mostly useful if the conflict -pulled in a lot of unrelated context that you don't really need to care +pulled in a lot of unrelated context that you do not really need to care about. =20 For particularly nasty conflicts with many conflict markers, you can use @@ -382,14 +382,14 @@ Dealing with file renames =20 One of the most annoying things that can happen while backporting a patch is discovering that one of the files being patched has been -renamed, as that typically means Git won't even put in conflict markers, +renamed, as that typically means Git will not even put in conflict markers, but will just throw up its hands and say (paraphrased): "Unmerged path! You do the work..." =20 There are generally a few ways to deal with this. If the patch to the renamed file is small, like a one-line change, the easiest thing is to just go ahead and apply the change by hand and be done with it. On the -other hand, if the change is big or complicated, you definitely don't +other hand, if the change is big or complicated, you definitely do not want to do it by hand. =20 As a first pass, you can try something like this, which will lower the @@ -400,7 +400,7 @@ an add-delete pair to be a potential rename):: git cherry-pick -strategy=3Drecursive -Xrename-threshold=3D30 =20 Sometimes the right thing to do will be to also backport the patch that -did the rename, but that's definitely not the most common case. Instead, +did the rename, but that is definitely not the most common case. Instead, what you can do is to temporarily rename the file in the branch you're backporting to (using ``git mv`` and committing the result), restart the attempt to cherry-pick the patch, rename the file back (``git mv`` and @@ -416,7 +416,7 @@ Gotchas Function arguments ~~~~~~~~~~~~~~~~~~ =20 -Pay attention to changing function arguments! It's easy to gloss over +Pay attention to changing function arguments! It is easy to gloss over details and think that two lines are the same but actually they differ in some small detail like which variable was passed as an argument (especially if the two variables are both a single character that look @@ -438,7 +438,7 @@ other patches. A good way to ensure that you review the error paths is to always use ``git diff -W`` and ``git show -W`` (AKA ``--function-context``) when inspecting your changes. For C code, this will show you the whole -function that's being changed in a patch. One of the things that often +function that is being changed in a patch. One of the things that often go wrong during backports is that something else in the function changed on either of the branches that you're backporting from or to. By including the whole function in the diff you get more context and can @@ -453,22 +453,22 @@ function. When backporting patches to an area where s= uch a refactoring has taken place, you effectively need to do the reverse when backporting: a patch to a single location may need to be applied to multiple locations in the backported version. (One giveaway for this -scenario is that a function was renamed -- but that's not always the +scenario is that a function was renamed -- but that is not always the case.) =20 -To avoid incomplete backports, it's worth trying to figure out if the +To avoid incomplete backports, it is worth trying to figure out if the patch fixes a bug that appears in more than one place. One way to do this would be to use ``git grep``. (This is actually a good idea to do in general, not just for backports.) If you do find that the same kind -of fix would apply to other places, it's also worth seeing if those -places exist upstream -- if they don't, it's likely the patch may need +of fix would apply to other places, it is also worth seeing if those +places exist upstream -- if they do not, it is likely the patch may need to be adjusted. ``git log`` is your friend to figure out what happened -to these areas as ``git blame`` won't show you code that has been +to these areas as ``git blame`` will not show you code that has been removed. =20 If you do find other instances of the same pattern in the upstream tree -and you're not sure whether it's also a bug, it may be worth asking the -patch author. It's not uncommon to find new bugs during backporting! +and you're not sure whether it is also a bug, it may be worth asking the +patch author. It is not uncommon to find new bugs during backporting! =20 Verifying the result =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D @@ -513,17 +513,17 @@ and running the patched kernel (or program). Build testing ------------- =20 -We won't cover runtime testing here, but it can be a good idea to build +We will not cover runtime testing here, but it can be a good idea to build just the files touched by the patch as a quick sanity check. For the Linux kernel you can build single files like this, assuming you have the ``.config`` and build environment set up correctly:: =20 make path/to/file.o =20 -Note that this won't discover linker errors, so you should still do a +Note that this will not discover linker errors, so you should still do a full build after verifying that the single file compiles. By compiling the single file first you can avoid having to wait for a full build *in -case* there are compiler errors in any of the files you've changed. +case* there are compiler errors in any of the files you have changed. =20 Runtime testing --------------- @@ -571,7 +571,7 @@ format:: Signed-off-by: =20 The "Upstream commit" line is sometimes slightly different depending on -the stable version. Older version used this format:: +the stable version. Older versions used this format:: =20 commit upstream. =20 diff --git a/Documentation/process/coding-assistants.rst b/Documentation/pr= ocess/coding-assistants.rst index 051f0d819f68e..f01c15afe6fe4 100644 --- a/Documentation/process/coding-assistants.rst +++ b/Documentation/process/coding-assistants.rst @@ -15,7 +15,7 @@ kernel development process: * Documentation/process/coding-style.rst * Documentation/process/submitting-patches.rst =20 -For guidelines on content generated by AI coding assistants see: +For guidelines on content generated by AI coding assistants, see: =20 * Documentation/process/generated-content.rst =20 @@ -73,12 +73,12 @@ these steps: the report to be ignored, as many unverified bug reports sent to mainta= iners happen to be invalid. Stop here if it finally looks wrong. 4. Write a fix for the bug. This part is not optional: except in a few very - rare cases, an AI assistant able to find a bug is able to fix it. Note = that - fixes written in the same session as used to find the bug will generally - lead to better and more accurate fixes as the LLM's reasoning context - remains present. + rare cases, an AI assistant capable of finding a bug is capable of fixi= ng it.=20 + Fixes written within the same session used to identify the bug will=20 + generally lead to better and more accurate fixes as the LLM's reasoning=20 + context remains present. 5. Build and verify that the fix works either using the reproducer or by - re-running a complete analysis; drop any fix that doesn't work and try + re-running a complete analysis; drop any fix that does not work and try another one. The fix must not add build warnings and must pass the checkpatch.pl checks (see submitting-patches.rst). 6. Commit the working fix with a detailed message describing the problem, = the diff --git a/Documentation/process/conclave.rst b/Documentation/process/con= clave.rst index 6a1234f546124..44324d285ed49 100644 --- a/Documentation/process/conclave.rst +++ b/Documentation/process/conclave.rst @@ -33,9 +33,9 @@ Technical Advisory Board (TAB) Chair as a backup. the expectation that it maximizes the long term health of the project and its community. =20 -- Within two weeks, a representative of this group will communicate to the - broader community, using the ksummit@lists.linux.dev mailing list, what - the next steps will be. +- Within two weeks, a representative of this group will communicate the=20 + next steps to the broader community via the ksummit@lists.linux.dev + mailing list. =20 The Linux Foundation, as guided by the TAB, will take the steps necessary to support and implement this plan. diff --git a/Documentation/process/contribution-maturity-model.rst b/Docume= ntation/process/contribution-maturity-model.rst index b87ab34de22ce..8b7e9ab6c9e82 100644 --- a/Documentation/process/contribution-maturity-model.rst +++ b/Documentation/process/contribution-maturity-model.rst @@ -11,7 +11,7 @@ Background As a part of the 2021 Linux Kernel Maintainers=E2=80=99 Summit, there was a `discussion `_ about the challenges in recruiting kernel maintainers as well as maintainer succession. Some of -the conclusions from that discussion included that companies which are a +the conclusions from that discussion included that companies that are a part of the Linux Kernel community need to allow engineers to be maintainers as part of their job, so they can grow into becoming respected leaders and eventually, kernel maintainers. To support a @@ -65,7 +65,7 @@ Level 3 authored by engineers from other companies) as part of their job responsibilities * Contributing presentations or papers to Linux-related or academic - conferences (such those organized by the Linux Foundation, Usenix, + conferences (such as those organized by the Linux Foundation, Usenix, ACM, etc.), are considered part of an engineer=E2=80=99s work. * A Software Engineer=E2=80=99s community contributions will be considered= in promotion and performance reviews. diff --git a/Documentation/process/cve.rst b/Documentation/process/cve.rst index 5e2753eff7294..69b20b2ecfb25 100644 --- a/Documentation/process/cve.rst +++ b/Documentation/process/cve.rst @@ -33,11 +33,11 @@ for CVE number assignments and have CVE numbers automat= ically assigned to them. These assignments are published on the linux-cve-announce mailing list as announcements on a frequent basis. =20 -Note, due to the layer at which the Linux kernel is in a system, almost +Note, due to the layer where the Linux kernel is in a system, almost any bug might be exploitable to compromise the security of the kernel, but the possibility of exploitation is often not evident when the bug is fixed. Because of this, the CVE assignment team is overly cautious and -assign CVE numbers to any bugfix that they identify. This +assigns CVE numbers to any bugfix that they identify. This explains the seemingly large number of CVEs that are issued by the Linux kernel team. =20 @@ -53,7 +53,7 @@ process<../process/security-bugs>`. No CVEs will be automatically assigned for unfixed security issues in the Linux kernel; assignment will only automatically happen after a fix is available and applied to a stable kernel tree, and it will be tracked -that way by the git commit id of the original fix. If anyone wishes to +by the Git commit ID of the original fix. If anyone wishes to have a CVE assigned before an issue is resolved with a commit, please contact the kernel CVE assignment team at to get an identifier assigned from their batch of reserved identifiers. @@ -83,7 +83,7 @@ If a security issue is found in a Linux kernel that is on= ly supported by a Linux distribution due to the changes that have been made by that distribution, or due to the distribution supporting a kernel version that is no longer one of the kernel.org supported releases, then a CVE -can not be assigned by the Linux kernel CVE team, and must be asked for +cannot be assigned by the Linux kernel CVE team, and must be asked for from that Linux distribution itself. =20 Any CVE that is assigned against the Linux kernel for an actively diff --git a/Documentation/process/deprecated.rst b/Documentation/process/d= eprecated.rst index 22a5e62c92eaf..b8f15c761ed08 100644 --- a/Documentation/process/deprecated.rst +++ b/Documentation/process/deprecated.rst @@ -9,7 +9,7 @@ Deprecated Interfaces, Language Features, Attributes, and C= onventions In a perfect world, it would be possible to convert all instances of some deprecated API into the new API and entirely remove the old API in a single development cycle. However, due to the size of the kernel, the -maintainership hierarchy, and timing, it's not always feasible to do these +maintainership hierarchy, and timing, it is not always feasible to do these kinds of conversions at once. This means that new instances may sneak into the kernel while old ones are being removed, only making the amount of work to remove the API grow. In order to educate developers about what @@ -20,12 +20,12 @@ kernel. __deprecated ------------ While this attribute does visually mark an interface as deprecated, -it `does not produce warnings during builds any more +it `does not produce warnings during builds anymore `_ because one of the standing goals of the kernel is to build without -warnings and no one was actually doing anything to remove these deprecated +warnings and no effort was made to remove these deprecated interfaces. While using `__deprecated` is nice to note an old API in -a header file, it isn't the full solution. Such interfaces must either +a header file, it is not the full solution. Such interfaces must either be fully removed from the kernel, or added to this file to discourage others from using them in the future. =20 @@ -206,8 +206,8 @@ Implicit switch case fall-through --------------------------------- The C language allows switch cases to fall through to the next case when a "break" statement is missing at the end of a case. This, however, -introduces ambiguity in the code, as it's not always clear if the missing -break is intentional or a bug. For example, it's not obvious just from +introduces ambiguity in the code, as it is not always clear if the missing +break is intentional or a bug. For example, it is not obvious just from looking at the code if `STATE_ONE` is intentionally designed to fall through into `STATE_TWO`:: =20 @@ -266,7 +266,7 @@ size problems:: struct foo items[0]; }; =20 -But this led to other problems, and didn't solve some problems shared by +But this led to other problems, and did not solve some problems shared by both styles, like not being able to detect when such an array is accidenta= lly being used _not_ at the end of a structure (which could happen directly, or when such a struct was in unions, structs of structs, etc). diff --git a/Documentation/process/development-process.rst b/Documentation/= process/development-process.rst index e34d7da58b7ff..6c40831bf45f7 100644 --- a/Documentation/process/development-process.rst +++ b/Documentation/process/development-process.rst @@ -4,12 +4,12 @@ A guide to the Kernel Development Process =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D= =3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D=3D =20 The purpose of this document is to help developers (and their managers) -work with the development community with a minimum of frustration. It is -an attempt to document how this community works in a way which is +work with the development community with a minimum of frustration. It is +an attempt to document how this community works in a way that is accessible to those who are not intimately familiar with Linux kernel development (or, indeed, free software development in general). While there is some technical material here, this is very much a process-oriented -discussion which does not require a deep knowledge of kernel programming to +discussion that does not require a deep knowledge of kernel programming to understand. =20 .. toctree:: diff --git a/Documentation/process/email-clients.rst b/Documentation/proces= s/email-clients.rst index b5377630a648a..88246203a9e99 100644 --- a/Documentation/process/email-clients.rst +++ b/Documentation/process/email-clients.rst @@ -25,7 +25,7 @@ attachments, but then the attachments should have content= -type it makes quoting portions of the patch more difficult in the patch review process. =20 -It's also strongly recommended that you use plain text in your email body, +It is also strongly recommended that you use plain text in your email body, for patches and other emails alike. https://useplaintext.email may be usef= ul for information on how to configure your preferred email client, as well as listing recommended email clients should you not already have a preference. @@ -34,10 +34,10 @@ Email clients that are used for Linux kernel patches sh= ould send the patch text untouched. For example, they should not modify or delete tabs or spaces, even at the beginning or end of lines. =20 -Don't send patches with ``format=3Dflowed``. This can cause unexpected +Do not send patches with ``format=3Dflowed``. This can cause unexpected and unwanted line breaks. =20 -Don't let your email client do automatic word wrapping for you. +Do not let your email client do automatic word wrapping for you. This can also corrupt your patch. =20 Email clients should not modify the character set encoding of the text. @@ -50,14 +50,14 @@ headers so that mail threading is not broken. =20 Copy-and-paste (or cut-and-paste) usually does not work for patches because tabs are converted to spaces. Using xclipboard, xclip, and/or -xcutsel may work, but it's best to test this for yourself or just avoid +xcutsel may work, but it is best to test this for yourself or just avoid copy-and-paste. =20 -Don't use PGP/GPG signatures in mail that contains patches. +Do not use PGP/GPG signatures in mail that contains patches. This breaks many scripts that read and apply the patches. (This should be fixable.) =20 -It's a good idea to send a patch to yourself, save the received message, +It is a good idea to send a patch to yourself, save the received message, and successfully apply it with 'patch' before sending patches to Linux mailing lists. =20 @@ -86,7 +86,7 @@ In the :menuselection:`Sending Preferences` section: - :menuselection:`Strip Whitespace Before Sending` must be ``disabled`` =20 When composing the message, the cursor should be placed where the patch -should appear, and then pressing `CTRL-R` let you specify the patch file +should appear, and then pressing `CTRL-R` lets you specify the patch file to insert into the message. =20 Claws Mail (GUI) @@ -180,7 +180,7 @@ Mutt (TUI) =20 Plenty of Linux developers use ``mutt``, so it must work pretty well. =20 -Mutt doesn't come with an editor, so whatever editor you use should be +Mutt does not come with an editor, so whatever editor you use should be used in a way that there are no automatic linebreaks. Most editors have an :menuselection:`insert file` option that inserts the contents of a file unaltered. @@ -208,7 +208,7 @@ to send them:: Config options: =20 It should work with default settings. -However, it's a good idea to set the ``send_charset`` to:: +However, it is a good idea to set the ``send_charset`` to:: =20 set send_charset=3D"us-ascii:utf-8" =20 @@ -266,9 +266,9 @@ Sylpheed (GUI) - Works well for inlining text (or using attachments). - Allows use of an external editor. - Is slow on large folders. -- Won't do TLS SMTP auth over a non-SSL connection. +- Will not do TLS SMTP auth over a non-SSL connection. - Has a helpful ruler bar in the compose window. -- Adding addresses to address book doesn't understand the display name +- Adding addresses to address book does not understand the display name properly. =20 Thunderbird (GUI) @@ -283,7 +283,7 @@ you need to restart Thunderbird. - Allow use of an external editor: =20 The easiest thing to do with Thunderbird and patches is to use extensions - which open your favorite external editor. + that open your favorite external editor. =20 Here are some example extensions which are capable of doing this. =20 @@ -294,7 +294,7 @@ you need to restart Thunderbird. https://addons.thunderbird.net/en-GB/thunderbird/addon/external-editor= -revived/ =20 It requires installing a "native messaging host". - Please read the wiki which can be found here: + Please read the wiki that can be found here: https://github.com/Frederick888/external-editor-revived/wiki =20 - "External Editor" @@ -317,7 +317,7 @@ you need to restart Thunderbird. =20 To beat some sense out of the internal editor, do this: =20 -- Edit your Thunderbird config settings so that it won't use ``format=3Dfl= owed``! +- Edit your Thunderbird config settings so that it will not use ``format= =3Dflowed``! Go to your main window and find the button for your main dropdown menu. :menuselection:`Main Menu-->Preferences-->General-->Config Editor...` to bring up the thunderbird's registry editor. @@ -333,7 +333,7 @@ To beat some sense out of the internal editor, do this: =20 to control this registry on the fly. =20 -- Don't write HTML messages! Go to the main window +- Do not write HTML messages! Go to the main window :menuselection:`Main Menu-->Account Settings-->youracc@server.something-= ->Composition & Addressing`! There you can disable the option "Compose messages in HTML format". =20 @@ -362,7 +362,7 @@ HacKerMaiL (TUI) **************** =20 HacKerMaiL (hkml) is a public-inbox based simple mails management tool that -doesn't require subscription of mailing lists. It is developed and mainta= ined +does not require subscription of mailing lists. It is developed and maint= ained by the DAMON maintainer and aims to support simple development workflows f= or DAMON and general kernel subsystems. Refer to the README (https://github.com/sjp38/hackermail/blob/master/README.md) for details. --=20 2.50.1 (Apple Git-155)