Message ID | 20230510183423.never.877-kees@kernel.org (mailing list archive) |
---|---|
State | Superseded |
Headers | show |
Series | docs: submitting-patches: Discuss interleaved replies | expand |
On Wed, May 10, 2023 at 11:34:26AM -0700, Kees Cook wrote: > 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@lwn.net> > Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> > Cc: Thorsten Leemhuis <linux@leemhuis.info> > Cc: Rong Tao <rtoax@foxmail.com> > Cc: Lukas Bulwahn <lukas.bulwahn@gmail.com> > Cc: Zhangfei Gao <zhangfei.gao@foxmail.com> > Cc: linux-doc@vger.kernel.org > Cc: linux-hardening@vger.kernel.org > Signed-off-by: Kees Cook <keescook@chromium.org> > --- > Documentation/process/submitting-patches.rst | 23 ++++++++++++++++++++ > 1 file changed, 23 insertions(+) > > diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst > index eac7167dce83..3e838da8822f 100644 > --- a/Documentation/process/submitting-patches.rst > +++ b/Documentation/process/submitting-patches.rst > @@ -326,6 +326,29 @@ explaining difference aganst previous submission (see > See Documentation/process/email-clients.rst for recommendations on email > clients and mailing list etiquette. > > +Use trimmed interleaved replies in email discussions > +---------------------------------------------------- > +Top-posting is strongly discouraged in Linux kernel development > +discusions. 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 replies 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 > Yes!!! Acked-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
On 10.05.23 20:34, Kees Cook wrote: > 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. Thx for doing this. > [...] > --- > Documentation/process/submitting-patches.rst | 23 ++++++++++++++++++++ > 1 file changed, 23 insertions(+) For some reason we have duplicate code^w documentation for this, hence I'd say the same or a similar text should also be added to one of the filed in Documentation/process/[0-9].*rst ; from a quick Documentation/process/6.Followthrough.rst might be the best one. Maybe in fact the text should move there and submitting-patches.rst should have a much shorter version, as it's meant to be the terser of the two docs about this. > diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst > index eac7167dce83..3e838da8822f 100644 > --- a/Documentation/process/submitting-patches.rst > +++ b/Documentation/process/submitting-patches.rst > @@ -326,6 +326,29 @@ explaining difference aganst previous submission (see > See Documentation/process/email-clients.rst for recommendations on email > clients and mailing list etiquette. > > +Use trimmed interleaved replies in email discussions > +---------------------------------------------------- > +Top-posting is strongly discouraged in Linux kernel development > +discusions. Interleaved (or "inline") replies make conversations much s/discusions/discussions/ > +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 replies easier to find, and saves time and Nitpicking, feel free to ignore: maybe "s/replies/responses/" or something like that, as at least my stupid brain accidentally thought of the email reply (as whole) when reading this for the first time. > +space. For more details see: http://daringfireball.net/2007/07/on_top > [...] Ciao, Thorsten
On Thu, May 11, 2023 at 11:21:36AM +0200, Thorsten Leemhuis wrote: > On 10.05.23 20:34, Kees Cook wrote: > > 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. > > Thx for doing this. > > > [...] > > --- > > Documentation/process/submitting-patches.rst | 23 ++++++++++++++++++++ > > 1 file changed, 23 insertions(+) > > For some reason we have duplicate code^w documentation for this, hence > I'd say the same or a similar text should also be added to one of the > filed in Documentation/process/[0-9].*rst ; from a quick > Documentation/process/6.Followthrough.rst might be the best one. > > Maybe in fact the text should move there and submitting-patches.rst > should have a much shorter version, as it's meant to be the terser of > the two docs about this. Hm, The place where it is mentioned is even shorter, so I kind of like it in submittingpatches. But, I'm open to whatever seems best. I just want to have a URL to point people at, and I'm usually pointing to places in submittingpatches. :) > > > diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst > > index eac7167dce83..3e838da8822f 100644 > > --- a/Documentation/process/submitting-patches.rst > > +++ b/Documentation/process/submitting-patches.rst > > @@ -326,6 +326,29 @@ explaining difference aganst previous submission (see > > See Documentation/process/email-clients.rst for recommendations on email > > clients and mailing list etiquette. > > > > +Use trimmed interleaved replies in email discussions > > +---------------------------------------------------- > > +Top-posting is strongly discouraged in Linux kernel development > > +discusions. Interleaved (or "inline") replies make conversations much > > s/discusions/discussions/ Agh, thanks. Fixed. > > > +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 replies easier to find, and saves time and > > Nitpicking, feel free to ignore: maybe "s/replies/responses/" or > something like that, as at least my stupid brain accidentally thought of > the email reply (as whole) when reading this for the first time. Yeah, that is more readable. Fixed. > > +space. For more details see: http://daringfireball.net/2007/07/on_top > > [...] > > Ciao, Thorsten Thanks!
On 11.05.23 20:37, Kees Cook wrote: > On Thu, May 11, 2023 at 11:21:36AM +0200, Thorsten Leemhuis wrote: >> On 10.05.23 20:34, Kees Cook wrote: >>> 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. >> >> Thx for doing this. >> >>> [...] >>> --- >>> Documentation/process/submitting-patches.rst | 23 ++++++++++++++++++++ >>> 1 file changed, 23 insertions(+) >> >> For some reason we have duplicate code^w documentation for this, hence >> I'd say the same or a similar text should also be added to one of the >> filed in Documentation/process/[0-9].*rst ; from a quick >> Documentation/process/6.Followthrough.rst might be the best one. >> >> Maybe in fact the text should move there and submitting-patches.rst >> should have a much shorter version, as it's meant to be the terser of >> the two docs about this. > > Hm, The place where it is mentioned is even shorter, Ohh, it is mentioned there already? I briefly looked, but had missed it. Sorry. :-/ > so I kind of like > it in submittingpatches. But, I'm open to whatever seems best. Guess that is Jonathan's call to make. Your v2 patch to me looks a bit like adding quite a bit of new and slow code to the fast path while adjusting faster code in the slow path. But the relation and interaction between those two texts in a bit messy already, so maybe it doesn't matter that much. Ciao, Thorsten
diff --git a/Documentation/process/submitting-patches.rst b/Documentation/process/submitting-patches.rst index eac7167dce83..3e838da8822f 100644 --- a/Documentation/process/submitting-patches.rst +++ b/Documentation/process/submitting-patches.rst @@ -326,6 +326,29 @@ explaining difference aganst previous submission (see See Documentation/process/email-clients.rst for recommendations on email clients and mailing list etiquette. +Use trimmed interleaved replies in email discussions +---------------------------------------------------- +Top-posting is strongly discouraged in Linux kernel development +discusions. 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 replies 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
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@lwn.net> Cc: Greg Kroah-Hartman <gregkh@linuxfoundation.org> Cc: Thorsten Leemhuis <linux@leemhuis.info> Cc: Rong Tao <rtoax@foxmail.com> Cc: Lukas Bulwahn <lukas.bulwahn@gmail.com> Cc: Zhangfei Gao <zhangfei.gao@foxmail.com> Cc: linux-doc@vger.kernel.org Cc: linux-hardening@vger.kernel.org Signed-off-by: Kees Cook <keescook@chromium.org> --- Documentation/process/submitting-patches.rst | 23 ++++++++++++++++++++ 1 file changed, 23 insertions(+)