From eed71ee0db0141d05b3ab86016658f705f06667c Mon Sep 17 00:00:00 2001
From: Michael Kerrisk <mtk.manpages@gmail.com>
Date: Sat, 28 Aug 2021 01:21:19 +0200
Subject: patches.html: Various minor improvements to instructions on patch
 submission

Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>
---
 patches.html | 48 ++++++++++++++++++++++++++++++++++++++----------
 1 file changed, 38 insertions(+), 10 deletions(-)

diff --git a/patches.html b/patches.html
index 437e0c7..aa4812b 100644
--- a/patches.html
+++ b/patches.html
@@ -95,19 +95,47 @@ patches |
     [patch] shmop.2: Add "(void *)" cast to RETURN VALUE </pre>
   </li>
   <li>
-      For <strong>nontrivial patches</strong>:
+      <strong>PLEASE NOTE</strong>: for <strong>nontrivial patches</strong>,
+      you can save the maintainers a <em>lot</em> of time by attending
+      to the following:
       <br>
       <br>
   </li>
   <ul>
       <li>
-      <strong>Describe how you obtained the information in your patch</strong>:
-      was it by reading (or
-      writing) the relevant kernel or (g)libc source code; by writing a
-      test program (send it with the patch, if you want, and if it is clear and
-      simple to use); from a standards document;
-      from other documentation; from a mailing list or online forum
-      (please provide a URL if possible)?
+          <strong>Describe how you obtained the information in your patch</strong>.
+          For example, was it:
+      <ul>
+      <li>
+          by reading (or writing) the relevant kernel or (g)libc source code?
+          (please provide a pointer to the relevant code)
+      </li>
+      <li>
+          from a commit message in the kernel or (g)libc
+          source code repository?
+          (please provide a commit ID)
+      </li>
+      <li>
+          by writing a test program?
+          (send it with the patch, but please make sure it is as simple
+          as possible,
+          and provide instructions on how to use and/or a demo run)
+      </li>
+      <li>
+          from a standards document?
+          (please name the standard and quote the relevant text)
+      </li>
+      <li>
+          from other documentation?
+          (please provide a pointer to that documentation)
+      </li>
+      <li>
+          from a mailing list or online forum?
+          (please provide a URL if possible)
+      </li>
+      </ul>
+      The more information that you can provide, the easier you make it
+      for the maintainers and others to review your patch.
       <br>
       <br>
     </li>
@@ -124,7 +152,7 @@ patches |
     </li>
   
     <li>
-      <strong>Please attempt to find and CC relevant developers.</strong>
+      <strong>Please CC relevant developers.</strong>
       If your patch documents a substantial feature or change, and you
       know which developers added the feature or made the change
       that your patch documents, please CC them on the patch;
@@ -139,7 +167,7 @@ patches |
     </li>
 
     <li>
-      <strong>Please consider CCing relevant mailing lists</strong>.
+      <strong>Please CC relevant mailing lists</strong>.
       If your patch documents a substantial feature or change, please
       consider CCing relevant mailing lists on your patch.
       With luck, subscribers on the mailing list might review your patch.
-- 
cgit v1.2.3