linux-kernel - [PATCH v2] docs: submitting-patches: Discuss interleaved replies

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [thread-next>] [day] [month] [year] [list]

Message-Id: <20230511184131.gonna.399-kees@kernel.org>
Date:   Thu, 11 May 2023 11:41:35 -0700
From:   Kees Cook <keescook@...omium.org>
To:     Jonathan Corbet <corbet@....net>
Cc:     Kees Cook <keescook@...omium.org>,
        Thorsten Leemhuis <linux@...mhuis.info>,
        Rong Tao <rtoax@...mail.com>,
        Lukas Bulwahn <lukas.bulwahn@...il.com>,
        Zhangfei Gao <zhangfei.gao@...mail.com>,
        linux-doc@...r.kernel.org, linux-hardening@...r.kernel.org,
        Greg Kroah-Hartman <gregkh@...uxfoundation.org>,
        Tyler Hicks <code@...icks.com>,
        Nick Desaulniers <ndesaulniers@...gle.com>,
        Jiri Kosina <jikos@...nel.org>,
        Matthieu Baerts <matthieu.baerts@...sares.net>,
        Krzysztof Kozlowski <krzysztof.kozlowski@...aro.org>,
        Xujun Leng <lengxujun2007@....com>,
        linux-kernel@...r.kernel.org
Subject: [PATCH v2] docs: submitting-patches: Discuss interleaved replies

Top-posting has been strongly discouraged in Linux development, but this
was actually not written anywhere in the common documentation about
sending patches and replying to reviews. Add a section about trimming
and interleaved replies.

Cc: Jonathan Corbet <corbet@....net>
Cc: Thorsten Leemhuis <linux@...mhuis.info>
Cc: Rong Tao <rtoax@...mail.com>
Cc: Lukas Bulwahn <lukas.bulwahn@...il.com>
Cc: Zhangfei Gao <zhangfei.gao@...mail.com>
Cc: linux-doc@...r.kernel.org
Cc: linux-hardening@...r.kernel.org
Acked-by: Greg Kroah-Hartman <gregkh@...uxfoundation.org>
Signed-off-by: Kees Cook <keescook@...omium.org>
---
v2:
 - rewrite 2.Process.rst to be postive and link to new section.
 - fix typos and phrasing (Thorsten)
 - add missing "::" for block quotes
 - add Greg's Ack
v1: https://lore.kernel.org/lkml/20230510183423.never.877-kees@kernel.org
---
 Documentation/process/2.Process.rst          |  7 +++---
 Documentation/process/submitting-patches.rst | 25 ++++++++++++++++++++
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/Documentation/process/2.Process.rst b/Documentation/process/2.Process.rst
index 6a919cffcbfd..9ab58a0d4fac 100644
--- a/Documentation/process/2.Process.rst
+++ b/Documentation/process/2.Process.rst
@@ -434,9 +434,10 @@ There are a few hints which can help with linux-kernel survival:
   questions.  Some developers can get impatient with people who clearly
   have not done their homework.
 
-- Avoid top-posting (the practice of putting your answer above the quoted
-  text you are responding to).  It makes your response harder to read and
-  makes a poor impression.
+- Use interleaved ("inline") replies, which makes your response easier to
+  read. (i.e. avoid top-posting -- the practice of putting your answer above
+  the quoted text you are responding to.) For more details, see
+  :ref:`Documentation/process/submittingpatches.rst <interleaved_replies>`.
 
 - Ask on the correct mailing list.  Linux-kernel may be the general meeting
   point, but it is not the best place to find developers from all
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst
index 486875fd73c0..efac910e2659 100644
--- a/Documentation/process/submitting-patches.rst
+++ b/Documentation/process/submitting-patches.rst
@@ -331,6 +331,31 @@ explaining difference against previous submission (see
 See Documentation/process/email-clients.rst for recommendations on email
 clients and mailing list etiquette.
 
+.. _interleaved_replies:
+
+Use trimmed interleaved replies in email discussions
+----------------------------------------------------
+Top-posting is strongly discouraged in Linux kernel development
+discussions. Interleaved (or "inline") replies make conversations much
+easier to follow. For more details see:
+https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
+
+As is frequently quoted on the mailing list::
+
+  A: http://en.wikipedia.org/wiki/Top_post
+  Q: Were do I find info about this thing called top-posting?
+  A: Because it messes up the order in which people normally read text.
+  Q: Why is top-posting such a bad thing?
+  A: Top-posting.
+  Q: What is the most annoying thing in e-mail?
+
+Similarly, please trim all unneeded quotations that aren't relevant
+to your reply. This makes responses easier to find, and saves time and
+space. For more details see: http://daringfireball.net/2007/07/on_top ::
+
+  A: No.
+  Q: Should I include quotations after my reply?
+
 .. _resend_reminders:
 
 Don't get discouraged - or impatient
-- 
2.34.1