Submitting Xen Patches - mercurial: Difference between revisions
(Created page with "== How To Generate and Submit a Patch to Xen using mercurial == Xen now uses [http://git-scm.com git] for its source code management, and we encourage everyone to use git. Howe…") |
(No difference)
|
Revision as of 11:57, 25 March 2013
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.
The current Xen development tree is at http://xenbits.xen.org/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 ~/.hgrc
:
- Enable the Patchqueue extension
[extensions] mq=
- Show function names in patch hunk headers (which makes patches easier to review).
[diff] showfunc=True
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 hg status
.
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
:
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 <joe.smith@citrix.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 <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 ...
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 .hgrc
file:
[extensions] hgext.patchbomb = [email] method = smtp from = Your Name <your.email@your-domain.com> cc = your.email@your-domain.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
:
$ 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 <joe.smith@citrix.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 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:
$ hg email -o --plain --to xen-devel@lists.xen.org --cc the.maintainer@example.com
(The -o
option tells patchbomb to submit all outgoing patches; --plain
removes the extraneous HG header information from the patches in the e-mails; --to
and --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:
-n
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.-d
produces a "diffstat", showing lines added and removed for each file. It asks a lot more questions, though.-s
&--desc
allow you to specify a subject line and body respectively for the summary email.firstpatch:lastpatch
allows you to name a specific range of patches to send and can be used instead of the-o
option.
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.