Difference between revisions of "Submitting Xen Project Patches"

From Xen
(Request CCs to maintainers by default)
(Updated instructions for git instead of mercurial)
Line 1: Line 1:
 
== How To Generate and Submit a Patch to Xen ==
 
== How To Generate and Submit a Patch to Xen ==
   
Xen uses [http://www.selenic.com/mercurial/wiki/index.cgi Mercurial] for its source code management. The current Xen development tree is at http://xenbits.xen.org/xen-unstable.hg. An excellent [http://www.selenic.com/mercurial/wiki/index.cgi/Tutorial tutorial] is here. Download and install mercurial to your system.
+
Xen uses [http://git-scm.com Git] for its source code management. The current Xen development tree is at http://xenbits.xen.org/xen.git; "master" is the branch containing the latest development changesets to pass our automated build and test system.
   
 
=== Generating a patch ===
 
=== Generating a patch ===
 
----
 
----
Here's a recommendation on how to send patches, as suggested by the Xen maintainers.
+
Here's a recommendation on how to create patches using git, as suggested by the Xen maintainers. If you want to use mercurial, please see [[Submitting_Xen_Patches_-_mercurial]].
   
  +
Begin by cloning the git repo from xen.org:
To begin, configure Mercurial by making the following additions to your <code>~/.hgrc</code>:
 
  +
<pre>
  +
$ git clone git://xenbits.xen.org/xen.git xen.git
  +
</pre>
   
  +
At this point you should have <code>xenbits</code> set up as the remote repostiory called "origin":
* Enable the [http://mercurial.selenic.com/wiki/MqExtension Patchqueue extension]
 
 
 
<pre>
 
<pre>
  +
$ git branch -a
[extensions]
 
  +
* master
mq=
 
  +
remotes/origin/HEAD -> origin/master
  +
remotes/origin/master
  +
remotes/origin/stable-4.0
  +
remotes/origin/stable-4.1
  +
remotes/origin/stable-4.2
  +
remotes/origin/staging
  +
remotes/origin/staging-4.0
  +
remotes/origin/staging-4.1
  +
remotes/origin/staging-4.2
 
</pre>
 
</pre>
   
  +
This process automatically creates a local branch called <code>master</code> that will track the xen.org branch called <code>master</code>.
  +
  +
The branch called <code>staging</code> is the bleeding-edge of commits; this is tested regularly with the <code>xen.org</code> build and regression testing system, and when it pases, is pushed to the <code>master</code> branch. It is suggested to develop patches based on the <code>master</code> branch.
  +
  +
When you want to introduce a change, start by making a new branch based on the most recent change in the <code>master</code> branch:
   
* Show function names in patch hunk headers (which makes patches easier to review).
 
 
 
<pre>
 
<pre>
  +
$ git checkout -b out/trondle-calls master
[diff]
 
  +
Switched to a new branch 'out/trondle-calls'
showfunc=True
 
 
</pre>
 
</pre>
   
  +
Then edit the source files you want to change. You can see which files have changed by using <code>git status</code>.
   
  +
When you're done editing, use <code>git add</code> to specify which file changes you want included in the changeset, and then use <code>git commit</code> to make a commit. You will be prompted to make a changset description:
When you want to make a patch, create a patch on the patch queue:
 
 
 
 
<pre>
 
<pre>
  +
$ git status
hg qnew patch01.diff
 
  +
# On branch out/trondle-calls
  +
# Changes not staged for commit:
  +
# (use "git add <file>..." to update what will be committed)
  +
# (use "git checkout -- <file>..." to discard changes in working directory)
  +
#
  +
# modified: foobar/zot.c
  +
# modified: foobar/zot.h
  +
#
  +
no changes added to commit (use "git add" and/or "git commit -a")
  +
$ git add foobar/zot.c foobar/zot.h
  +
$ git commit
 
</pre>
 
</pre>
   
  +
Alternatively, you can commit all changes using "git commit -a":
   
Then edit the source files you want to change. You can see which files have changed by using <code>hg status</code>.
 
 
When you're done editing, save your changes into the patch, and add a description. The easiest way to add a description is to use the <code>-e</code> option to <code>hg qrefresh</code>:
 
 
 
<pre>
 
<pre>
  +
$ git commit -a
hg qrefresh -e
 
 
</pre>
 
</pre>
 
 
 
 
<pre>
 
<pre>
Line 50: Line 72:
 
</pre>
 
</pre>
   
  +
Make as many commits on your new branch as are necessary.
Alternately, after refreshing the patch with <code>hg qrefresh</code>, you can edit the files directly in <code>.hg/patches/</code>. Everything above the line starting with <code>diff</code> will be ignored:
 
 
 
<pre>
 
foobar: Add a new trondle calls
 
   
  +
If you want to make a local branch based on <code>staging</code> rather than <code>master</code> (for example, to fix a changeset which has caused the xen.org nightly testing to fail), you can do the following:
Add a some new trondle calls to the foobar interface to support
 
the new zot feature.
 
 
Signed-off-by: Joe Smith <joe.smith@citrix.com>
 
 
diff -r 63531e640828 tools/libxc/Makefile
 
--- a/tools/libxc/Makefile Mon Dec 07 17:01:11 2009 +0000
 
+++ b/tools/libxc/Makefile Mon Dec 21 11:45:00 2009 +0000
 
...
 
</pre>
 
 
Repeat as necessary for all of your changes
 
 
 
<pre>
 
<pre>
  +
$ git checkout -b staging remotes/origin/staging
hg qnew patch02.diff
 
  +
Branch staging set up to track remote branch staging from origin.
  +
Switched to a new branch 'staging'
 
</pre>
 
</pre>
  +
Then in the commands above, you would use "staging" instead of "master" as the base branch.
 
 
...
 
...
 
=== Signing off a patch ===
 
=== Signing off a patch ===
Line 108: Line 118:
 
=== Making good patches ===
 
=== Making good patches ===
 
----
 
----
Patches, if accepted, will turn into commits in the mercurial source tree. There are three people to think about when writing the patch and the comment:
+
Patches, if accepted, will turn into commits in the git source tree. There are three people to think about when writing the patch and the comment:
 
* Reviewers on the mailing list, who are trying to understand what your patch does, if it's correct, and what side effects it will have.
 
* Reviewers on the mailing list, who are trying to understand what your patch does, if it's correct, and what side effects it will have.
 
* People skimming through changesets deciding if a patch is important for them to look at for backporting, review, implications on out-of-tree patches, &c.
 
* People skimming through changesets deciding if a patch is important for them to look at for backporting, review, implications on out-of-tree patches, &c.
Line 119: Line 129:
 
* Don't mix clean-up patches (which make things look prettier or move things round but don't change functionality) with code-change patches. Clean-up patches should be clearly marked as having no functional changes.
 
* Don't mix clean-up patches (which make things look prettier or move things round but don't change functionality) with code-change patches. Clean-up patches should be clearly marked as having no functional changes.
 
==== Write a good description for each patch ====
 
==== Write a good description for each patch ====
* If you're using mercurial queues, as described above, use <code>hg qrefresh -e</code> to edit the description, or edit the patch files directly in <code>.hg/patches/</code>. NB that if you edit the files directly, you'll have to <code>hg qpop -a ; hg qpush -a</code> to get the description into mercurial.
 
 
* The first line the top of the patch should contain a short description of what the patch does, and hints as to what code it touches
 
* The first line the top of the patch should contain a short description of what the patch does, and hints as to what code it touches
 
* The description should be useful for both the reviewers and people in the future trying to understand what the patch does. It can be as short as <code>Code cleanup -- no functional changes</code>, or as long as it takes to accurately describe the bug you are trying to solve or the new functionality you are introducing.
 
* The description should be useful for both the reviewers and people in the future trying to understand what the patch does. It can be as short as <code>Code cleanup -- no functional changes</code>, or as long as it takes to accurately describe the bug you are trying to solve or the new functionality you are introducing.
Line 129: Line 138:
 
* The maintainers are listed in the MAINTAINERS file at the top of the Xen source tree. If no maintainer is listed then there is no need for a CC (if you are modifying code with no maintainer then you might like to consider becoming the maintainer for that piece of code!)
 
* The maintainers are listed in the MAINTAINERS file at the top of the Xen source tree. If no maintainer is listed then there is no need for a CC (if you are modifying code with no maintainer then you might like to consider becoming the maintainer for that piece of code!)
 
* In addition to CCing the maintainer you should always send patches to the xen-devel@lists.xen.org mailing list as well.
 
* In addition to CCing the maintainer you should always send patches to the xen-devel@lists.xen.org mailing list as well.
* To add a CC when sending the mail you can use the ''--cc'' option to the ''hg email'' command, or you can do it manually in your MUA.
+
* To add a CC when sending the mail you can use the ''--cc'' option to the ''git send-email'' command, or you can do it manually in your MUA.
   
 
=== Sending the patches to the list ===
 
=== Sending the patches to the list ===
Line 136: Line 145:
 
The xen-devel mailing list is moderated for non-subscribers. It is not mandatory to subscribe but it can help avoid this delay. It is possible to subscribe and then disable delivery in the mailman options so as to avoid moderation but not receive list traffic if that is what you would prefer.
 
The xen-devel mailing list is moderated for non-subscribers. It is not mandatory to subscribe but it can help avoid this delay. It is possible to subscribe and then disable delivery in the mailman options so as to avoid moderation but not receive list traffic if that is what you would prefer.
   
==== Mercurial Patchbomb Extension ====
+
==== Git Patchbomb Extension ====
The most robust way to send files is by using the [http://mercurial.selenic.com/wiki/PatchbombExtension Mercurial Patchbomb extension].
+
The most robust way to send files is by using the [https://www.kernel.org/pub/software/scm/git/docs/git-send-email.html git send-email command]. (If you're using mercurial, please see our [[Submitting_Xen_Patches_-_mercurial]]).
   
To do this, first set up the Patchbomb extension in your <code>.hgrc</code> file:
+
To do this, first set configure your information:
 
 
<pre>
 
<pre>
  +
git config --global sendemail.from "YOUR NAME <user@example.org>"
[extensions]
 
  +
git config --global sendemail.smtpserver imap.example.org
hgext.patchbomb =
 
  +
git config --global sendemail.smtpuser USER
  +
# depending on your config you may also set:
  +
git config --global sendemail.smtpencryption tls
  +
</pre>
   
  +
If you don't want to enter password for your SMTP server all the time:
[email]
 
  +
<pre>
method = smtp
 
  +
git config --global sendemail.smtppass = PASS
from = Your Name <your.email@your-domain.com>
 
cc = your.email@your-domain.com
 
 
[smtp]
 
host = mail.yourdomain.com
 
port = 25
 
 
</pre>
 
</pre>
   
Then check to make sure you have the right patches to be submitted by using <code>hg out</code>:
+
Then check to make sure you have the right patches to be submitted by using <code>git </code>:
 
 
 
<pre>
 
<pre>
  +
$ git log master..
$ hg out
 
  +
commit 347175ecaba64c324853f004e4860a941b07e5a9
comparing with http://hg/xen-unstable.hg
 
  +
Author: Joe Smith <joe.smith@citrix.com>
searching for changes
 
  +
changeset: 21165:2631707c54b3
 
  +
foobar: Add new trondle calls
tag: qbase
 
tag: add-trondle-call.diff
 
user: Joe Smith <joe.smith@citrix.com>
 
date: Wed Apr 14 11:16:58 2010 +0100
 
summary: foobar: Add new trondle calls
 
   
 
...
 
...
Line 173: Line 176:
 
Next you need to figure out who (if anyone) you should copy the patches to. To do this you should consult the <code>MAINTAINERS</code> file at the top of the Xen source tree. If there is a specific maintainer listed for the area of the code you are modifying then it is best to copy the patches to them. You should always send patches to the xen-devel@lists.xen.org mailing list as well.
 
Next you need to figure out who (if anyone) you should copy the patches to. To do this you should consult the <code>MAINTAINERS</code> file at the top of the Xen source tree. If there is a specific maintainer listed for the area of the code you are modifying then it is best to copy the patches to them. You should always send patches to the xen-devel@lists.xen.org mailing list as well.
   
Once you're sure you have the proper series of patches and know who you are sending it to then you're ready to use the patchbomb tool:
+
Once you're sure you have the proper series of patches and know who you are sending it to then you're ready to use <code>git send-email</code>:
 
 
 
<pre>
 
<pre>
$ hg email -o --plain --to xen-devel@lists.xen.org --cc the.maintainer@example.com
+
$ git send-email --to xen-devel@lists.xen.org --cc the.maintainer@example.com master..
 
</pre>
 
</pre>
   
(The <code>-o</code> option tells patchbomb to submit all outgoing patches; <code>--plain</code> removes the extraneous HG header information from the patches in the e-mails; <code>--to</code> and <code>--cc</code> say who to send the mail to.) It will ask you some questions, like this:
+
<code>--to</code> and <code>--cc</code> say who to send the mail to. <code>master..</code> will tell it to send all changesets on the current branch *after* (not including) the one marked by <code>master</code>.
 
<pre>
 
comparing with http://hg/xen-unstable.hg
 
searching for changes
 
This patch series consists of 5 patches.
 
   
  +
NB, emacs users: if you're running this from an emacs shell, this can get tricky, since all of the editors it wants to offer you require a terminal. The best option is probably to enable server mode and then set [http://www.emacswiki.org/emacs/EmacsClient emacsclient] as the default editor.
Subject: [PATCH 0 of 5]
 
</pre>
 
 
Enter in a summary for the entire patch series here, and press enter. You will then be dropped into an editor, to write the text for the patch series intro e-mail.
 
 
NB, emacs users: if you're running this from an emacs shell, this can get tricky, since all of the editors it wants to offer you require a terminal. Best to run it in a normal terminal window somewhere.
 
   
 
Tada! You should shortly see your patch series appear in your inbox, and on the xen-devel mailing list (depending on how you've configured it.)
 
Tada! You should shortly see your patch series appear in your inbox, and on the xen-devel mailing list (depending on how you've configured it.)
   
 
Other useful options include:
 
Other useful options include:
* <code>-n</code> will go through all the motions of preparing the patchbomb, but instead of sending a mail, will just output the mails it would have sent. Useful for testing.
+
* <code>--dry-run</code> will go through all the motions of preparing the patchbomb, but instead of sending a mail, will just output the mails it would have sent. Useful for testing.
  +
* <code>--subject-prefix</code> will allow you to change the prefix from <code>[PATCH]</code> to something else. Examples may include <code>--subject-prefx="PATCH RFC"</code> if you just want to get feedback on a patch series (Request For Comments), or <code>--subject-prefix="PATCH v3"</code> for the 3rd version of your patch series.
* <code>-d</code> produces a "diffstat", showing lines added and removed for each file. It asks a lot more questions, though.
 
  +
* <code>-s</code> & <code>--desc</code> allow you to specify a subject line and body respectively for the summary email.
 
* <code>firstpatch:lastpatch</code> allows you to name a specific range of patches to send and can be used instead of the <code>-o</code> option.
 
   
 
==== Sending Patches Manually ====
 
==== Sending Patches Manually ====
   
It is strongly recommended to use the Mercurial patchbomb extension discussed above. However it is possible to send a patch manually using your regular mail client.
+
It is strongly recommended to use the git send-email extension discussed above. However it is possible to send a patch manually using your regular mail client.
   
 
You should be aware that many mail clients have a tendency to mangle the whitespace of a patch making it impossible to apply. It is highly recommended to read Linux's [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/email-clients.txt;hb=HEAD email-clients.txt] for advice on how to avoid this in popular mail clients.
 
You should be aware that many mail clients have a tendency to mangle the whitespace of a patch making it impossible to apply. It is highly recommended to read Linux's [http://git.kernel.org/?p=linux/kernel/git/torvalds/linux-2.6.git;a=blob;f=Documentation/email-clients.txt;hb=HEAD email-clients.txt] for advice on how to avoid this in popular mail clients.
Line 216: Line 208:
 
Once you have addressed any review you should normally resend the patch. It is normally expected that you address all review before reposting. This often means code changes in your patch but could also mean simply responding to the review comments explaining you reasoning or giving reasons why something should be the way it is.
 
Once you have addressed any review you should normally resend the patch. It is normally expected that you address all review before reposting. This often means code changes in your patch but could also mean simply responding to the review comments explaining you reasoning or giving reasons why something should be the way it is.
   
When resending a patch you should normally include a note of what has changed since last time in the message. Common practice is to include these notes after your Signed-off-by separated by a triple-dash ("---"). This indicates patch commentary specific to the posting which need not be included in the final changelog (although you should also remember to update the changelog if necessary). You should also including a "V2" (V3, V4 etc) tag in the subject line (if you are using the Mercurial patchbomb extension then the <code>--flag</code> option is helpful here).
+
When resending a patch you should normally include a note of what has changed since last time in the message. Common practice is to include these notes after your Signed-off-by separated by a triple-dash ("---"). This indicates patch commentary specific to the posting which need not be included in the final changelog (although you should also remember to update the changelog if necessary). You should also including a "V2" (V3, V4 etc) tag in the subject line (if you are using the git <code>send-email</code> command then the <code>--subject-prefix</code> option is helpful here).
   
 
If someone replies to your patch with a tag of the form "Acked-by: <Developer>", "Reviewed-by:", "Tested-by:" etc then, assuming you have not completely reworked the patch, you should include these tags in any reposting after your own Signed-off-by line. This lets people know that the patch has been seen and that someone approves of it and also serves to prevent reviewers wasting time re-reviewing a patch which is not significantly different to last time. The developers with commit access also like to see postings with such tags since it means they are likely to be much easier to deal with and commit.
 
If someone replies to your patch with a tag of the form "Acked-by: <Developer>", "Reviewed-by:", "Tested-by:" etc then, assuming you have not completely reworked the patch, you should include these tags in any reposting after your own Signed-off-by line. This lets people know that the patch has been seen and that someone approves of it and also serves to prevent reviewers wasting time re-reviewing a patch which is not significantly different to last time. The developers with commit access also like to see postings with such tags since it means they are likely to be much easier to deal with and commit.
Line 253: Line 245:
 
=== After your patch is committed ===
 
=== After your patch is committed ===
   
Changes committed to Xen by the committers are immediately available in the "staging" repositories, for example http://xenbits.xen.org/staging/xen-unstable.hg. They are then automatically tested, and if the tests pass the changes are propagated to the main tree http://xenbits.xen.org/xen-unstable.hg.
+
Changes committed to Xen by the committers are immediately available in the "staging" branch of the main xen.git tree. They are then automatically tested, and if the tests pass the changes are propagated to the "master" branch.
   
 
If your patch turns out to break something you will be expected to respond promptly to help diagnose and fix the problem. If it can't be fixed quickly, your change may be reverted.
 
If your patch turns out to break something you will be expected to respond promptly to help diagnose and fix the problem. If it can't be fixed quickly, your change may be reverted.
Line 264: Line 256:
   
 
Xen uses QEMU as device model, that is the software component that takes care of emulating devices (like the network card) for HVM guests.
 
Xen uses QEMU as device model, that is the software component that takes care of emulating devices (like the network card) for HVM guests.
Two QEMU trees, both using [http://git-scm.com/ git] for revision control, are currently in use by xen-unstable.hg:
+
Two QEMU trees, both using [http://git-scm.com/ git] for revision control, are currently in use by xen.git:
   
 
- [http://xenbits.xen.org/gitweb/?p=qemu-xen-unstable.git;a=summary qemu-xen-traditional]: old and stable tree, only bug fixes are accepted in this tree at the moment;
 
- [http://xenbits.xen.org/gitweb/?p=qemu-xen-unstable.git;a=summary qemu-xen-traditional]: old and stable tree, only bug fixes are accepted in this tree at the moment;
Line 277: Line 269:
 
== How to Generate, and Submit a Xen Patch to the Linux Tree ==
 
== How to Generate, and Submit a Xen Patch to the Linux Tree ==
   
Linux uses the git SCM, unlike Xen, which currently uses Mercurial. The Linux tree contains documentation on submitting patches, in Documentation/SubmittingPatches, as well as a script (scripts/checkpatch.pl) that ensures your patch is in Linux house style. Running git apply --check on your patch can reveal merge errors.
+
Like Xen, Linux uses the git SCM. The Linux tree contains documentation on submitting patches, in Documentation/SubmittingPatches, as well as a script (scripts/checkpatch.pl) that ensures your patch is in Linux house style. Running git apply --check on your patch can reveal merge errors.
   
 
Patches should be emailed to xen-devel@lists.xen.org, linux-kernel@vger.kernel.org, and any relevant maintainers (which can be found by running scripts/get_maintainer.pl on your patch).
 
Patches should be emailed to xen-devel@lists.xen.org, linux-kernel@vger.kernel.org, and any relevant maintainers (which can be found by running scripts/get_maintainer.pl on your patch).

Revision as of 15:30, 25 March 2013

How To Generate and Submit a Patch to Xen

Xen uses Git for its source code management. The current Xen development tree is at http://xenbits.xen.org/xen.git; "master" is the branch containing the latest development changesets to pass our automated build and test system.

Generating a patch


Here's a recommendation on how to create patches using git, as suggested by the Xen maintainers. If you want to use mercurial, please see Submitting_Xen_Patches_-_mercurial.

Begin by cloning the git repo from xen.org:

$ git clone git://xenbits.xen.org/xen.git xen.git

At this point you should have xenbits set up as the remote repostiory called "origin":

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/stable-4.0
  remotes/origin/stable-4.1
  remotes/origin/stable-4.2
  remotes/origin/staging
  remotes/origin/staging-4.0
  remotes/origin/staging-4.1
  remotes/origin/staging-4.2

This process automatically creates a local branch called master that will track the xen.org branch called master.

The branch called staging is the bleeding-edge of commits; this is tested regularly with the xen.org build and regression testing system, and when it pases, is pushed to the master branch. It is suggested to develop patches based on the master branch.

When you want to introduce a change, start by making a new branch based on the most recent change in the master branch:

$ git checkout -b out/trondle-calls master
Switched to a new branch 'out/trondle-calls'

Then edit the source files you want to change. You can see which files have changed by using git status.

When you're done editing, use git add to specify which file changes you want included in the changeset, and then use git commit to make a commit. You will be prompted to make a changset description:

$ git status
# On branch out/trondle-calls
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   foobar/zot.c
#	modified:   foobar/zot.h
#
no changes added to commit (use "git add" and/or "git commit -a")
$ git add foobar/zot.c foobar/zot.h
$ git commit

Alternatively, you can commit all changes using "git commit -a":

$ git commit -a
foobar: Add a new trondle calls

Add a some new trondle calls to the foobar interface to support
the new zot feature.

Signed-off-by: Joe Smith <joe.smith@citrix.com>

Make as many commits on your new branch as are necessary.


If you want to make a local branch based on staging rather than master (for example, to fix a changeset which has caused the xen.org nightly testing to fail), you can do the following:

$ git checkout -b staging remotes/origin/staging
Branch staging set up to track remote branch staging from origin.
Switched to a new branch 'staging'

Then in the commands above, you would use "staging" instead of "master" as the base branch. ...

Signing off a patch


All patches to the Xen code base must include the the line "Signed-off-by: your_name <your_email>" at the end of the change description. This is required and indicates that you certify the patch under the "Developer's Certificate of Origin" which states:


Developer's Certificate of Origin 1.1

        By making a contribution to this project, I certify that:

        (a) 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

        (b) 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

        (c) The contribution was provided directly to me by some other
            person who certified (a), (b) or (c) and I have not modified
            it.

	(d) 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.

Making good patches


Patches, if accepted, will turn into commits in the git source tree. There are three people to think about when writing the patch and the comment:

  • Reviewers on the mailing list, who are trying to understand what your patch does, if it's correct, and what side effects it will have.
  • People skimming through changesets deciding if a patch is important for them to look at for backporting, review, implications on out-of-tree patches, &c.
  • Someone in the perhaps distant future, who is trying to understand why the code is the way it is.

Try to make your patches with all of these people in mind. To do this:

Break down your patches

  • Each patch should preferably do one logical thing (or one related set of things). The goal is for reviewers to understand the change that each patch is making with a minimum of effort.
  • No patch should ever break existing functionality.
  • Never fix bugs in one of your patches by changing it in a later patch; go back and change the patch with the bug in it.
  • Don't mix clean-up patches (which make things look prettier or move things round but don't change functionality) with code-change patches. Clean-up patches should be clearly marked as having no functional changes.

Write a good description for each patch

  • The first line the top of the patch should contain a short description of what the patch does, and hints as to what code it touches
  • The description should be useful for both the reviewers and people in the future trying to understand what the patch does. It can be as short as Code cleanup -- no functional changes, or as long as it takes to accurately describe the bug you are trying to solve or the new functionality you are introducing.
  • The description should be wrapped to a maximum of 80 columns.

Cc the maintainer of the code you are modifying

  • Please always send a copy of the patch to the maintainer of the code you are modifying.
  • The maintainers are listed in the MAINTAINERS file at the top of the Xen source tree. If no maintainer is listed then there is no need for a CC (if you are modifying code with no maintainer then you might like to consider becoming the maintainer for that piece of code!)
  • In addition to CCing the maintainer you should always send patches to the xen-devel@lists.xen.org mailing list as well.
  • To add a CC when sending the mail you can use the --cc option to the git send-email command, or you can do it manually in your MUA.

Sending the patches to the list


The xen-devel mailing list is moderated for non-subscribers. It is not mandatory to subscribe but it can help avoid this delay. It is possible to subscribe and then disable delivery in the mailman options so as to avoid moderation but not receive list traffic if that is what you would prefer.

Git Patchbomb Extension

The most robust way to send files is by using the git send-email command. (If you're using mercurial, please see our Submitting_Xen_Patches_-_mercurial).

To do this, first set configure your information:

git config --global sendemail.from "YOUR NAME <user@example.org>"
git config --global sendemail.smtpserver imap.example.org
git config --global sendemail.smtpuser USER
# depending on your config you may also set:
git config --global sendemail.smtpencryption tls

If you don't want to enter password for your SMTP server all the time:

git config --global sendemail.smtppass = PASS

Then check to make sure you have the right patches to be submitted by using git :

$ git log master..
commit 347175ecaba64c324853f004e4860a941b07e5a9
Author: Joe Smith <joe.smith@citrix.com>

foobar: Add new trondle calls

...

Next you need to figure out who (if anyone) you should copy the patches to. To do this you should consult the MAINTAINERS file at the top of the Xen source tree. If there is a specific maintainer listed for the area of the code you are modifying then it is best to copy the patches to them. You should always send patches to the xen-devel@lists.xen.org mailing list as well.

Once you're sure you have the proper series of patches and know who you are sending it to then you're ready to use git send-email:

$ git send-email --to xen-devel@lists.xen.org --cc the.maintainer@example.com master..

--to and --cc say who to send the mail to. master.. will tell it to send all changesets on the current branch *after* (not including) the one marked by master.

NB, emacs users: if you're running this from an emacs shell, this can get tricky, since all of the editors it wants to offer you require a terminal. The best option is probably to enable server mode and then set emacsclient as the default editor.

Tada! You should shortly see your patch series appear in your inbox, and on the xen-devel mailing list (depending on how you've configured it.)

Other useful options include:

  • --dry-run will go through all the motions of preparing the patchbomb, but instead of sending a mail, will just output the mails it would have sent. Useful for testing.
  • --subject-prefix will allow you to change the prefix from [PATCH] to something else. Examples may include --subject-prefx="PATCH RFC" if you just want to get feedback on a patch series (Request For Comments), or --subject-prefix="PATCH v3" for the 3rd version of your patch series.


Sending Patches Manually

It is strongly recommended to use the git send-email extension discussed above. However it is possible to send a patch manually using your regular mail client.

You should be aware that many mail clients have a tendency to mangle the whitespace of a patch making it impossible to apply. It is highly recommended to read Linux's email-clients.txt for advice on how to avoid this in popular mail clients.

Review, Rinse & Repeat


After posting your patches you will hopefully see some response in the form of comments, patch review and eventually commit.

The form of the review may often be quite direct and to the point which may be daunting for some people. However bear in mind that detailed criticism of a patch usually means that the reviewer is interested in your patch and wants to see it go in!

Once you have addressed any review you should normally resend the patch. It is normally expected that you address all review before reposting. This often means code changes in your patch but could also mean simply responding to the review comments explaining you reasoning or giving reasons why something should be the way it is.

When resending a patch you should normally include a note of what has changed since last time in the message. Common practice is to include these notes after your Signed-off-by separated by a triple-dash ("---"). This indicates patch commentary specific to the posting which need not be included in the final changelog (although you should also remember to update the changelog if necessary). You should also including a "V2" (V3, V4 etc) tag in the subject line (if you are using the git send-email command then the --subject-prefix option is helpful here).

If someone replies to your patch with a tag of the form "Acked-by: <Developer>", "Reviewed-by:", "Tested-by:" etc then, assuming you have not completely reworked the patch, you should include these tags in any reposting after your own Signed-off-by line. This lets people know that the patch has been seen and that someone approves of it and also serves to prevent reviewers wasting time re-reviewing a patch which is not significantly different to last time. The developers with commit access also like to see postings with such tags since it means they are likely to be much easier to deal with and commit.

An example of a resend of the example patch from above might be:

Subject: [PATCH v2] foobar: Add a new trondle calls

Add a some new trondle calls to the foobar interface to support
the new zot feature.

Signed-off-by: Joe Smith <joe.smith@citrix.com>
Acked-by: Jane Doe <jane.doe@example.com>

---
Changed since v1:
  * fix coding style
  * be sure to treadle the trondle in the error case.

diff -r 63531e640828 tools/libxc/Makefile
--- a/tools/libxc/Makefile	Mon Dec 07 17:01:11 2009 +0000
+++ b/tools/libxc/Makefile	Mon Dec 21 11:45:00 2009 +0000
...

If you do not get any response to your patch or you got lots of Acked-by's but the patch has not been committed (remember that reviewers and maintainers are busy people too and sometimes things may fall through the cracks) then after some time, perhaps 2-4 weeks (guidelines), you should resend the patch, perhaps including [RESEND] in the subject line to alert people that the last mail was dropped. Before resending it may be worth considering if there is anything you can do to improve the commit message or subject line of your patch to better attract the attention of the relevant people. Remember to include any Acked-by/Reviewed-by which you received in response to the previous post.

What If


  • Your patch is really big?
  • You have lots and lots of patches? If you are going to generate > 20 patches a week:
    • You might want to host a repository tree that the maintainers can pull from, talk to the maintainers

After your patch is committed

Changes committed to Xen by the committers are immediately available in the "staging" branch of the main xen.git tree. They are then automatically tested, and if the tests pass the changes are propagated to the "master" branch.

If your patch turns out to break something you will be expected to respond promptly to help diagnose and fix the problem. If it can't be fixed quickly, your change may be reverted.

How To Generate and Submit a Patch to Qemu-Xen

Xen uses QEMU as device model, that is the software component that takes care of emulating devices (like the network card) for HVM guests. Two QEMU trees, both using git for revision control, are currently in use by xen.git:

- qemu-xen-traditional: old and stable tree, only bug fixes are accepted in this tree at the moment;

- qemu-xen: new tree used for development, based on the latest stable branch of Upstream QEMU, that currently is available at qemu git repo. See QEMU Upstream on how to manually build it and use it to run VMs.


New features should be developed again the latest upstream QEMU first, see http://wiki.qemu.org/Contribute/SubmitAPatch, then upon request they can be backported to qemu-xen. Only patches that have been acked and committed to qemu.git are eligible to be backported to qemu-xen. In order to request a backport, send an email to xen-devel@lists.xen.org, specifying the original commit id in qemu.git and the reason why the patch should be backported to qemu-xen.

How to Generate, and Submit a Xen Patch to the Linux Tree

Like Xen, Linux uses the git SCM. The Linux tree contains documentation on submitting patches, in Documentation/SubmittingPatches, as well as a script (scripts/checkpatch.pl) that ensures your patch is in Linux house style. Running git apply --check on your patch can reveal merge errors.

Patches should be emailed to xen-devel@lists.xen.org, linux-kernel@vger.kernel.org, and any relevant maintainers (which can be found by running scripts/get_maintainer.pl on your patch).