Submitting Xen Project Patches
How To Generate and Submit a Patch to Xen
Xen uses Mercurial for its source code management. The current Xen development tree is at http://xenbits.xensource.com/xen-unstable.hg. An excellent tutorial is here. Download and install mercurial to your system.
Generating a patch
Here's a recommendation on how to send patches, as suggested by the Xen maintainers.
To begin, configure Mercurial by making the following additions to your
- Enable the Patchqueue extension
- Show function names in patch hunk headers (which makes patches easier to review).
When you want to make a patch, create a patch on the patch queue:
hg qnew patch01.diff
Then edit the source files you want to change. You can see which files have changed by using
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
-e option to
hg qrefresh -e
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 <email@example.com>
Alternately, after refreshing the patch with
hg qrefresh, you can edit the files directly in
.hg/patches/. Everything above the line starting with
diff will be ignored:
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 <firstname.lastname@example.org> 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 ...
Repeat as necessary for all of your changes
hg qnew patch02.diff
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 mercurial 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
- If you're using mercurial queues, as described above, use
hg qrefresh -eto edit the description, or edit the patch files directly in
.hg/patches/. NB that if you edit the files directly, you'll have to
hg qpop -a ; hg qpush -ato 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 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.
Sending the patches to the list
The most robust way to send files is by using the Mercurial Patchbomb extension.
To do this, first set up the Patchbomb extension in your
[extensions] hgext.patchbomb = [email] method = smtp from = Your Name <email@example.com> cc = firstname.lastname@example.org [smtp] host = mail.yourdomain.com port = 25
Then check to make sure you have the right patches to be submitted by using
$ hg out comparing with http://hg/xen-unstable.hg searching for changes changeset: 21165:2631707c54b3 tag: qbase tag: add-trondle-call.diff user: Joe Smith <email@example.com> date: Wed Apr 14 11:16:58 2010 +0100 summary: 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 firstname.lastname@example.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:
$ hg email -o --plain --to email@example.com --cc firstname.lastname@example.org
-o option tells patchbomb to submit all outgoing patches;
--plain removes the extraneous HG header information from the patches in the e-mails;
--cc say who to send the mail to.) It will ask you some questions, like this:
comparing with http://hg/xen-unstable.hg searching for changes This patch series consists of 5 patches. Subject: [PATCH 0 of 5]
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.)
Other useful options include:
-nwill 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.
-dproduces a "diffstat", showing lines added and removed for each file. It asks a lot more questions, though.
--descallow you to specify a subject line and body respectively for the summary email.
firstpatch:lastpatchallows you to name a specific range of patches to send and can be used instead of the
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 Mercurial patchbomb extension then the
--flag 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 <email@example.com> Acked-by: Jane Doe <firstname.lastname@example.org> --- 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.
- Your patch is really big?
- Break it up into smaller logically distinct patches
- Example - http://markmail.org/thread/e36vcwk3347de27n
- 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