Submitting Xen Patches - mercurial
How To Generate and Submit a Patch to Xen using mercurial
Xen now uses git for its source code management, and we encourage everyone to use git. However, we have historically used Mercurial, and still maintain mercurial branches for those who which to continue using mercurial.
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 <firstname.lastname@example.org>
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 <email@example.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 ...
Repeat as necessary for all of your changes
hg qnew patch02.diff
Sending the patches to the list
Please see the main [Submitting_Xen_Patches Submitting Xen Patches] page for advice and requirements about what to include in the patch, how to format the patch, and so on.
Mercurial Patchbomb Extension
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 <firstname.lastname@example.org> cc = email@example.com [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 <firstname.lastname@example.org> 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 email@example.com 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 firstname.lastname@example.org --cc email@example.com
-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. The best option is probably to enable server mode and then set emacs client 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:
-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
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.
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.