From 703832299190d088e3b71e1546864001d9bffb9d Mon Sep 17 00:00:00 2001 From: Laine Stump Date: Thu, 6 Sep 2012 13:21:21 -0400 Subject: [PATCH] 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. --- HACKING | 22 ++++++++++++++-------- docs/hacking.html.in | 28 ++++++++++++++++++---------- docs/hacking2.xsl | 3 ++- 3 files changed, 34 insertions(+), 19 deletions(-) diff --git a/HACKING b/HACKING index 804d54c841..ab1a329085 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@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 ca02669058..eb799532c2 100644 --- a/docs/hacking.html.in +++ b/docs/hacking.html.in @@ -31,11 +31,16 @@ 
   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 +

(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 + --cover-letter, but a series of 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
@@ -55,12 +60,15 @@
       
 
       
  • 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.
    
+        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 (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).
    
       
    • 
 
       
  • Make sure your patches apply against libvirt GIT.  Developers
diff --git a/docs/hacking2.xsl b/docs/hacking2.xsl
index 89e777b0ea..cd1712c050 100644
--- a/docs/hacking2.xsl
+++ b/docs/hacking2.xsl
@@ -18,7 +18,8 @@
 
 
 -*- 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!