4:44 a.m.
We should really advise (new) developers to send rebased patches
that apply cleanly and use git-send-email rather than all other
obscure ways.
---
diff to v2:
-Eric's suggestions worked in
HACKING | 37 ++++++++++++++++++++++++++++++++++++-
docs/hacking.html.in | 49 ++++++++++++++++++++++++++++++++++++++++++++-----
2 files changed, 80 insertions(+), 6 deletions(-)
diff --git a/HACKING b/HACKING
index 69ea96b..d960992 100644
--- a/HACKING
+++ b/HACKING
@@ -21,9 +21,44 @@ or:
git diff > libvirt-myfeature.patch
+However, the usual workflow of libvirt developer is:
+
+ git checkout master
+ git pull
+ git checkout -t origin -b workbranch
+ Hack, committing any changes along the way
+
+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(a)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(a)redhat.com" designation you can set it in git config:
+
+ git config sendemail.to libvir-list(a)redhat.com
+
+Please follow this as close as you can, especially the rebase and git
+send-email part, as it makes life easier for other developers to review your
+patch set. One should avoid sending patches as attachments, but rather send
+them in email body among with commit message. If a developer is sending
+another version of the patch (e.g. to address review comments), he is advised
+to note differences to previous versions after the "---" line in the patch so
+that it helps reviewers but doesn't become part of git history. Moreover, such
+patch needs to be prefixed correctly with "--subject-prefix=PATCHv2" appended
+to "git send-email" (substitute "v2" with the correct version if
needed
+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.
+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.
+
+
(4) Make sure your patches apply against libvirt GIT. Developers only follow GIT
and don't care much about released versions.
diff --git a/docs/hacking.html.in b/docs/hacking.html.in
index 89f9980..96cc062 100644
--- a/docs/hacking.html.in
+++ b/docs/hacking.html.in
@@ -11,19 +11,58 @@
<li><p>Post patches in unified diff format. A command similar to this
should work:</p>
-<pre>
+<del><pre>
diff -urp libvirt.orig/ libvirt.modified/ > libvirt-myfeature.patch
-</pre>
+</pre></del>
<p>
or:
</p>
<pre>
git diff > libvirt-myfeature.patch
</pre>
+ <p>However, the usual workflow of libvirt developer is:</p>
+<pre>
+ git checkout master
+ git pull
+ git checkout -t origin -b workbranch
+ Hack, committing any changes along the way
+</pre>
+ <p>Then, when you want to post your patches:</p>
+<pre>
+ git pull --rebase
+ (fix any conflicts)
+ git send-email --cover-letter --no-chain-reply-to --annotate
--to=libvir-list(a)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(a)redhat.com</code> designation you
can
+ set it in git config:</p>
+<pre>
+ git config sendemail.to libvir-list(a)redhat.com
+</pre>
+ <p>Please follow this as close as you can, especially the rebase and
+ git send-email part, as it makes life easier for other developers to
+ review your patch set. One should avoid sending patches as attachments,
+ but rather send them in email body among with commit message. If a
+ developer is sending another version of the patch (e.g. to address
+ review comments), he is advised to note differences to previous
+ versions after the <code>---</code> line in the patch so that it
helps
+ reviewers but doesn't become part of git history. Moreover, such patch
+ needs to be prefixed correctly with
+ <code>--subject-prefix=PATCHv2</code> appended to <code>git
+ send-email</code> (substitute <code>v2</code> with the
correct
+ version if needed though).</p>
</li>
- <li>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.</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>
+ </li>
+
<li>Make sure your patches apply against libvirt GIT. Developers
only follow GIT and don't care much about released versions.</li>
<li><p>Run the automated tests on your code before submitting any
changes.
--
1.7.8.6