[libvirt] [PATCH] docs: point out git send-email location, be more stern about make check

[Laine Stump]

An email came to libvir-list wondering why the git send-email command
was missing in spite of having git installed; this is due to the
send-email command being in a sub-package of the main git package.

While touching the hacking file, I thought it would be useful to 1)
indicate the location of the source (docs/hacking.html.in) in the
message at the top of HACKING, and also to make the note about running
"make check" and "make syntax-check" a bit more stern.
---
 HACKING              | 22 ++++++++++++++--------
 docs/hacking.html.in | 29 ++++++++++++++++++-----------
 docs/hacking2.xsl    |  3 ++-
 3 files changed, 34 insertions(+), 20 deletions(-)

diff --git a/HACKING b/HACKING
index 804d54c..ab1a329 100644
--- a/HACKING
+++ b/HACKING
@@ -1,5 +1,6 @@
 -*- buffer-read-only: t -*- vi: set ro:
-DO NOT EDIT THIS FILE!  IT IS GENERATED AUTOMATICALLY!
+DO NOT EDIT THIS FILE!  IT IS GENERATED AUTOMATICALLY
+from docs/hacking.html.in!
 
 
 
@@ -32,11 +33,14 @@ Then, when you want to post your patches:
 
   git pull --rebase
   (fix any conflicts)
-  git send-email --cover-letter --no-chain-reply-to --annotate --to=libvir-list at redhat.com master
+  git send-email --cover-letter --no-chain-reply-to --annotate \
+                 --to=libvir-list at redhat.com master
 
-For a single patch you can omit "--cover-letter", but series of a two or more
-patches needs a cover letter. If you get tired of typing
-"--to=libvir-list at redhat.com" designation you can set it in git config:
+(Note that the "git send-email" subcommand is usually not in the main git
+package, but part of a sub-package called "git-email".) For a single patch you
+can omit "--cover-letter", but series of a two or more patches needs a cover
+letter. If you get tired of typing "--to=libvir-list at redhat.com" designation
+you can set it in git config:
 
   git config sendemail.to libvir-list at redhat.com
 
@@ -56,9 +60,11 @@ though).
 (3) Split large changes into a series of smaller patches, self-contained if
 possible, with an explanation of each patch and an explanation of how the
 sequence of patches fits together. Moreover, please keep in mind that it's
-required to be able to compile cleanly after each patch. A feature does not
-have to work until the end of a series, as long as intermediate patches don't
-cause test-suite failures.
+required to be able to compile cleanly (*including* "make check" and "make
+syntax-check") after each patch. A feature does not have to work until the end
+of a series, but intermediate patches must compile and not cause test-suite
+failures (this is to preserve the usefulness of "git bisect", among other
+things).
 
 
 
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index ca02669..1917b78 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -31,11 +31,15 @@
 <pre>
   git pull --rebase
   (fix any conflicts)
-  git send-email --cover-letter --no-chain-reply-to --annotate --to=libvir-list at redhat.com master
-</pre>
-        <p>For a single patch you can omit <code>--cover-letter</code>, but
-        series of a two or more patches needs a cover letter. If you get tired
-        of typing <code>--to=libvir-list at redhat.com</code> designation you can
+  git send-email --cover-letter --no-chain-reply-to --annotate \
+                 --to=libvir-list at redhat.com master
+</pre>
+        <p>(Note that the "git send-email" subcommand is usually not
+        in the main git package, but part of a sub-package called
+        "git-email".) For a single patch you can omit
+        <code>--cover-letter</code>, but series of a two or more
+        patches needs a cover letter. If you get tired of typing
+        <code>--to=libvir-list at redhat.com</code> designation you can
         set it in git config:</p>
 <pre>
   git config sendemail.to libvir-list at redhat.com
@@ -55,12 +59,15 @@
       </li>
 
       <li><p>Split large changes into a series of smaller patches,
-        self-contained if possible, with an explanation of each patch and an
-        explanation of how the sequence of patches fits together. Moreover,
-        please keep in mind that it's required to be able to compile cleanly
-        after each patch.  A feature does not have to work until the end of a
-        series, as long as intermediate patches don't cause test-suite
-        failures.</p>
+        self-contained if possible, with an explanation of each patch
+        and an explanation of how the sequence of patches fits
+        together. Moreover, please keep in mind that it's required to
+        be able to compile cleanly (<b>including</b> <code>make
+        check</code> and <code>make syntax-check</code>) after each
+        patch.  A feature does not have to work until the end of a
+        series, but intermediate patches must compile and not cause
+        test-suite failures (this is to preserve the usefulness
+        of <code>git bisect</code>, among other things).</p>
       </li>
 
       <li>Make sure your patches apply against libvirt GIT.  Developers
diff --git a/docs/hacking2.xsl b/docs/hacking2.xsl
index 89e777b..cd1712c 100644
--- a/docs/hacking2.xsl
+++ b/docs/hacking2.xsl
@@ -18,7 +18,8 @@
 
 <xsl:template match="/">
 <xsl:text>-*- buffer-read-only: t -*- vi: set ro:
-DO NOT EDIT THIS FILE!  IT IS GENERATED AUTOMATICALLY!
+DO NOT EDIT THIS FILE!  IT IS GENERATED AUTOMATICALLY
+from docs/hacking.html.in!
 
 
 
-- 
1.7.11.4