[Libvirt-cim] [PATCH] Add patching guidelines to site
Jay Gagnon
grendel at linux.vnet.ibm.com
Tue Dec 4 14:49:25 UTC 2007
# HG changeset patch
# User Jay Gagnon <grendel at linux.vnet.ibm.com>
# Date 1196783327 18000
# Node ID 1a3e2e6e3ec15d8f600eb21477e18b6a48ccb2df
# Parent d182b5a3324feb2d8403d995f8208f8e0057aa6d
Add patching guidelines to site.
Signed-off-by: Jay Gagnon <grendel at linux.vnet.ibm.com>
diff -r d182b5a3324f -r 1a3e2e6e3ec1 doc/Makefile.am
--- a/doc/Makefile.am Mon Dec 03 11:22:46 2007 -0500
+++ b/doc/Makefile.am Tue Dec 04 10:48:47 2007 -0500
@@ -5,6 +5,7 @@ WEB_PAGES = index.html \
downloads.html \
intro.html \
news.html \
+ patches.html \
platforms.html \
schema.html
diff -r d182b5a3324f -r 1a3e2e6e3ec1 doc/libvirt-cim.html
--- a/doc/libvirt-cim.html Mon Dec 03 11:22:46 2007 -0500
+++ b/doc/libvirt-cim.html Tue Dec 04 10:48:47 2007 -0500
@@ -57,6 +57,183 @@
<a href="http://libvirt.org/hg/libvirt-cim/archive/tip.tar.gz">tarball</a> or
<a href="http://libvirt.org/hg/libvirt-cim/archive/tip.zip">zip</a>
file snapshot of the repository.
+</p>
+
+<h2><a name="Patches">Patches</a></h2>
+
+<p>To submit patches to libvirt-cim, you must follow the DCO process, outlined
+below:</p>
+
+<h3>Developer's Certificate of Origin 1.1</h3>
+<p>By making a contribution to this project, I certify that:</p>
+<ol>
+<li>
+ <p>
+ The contribution was created in whole or in part by me and I
+ have the right to submit it under the open source license indicated in
+ the file; or
+ </p>
+</li>
+<li>
+ <p>
+ The contribution is based upon previous work that, to the best of my
+ knowledge, is covered under an appropriate open source license and I have the
+ right under that license to submit that work with modifications, whether
+ created in whole or in part by me, under the same open source license
+ (unless I am permitted to submit under a different license), as indicated in
+ the file; or
+ </p>
+</li>
+<li>
+ <p>
+ The contribution was provided directly to me by some other person who
+ certified (1), (2) or (3) and I have not modified it.
+ </p>
+</li>
+<li>
+ <p>
+ I understand and agree that this project and the contribution are public and
+ that a record of the contribution (including all personal information I
+ submit with it, including my sign-off) is maintained indefinitely and may be
+ redistributed consistent with this project or the open source license(s)
+ involved.
+ </p>
+</li>
+</ol>
+
+<p>then you just add a line saying</p>
+
+<p style="text-align:center">
+ Signed-off-by: Random J Developer <random at developer.example.org>
+</p>
+
+<p>using your real name (sorry, no pseudonyms or anonymous contributions.)</p>
+
+<h3>Guidelines for Submitting Patches.</h3>
+<p>
+ Patches should be submitted using Mercurial's patchbomb extension, and we
+ recommend using the queues extension as well. On top of that, we have some
+ guidelines you should follow when submitting patches. This makes reviewing
+ patches easier, which in turns improves the chances of your patch being
+ accepted in a timely fashion.
+</p>
+<p>
+ For help on how to use the patchbomb extension, see
+ <a href="http://hgbook.red-bean.com/hgbookch14.html">Section 14.4</a> of <i>
+ Distributed revision control with Mercurial</i>.
+</p>
+<p>
+ For help on the queues extension, see
+ <a href="http://hgbook.red-bean.com/hgbookch12.html">Chapter 12</a>.
+</p>
+
+<h4>Single Patches:</h4>
+<ol>
+<li>
+ <p>
+ When you add a patch to the queue you have an idea of where you're going with
+ it, and the commit message should reflect that. Be specific. Avoid just
+ saying something like, "Various fixes to AllocationCapabilities." Add a list
+ of what was actually fixed, like, "Add EnumInstanceNames support," and,
+ "Eliminate duplicate instances."
+</p>
+</li>
+<li>
+ <p>
+ The first line of your commit message will be the subject of the patch email
+ when you send it out, so write it like a subject. Keep it short and to the
+ point, then start a new line and feel free to be as verbose as you need to
+ be. The entire commit message will be included in the patch.
+ </p>
+</li>
+<li>
+ <p>
+ Stay on task with a patch. If you notice other problems while you are
+ working on a patch, and they are not most definitely specific to your patch,
+ they should be another patch. The same goes for nitpicking. While it might
+ be only a line or two here and there that is off track, this is actually one
+ of the easiest ways to make a patch difficult to review. All the trivial
+ changes hide what is really going on. Make the unrelated changes a new
+ patch or don't make them at all.
+ </p>
+</li>
+<li>
+ <p>
+ If your patch addresses a strange issue or a rare edge case that the
+ reviewers are unlikely to be familiar with, make sure the commit message
+ include some example testcase with results, so the reviewers can verify
+ your patch more quickly.
+ </p>
+</li>
+<li>
+ <p>
+ Before you email, export. If you have a patch called "alloc_fixes", which
+ would be emailed with "hg email alloc_fixes", you should first run "hg export
+ alloc_fixes". This lets you review your patch. Does it have any typos in
+ the comments? Did you accidentally include an irrelevant change? Is your
+ commit message still accurate and useful? This is the single biggest step in
+ ensuring you have a good patch.
+ </p>
+</li>
+<li>
+ <p>
+ If your patch needs to be reworked and resent, prepend a "version number" to
+ the first line of the commit message. For example, "Add EnumInstance to
+ RASD," becomes "#2 Add EnumInstance to RASD." This helps mail readers thread
+ discussions correctly and helps maintainers know they are applying the right
+ version of your patch. At the end of the commit message, explain what is
+ different from one version to the next. Nobody likes having to diff a diff.
+ </p>
+</li>
+<li>
+ <p>
+ If your patch depends on a patch that exists on the mailing list but not in
+ the tree, it is okay to send your patch to the list as long as your commit
+ message mentions the dependency. It is also a good idea to import the
+ patch into your tree before you make your patch. For example, a new patch
+ called "cu_statusf API change" is on the list, and your patch needs the new
+ API. Save the email (no need to trim headers) as api_change.eml, then do
+ "hg qimport api_change.eml" and "hg qpush" so that the patch is applied to
+ your tree. Now write your patch on top of it. You should still indicate
+ the dependency in your commit message.
+</li>
+</ol>
+
+<h4>Patchsets:</h4>
+<ol>
+<li>
+ <p>
+ When you send a group of patches, Mercurial's email extension will create a
+ "header" email. Make the subject and body of that email meaningful, so we
+ know how the patches relate. It's easy to say, "Each patch has a commit
+ message, it's obvious how they work together," but the rest of the list
+ usually won't agree with that. If the commit messages for each patch are
+ good, you shouldn't need more than a sentence or two to tie them all
+ together, but you do need it.
+ </p>
+</li>
+<li>
+ <p>
+ If any of your patches are rejected and you rework them, resend the entire
+ set. This prevents things like, "So use patch 1 of 4 from the set I sent
+ yesterday, 2 and 3 of 4 from the patch I sent an hour later, and patch 4
+ of 4 from today."
+ </p>
+</li>
+<li>
+ <p>
+ If you resend a patchset, apply part (6) of the Single Patches guidelines to
+ your "Patch [0 of 3]" header email, for all the same reasons.
+ </p>
+</li>
+</ol>
+
+<p>Questions/Comments on the Guidelines should be directed to:</p>
+<p>
+ Jay Gagnon
+ <a href="mailto:grendel at linux.vnet.ibm.com">grendel at linux.vnet.ibm.com</a>
+ <br>
+ Patch Compliance Officer
</p>
<h2><a name="Schema">Schema</a></h2>
diff -r d182b5a3324f -r 1a3e2e6e3ec1 doc/site.xsl
--- a/doc/site.xsl Mon Dec 03 11:22:46 2007 -0500
+++ b/doc/site.xsl Tue Dec 04 10:48:47 2007 -0500
@@ -50,6 +50,9 @@
</xsl:when>
<xsl:when test="$name = '#Schema'">
<xsl:text>schema.html</xsl:text>
+ </xsl:when>
+ <xsl:when test="$name = '#Patches'">
+ <xsl:text>patches.html</xsl:text>
</xsl:when>
<xsl:when test="$name = ''">
<xsl:text>unknown.html</xsl:text>
More information about the Libvirt-cim
mailing list