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

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.

diff --git a/HACKING b/HACKING
index 804d54c841bdbd2ae1a671102963e9ed053704f9..ab1a329085336456fa75f5e88902edb473be6d65 100644 (file)
--- 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@redhat.com master
+  git send-email --cover-letter --no-chain-reply-to --annotate \
+                 --to=libvir-list@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@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@redhat.com" designation
+you can set it in git config:
 
   git config sendemail.to libvir-list@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 ca026690584509210611aaf1d26a5ce7a2180bd2..eb799532c2d54b2b30c3329ee1122d6726f0c61b 100644 (file)
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -31,11 +31,16 @@
 <pre>
   git pull --rebase
   (fix any conflicts)
-  git send-email --cover-letter --no-chain-reply-to --annotate --to=libvir-list@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@redhat.com</code> designation you can
+  git send-email --cover-letter --no-chain-reply-to --annotate \
+                 --to=libvir-list@redhat.com master
+</pre>
+        <p>(Note that the "git send-email" subcommand may not be in
+        the main git package and using it may require installion of a
+        separate package, for example the "git-email" package in
+        Fedora.)  For a single patch you can omit
+        <code>--cover-letter</code>, but a series of two or more
+        patches needs a cover letter. If you get tired of typing
+        <code>--to=libvir-list@redhat.com</code> designation you can
         set it in git config:</p>
 <pre>
   git config sendemail.to libvir-list@redhat.com
@@ -55,12 +60,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 89e777b0eaa0955d2174057ab903ac82eaeb3a49..cd1712c050fc6a69f06fa03da81418b5a0baf90a 100644 (file)
--- 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!