# HG changeset patch # User Jay Gagnon <grendel@linux.vnet.ibm.com> # Date 1196783327 18000 # Node ID 1a3e2e6e3ec15d8f600eb21477e18b6a48ccb2df # Parent d182b5a3324feb2d8403d995f8208f8e0057aa6d Add patching guidelines to site. Signed-off-by: Jay Gagnon <grendel@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@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@linux.vnet.ibm.com">grendel@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>