Difference between revisions of "Managing Xen Patches with StGit"

From Xen
(Sending a Patch or Patch Series to xen-devel@: Add a section on outbound branches)
 
(22 intermediate revisions by 4 users not shown)
Line 1: Line 1:
  +
This document assumes that you are familiar with the following documents
== How To Generate and Submit a Patch to Xen using Git ==
 
  +
* [[Xen Project Repositories]]
  +
* [[Submitting Xen Project Patches]] - the document explains conventions related to cover letters, *-by tags, etc. as well as the tooling involved in sending patches and patch series
   
  +
This document lays out basic examples and best practice of how to use StGit to manage Xen patches as part of the patch submission process. To be able to manage the patch contribution more easily, we [http://www.procode.org/stgit/ StGit], which is an application that runs on top of git and provides a functionality similar to Mercurial PatchQueue extension. This tutorial will show how to manage branches with git and StGit, so before proceeding please make sure that StGit is installed.
Xen uses [http://git-scm.com/ Git] for its source code management. The current Xen development tree is at http://xenbits.xen.org/gitweb/?p=xen.git;a=summary. Git provides excellent [http://git-scm.com/documentation documentation], please read it if this is your first time using Git. Download and install git to your system.
 
   
  +
Similar documents exist for
=== Recommended git extensions ===
 
  +
* '''Git''': see [[Managing Xen Patches with Git]].
  +
* '''git-series''' is a tool on top of Git that tracks changes to a patch series over time, including cover letter for the patch series, formats the series for email, and prepares patch submission. You can find instructions at [[Managing Xen Patches with Git-series]].
   
  +
== StGit Basics ==
To be able to manage patches better I recommend [http://www.procode.org/stgit/ StGit], which is an application that runs on top of git and provides a functionality similar to Mercurial PatchQueue extension. This tutorial will show how to manage patch queues with git and StgGit, so before proceeding please make sure that StGit is installed.
 
   
  +
StGit is a tool that runs on top of Git which allows you to manage patches in a stack on top of an existing git baseline. The stack of patches that have been created on top of your baseline maps to the patch series you are working on. To get started you have to initialise StGit on your working baseline (e.g. your current development branch of your repository using <code>stg init</code>).
=== Generating a patch ===
 
  +
----
 
  +
The, you add a new patch to your stack, with the following the basic workflow
Here's a recommendation on how to send patches, as suggested by the Xen maintainers.
 
  +
  +
<syntaxhighlight lang="sh" highlight="1,4,6">
  +
stg new <new-patch-id>
  +
...edit patch description
  +
...develop in the tree
  +
stg refresh
  +
...develop some more
  +
stg refresh
  +
</syntaxhighlight>
  +
  +
You can add several patches this way and then use <code>stg series</code> to list them. This shows your current stack of patches, where patches preceded by '''minus signs''' are not applied, patches preceded by '''plus signs''' are applied, while your '''current working patch''' is highlighted by a <code>></code> character in the <code>stg series</code> output. The current working patch is always also the current top of your stack of patches.
  +
  +
At any point you can edit the current tree to update your current working patch : Simply edit the files and use the <code>stg refresh</code> command to record your changes. You can use <code>stg refresh -e</code> to update the patch description as well. <code>stg show</code> will show the current (or any) patch.
  +
  +
You can manipulate the stack of patches using the <code>[http://procode.org/stgit/doc/stg-push.html push]</code>, <code>[http://procode.org/stgit/doc/stg-pop.html pop]</code>, <code>[http://procode.org/stgit/doc/stg-goto.html goto]</code>, <code>[http://procode.org/stgit/doc/stg-sink.html sink]</code> and <code>[http://procode.org/stgit/doc/stg-float.html float]</code> StGit commands. The most basic option to control the stack - and thus the current working patch - is a sequence of <code>pop</code> commands, followed by an edit-refresh cycle and a matching sequence of <code>push</code> commands. This works very well in a review cycle, where typically you move from one patch of a series to another. The <code>goto</code> command can be used if you need to move the current working patch by more than a few positions in the stack.
  +
  +
Before running any command the first time, we recommended that you at least quickly skim through its [http://procode.org/stgit/doc/stg.html man pages]. Many of the commands have very useful and interesting features that are not listed here: sometimes there are some extra notes which are very useful. Quick usage help is available for the StGit command using <code>stg help <command></code>.
  +
  +
If you want to rebase your series of patches against a different baseline, or just rebase an existing one you can use the <code>stg pull</code> command. It will pop all the patches, then update your current branch to the upstream revision using <code>git pull</code>, then push your patches back on top of the new base. If conflicts occur you need to resolve them and tell StGit using the <code>stg resolved</code> command and then update the patch using <code>stg refresh</code> and resume by performing a <code>stg push -a</code>.
  +
  +
== Generating an initial Patch or Patch Series ==
  +
Here's a recommendation on how to manage patches with StGit, as suggested by the Xen maintainers. Before you follow the instructions, you may want to read the following short discussion about whether to develop against [[Managing_Xen_Patches_with_Git#staging-master|<code>staging</code> or <code>master</code>]] branches. Unlike the [[Managing Xen Patches with Git|git guide]], this document assumes you are developing against <code>master</code>.
   
 
The first thing to do is cloning the xen git repository:
 
The first thing to do is cloning the xen git repository:
   
  +
<syntaxhighlight lang="sh" highlight="1,3">
<pre>
 
git clone git://xenbits.xen.org/xen.git
+
$ git clone git://xenbits.xen.org/xen.git
  +
$ cd xen
</pre>
 
  +
$ stg init
  +
</syntaxhighlight>
   
  +
This will create a new folder, called xen, and initialises StGit where you will work on your patches.
This will create a new folder, called xen, where you will work on your patches. We are going to create a branch for each series of patches that we are going to work on. This will allow a developer to work on several patch series at the same time, keeping the patches contained and well classified. Now we will create a new branch on top of the default branch, which is called "master".
 
   
  +
=== Create a branch for your changes ===
<pre>
 
  +
We are going to create a branch for each series of patches that we are going to work on. This will allow a developer to work on several patch series at the same time, keeping the patches contained and well classified. Now we will create a new branch on top of the default branch, which is called <code>master</code>
stg branch -c my_new_feature
 
</pre>
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
You are now working on a different branch, you can switch back to the "master" branch at any time by using:
 
  +
$ stg branch -c my_new_feature
  +
</syntaxhighlight>
   
  +
You are now working on a different branch, you can switch back to the <code>master</code> branch at any time by using:
<pre>
 
stg branch master
 
</pre>
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
Now that we are on the branch we wish to use to develop feature X we will start creating patches. The first thing to do is creating a new patch, StGit will ask for a description of the patch, but if unsure you can leave it blank and fill it later.
 
  +
$ stg branch master
  +
</syntaxhighlight>
   
  +
==== Set up a patch (this happens before you develop it) ====
<pre>
 
  +
Now that we are on the branch we wish to use to develop feature X we will start creating patches. The first thing to do is creating a new patch, StGit will ask for a description of the patch, but if unsure you can leave it blank and fill it later. The conventions related to what should be in commit messages are described in [[Submitting Xen Project Patches]]. The example below is merely intended to explain the necessary StGit commands: when you submit patches you will likely need more detail than shown in this document.
stg new first_patch_in_the_series
 
  +
</pre>
 
  +
<syntaxhighlight lang="sh" highlight="1">
  +
$ stg new first.patch
  +
</syntaxhighlight>
   
 
Here is an example of a simple description:
 
Here is an example of a simple description:
   
  +
<syntaxhighlight lang="sh" highlight="1">
<pre>
 
 
foobar: Add a new trondle calls
 
foobar: Add a new trondle calls
   
Line 44: Line 76:
   
 
Signed-off-by: Joe Smith <joe.smith@citrix.com>
 
Signed-off-by: Joe Smith <joe.smith@citrix.com>
  +
</syntaxhighlight>
</pre>
 
   
 
The first line in the description will be used as the subject when the patch is sent to the mailing list, so please make sure it contains an accurate description about what the patch is expected to introduce. It should be followed by a more accurate description and finally a "Signed-off-by".
 
The first line in the description will be used as the subject when the patch is sent to the mailing list, so please make sure it contains an accurate description about what the patch is expected to introduce. It should be followed by a more accurate description and finally a "Signed-off-by".
   
  +
==== Develop and Test your patch ====
Now you can starting modifying the code, all your changes will be contained inside this patch. When finished, you will have to refresh the patch, and create a new one on top if desired.
 
  +
Now you can starting modifying the code, all your changes will be contained inside this patch.
   
  +
==== Modify the commit message ====
<pre>
 
  +
If you want to modify the description of a patch, you should use the [http://procode.org/stgit/doc/stg-edit.html edit] command
stg refresh
 
stg new second_patch_in_the_series
 
</pre>
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
If you want to modify the description of a patch, you should use the [http://procode.org/stgit/doc/stg-edit.html edit] command:
 
  +
$ stg edit first.patch
  +
</syntaxhighlight>
   
  +
==== Refresh (commit) your patch ====
<pre>
 
  +
When finished, you will have to refresh the patch.
stg edit first_patch_in_the_series
 
</pre>
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
Also, if you want to move between the series, you can use the following StGit commands, [http://procode.org/stgit/doc/stg-push.html push], [http://procode.org/stgit/doc/stg-pop.html pop] and [http://procode.org/stgit/doc/stg-goto.html goto].
 
  +
$ stg refresh
  +
</syntaxhighlight>
   
  +
If you also want to edit the commit message, you can use
=== 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:
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
<pre>
 
  +
$ stg refresh -e
Developer's Certificate of Origin 1.1
 
  +
</syntaxhighlight>
   
  +
=== Develop a second patch in the patch series and commit it ===
By making a contribution to this project, I certify that:
 
  +
For further patches, you follow the same protocol as outlined in the previous section using a different name for your patch, starting with
   
  +
<syntaxhighlight lang="sh" highlight="1">
(a) The contribution was created in whole or in part by me and I
 
  +
$ stg new second.patch
have the right to submit it under the open source license
 
  +
</syntaxhighlight>
indicated in the file; or
 
   
  +
=== Working on patches in a Patch Series ===
(b) The contribution is based upon previous work that, to the best
 
  +
At this point, we currently have a two patch series consisting of <code>first.patch</code> and <code>second.patch</code>. We are going to add a <code>third.patch</code> as described before, which we can see using
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
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
(c) The contribution was provided directly to me by some other
 
  +
$ stg series --description
person who certified (a), (b) or (c) and I have not modified
 
  +
+ first.patch # My first patch
it.
 
  +
+ second.patch # My second patch
  +
> third.patch # My third patch
  +
</syntaxhighlight>
   
  +
StGit shows patches chronologically ordered from top to bottom. Note that this is the opposite from git log, which by default uses reverse chronological ordering. In the example, <code>third.patch</code> is your current working patch.
(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.
 
</pre>
 
   
  +
If for example you want to work on the first patch, you can choose to perform
=== 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>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 wrapped to a maximum of 80 columns.
 
==== Cc the maintainer of the code you are modifying ====
 
* 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 you should Cc the patches to them. You should always send patches to the xen-devel@lists.xen.org mailing list as well. The easier way to Cc the maintainers is to add the following field after your "Signed-off-by"
 
<pre>
 
Cc: Joseph Foo <joseph.foo@example.com>
 
</pre>
 
Then git will automagically add the Cc to the email when sending it.
 
=== Sending the patches to the list ===
 
----
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
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.
 
  +
$ stg pop
  +
$ stg pop
  +
</syntaxhighlight>
   
  +
or
==== Git format-patch and send-email ====
 
The most robust way to send files is by using the git [http://www.kernel.org/pub/software/scm/git/docs/git-format-patch.html format-patch] and [http://www.kernel.org/pub/software/scm/git/docs/git-send-email.html send-email] commands.
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
First, we will set up the configuration git send-email will use to send the patches. Edit your ~/.gitconfig file and add the following lines:
 
  +
$ stg goto first.patch
  +
</syntaxhighlight>
   
  +
showing the following
<pre>
 
[user]
 
name = John Smith
 
email = john.smith@example.com
 
[sendemail]
 
smtpserver = mail.example.com
 
smtpserverport = 25
 
smtpuser = johnsmith
 
</pre>
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
Now we can proceed to generate the patches and send them. We will use format-patch to generate the patches and send-email to send them to the mailing list.
 
  +
$ stg series --description
  +
> first.patch # My first patch
  +
- second.patch # My second patch
  +
- third.patch # My third patch
  +
</syntaxhighlight>
   
  +
The command
<pre>
 
git format-patch --subject-prefix="PATCH RFC" -o outgoing/ HEAD~2
 
</pre>
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
The format-patch command allows us to set a prefix to our patch series, in this case I want them to be marked as "RFC", if you don't need to include any specific prefix in the subject you don't need to specify "subject-prefix", and git will use the default one "PATCH X/Y". I've also used the "-o" option so format patch outputs the patches to the "outgoing" folder. Lastly you have to specify the first commit ID that will be used to generate your series. This can either be something like HEAD~3 if your series has 3 patches, and HEAD is the last patch in the series. Alternatively you can also use a commit ID instead of HEAD, and all commits on top of commit ID will be outputted.
 
  +
$ stg show
  +
</syntaxhighlight>
   
  +
shows you the current patch you are working on.
Before sending the patches it is recommended that you review them yourself, this can avoid sending patches that contain mistakes that could be avoided, and will allow you to send less revisions. After you have checked that the patches are fine, you can send them using the send-email git command.
 
   
  +
== Sending a Patch or Patch Series to xen-devel@ ==
<pre>
 
  +
You can find instructions on how to send patches in our [[Submitting_Xen_Project_Patches#send|Patch Submission Guide]]. It is important though, that the current working patch is the last patch in the series, otherwise you will submit only a subset of your series.
git send-email --compose outgoing/*
 
</pre>
 
   
  +
In the example above, you want to perform
The "compose" option will allow you to write an introductory email to the series. This is recommended, so the reviewer can understand easily what you are trying to accomplish with this series. Finally git will ask you the mail address where patches should be sent, which the user will have to fill with xen-devel@lists.xen.org.
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
==== Sending Patches Manually ====
 
  +
$ stg goto third.patch
  +
</syntaxhighlight>
   
  +
before executing the commands outlined in our [[Submitting_Xen_Project_Patches#send|Patch Submission Guide]].
It is strongly recommended to use the git send-email command discussed above. However it is possible to send a patch manually using your regular mail client.
 
   
  +
=== Creating outbound version branches ===
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.
 
  +
As as the case with a git workflow, you should create an outbound version branch after you sent a patch for review. This allows you to go back to previous versions easily. If you share a branch of a complex series in your cover letter as suggested here, it is important to do this, such that the branch remains static and code reviewers do not get confused by unexpected changes in the shared git branch.
   
  +
With stgit, you can do this with [http://procode.org/stgit/doc/stg-publish.html stg publish <outbound-branch-name>], which creates a new branch with the patches to publish. In other words, if used consistently you end you end up with a git branch that allows you to save your changes for each revision in a separate git branch.
=== Review, Rinse & Repeat ===
 
----
 
   
  +
You can also use the normal git workflow and push the changes to a remote branch, via <code>git push ... <stgit branch>:<remote branch name></code>.
After posting your patches you will hopefully see some response in the form of comments, patch review and eventually commit.
 
   
  +
== Addressing Review Comments ==
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!
 
  +
Addressing review comments in StGit is much easier than with git, as you can simply move between patches of your series as outlined below
   
  +
<syntaxhighlight lang="sh" highlight="1,4,6">
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.
 
  +
stg goto <patch-id>
  +
...modify the patch
  +
stg refresh -e
  +
</syntaxhighlight>
   
  +
and then update the commit message including the change log. This may look something like:
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, this can be easily accomplished by using the format-patch --subject-prefix option.
 
   
  +
<syntaxhighlight lang="diff" highlight="9-11" line>
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.
 
  +
xen/x86: Added trondle feature
   
  +
Because, ...
An example of a resend of a patch might be:
 
<pre>
 
Subject: [PATCH v2] foobar: Add a new trondle calls
 
   
  +
Signed-off-by: Joe Blogs <joe...@citrix.com>
Add a some new trondle calls to the foobar interface to support
 
  +
---
the new zot feature.
 
  +
CC: Another Colleague <ano...@citrix.com>
 
Signed-off-by: Joe Smith <joe.smith@citrix.com>
 
Acked-by: Jane Doe <jane.doe@example.com>
 
   
  +
Changes in v3:
---
 
  +
- s/nGRE/nGnRE/g
Changed since v1:
 
  +
- move security support clarification to a separate patch
* fix coding style
 
* be sure to treadle the trondle in the error case.
 
   
  +
Changes in v2:
diff -r 63531e640828 tools/libxc/Makefile
 
  +
- add #define LIBXL_HAVE_MEMORY_POLICY
--- a/tools/libxc/Makefile Mon Dec 07 17:01:11 2009 +0000
 
  +
- ability to part the memory policy parameter even if gfn is not passed
+++ b/tools/libxc/Makefile Mon Dec 21 11:45:00 2009 +0000
 
  +
- rename cache_policy to memory policy
...
 
  +
</syntaxhighlight>
</pre>
 
   
  +
== Common tasks ==
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 ([http://blog.xen.org/index.php/2009/09/16/submitting-patches-to-xen-org-community/ 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.
 
   
=== Common tasks ===
+
=== Rebasing a series ===
  +
If you are working on a big or controversial patch series, it is very likely that you will have to submit several versions of them, and you will need to rebase your code to match the changes that will be committed to the repository between each revision of your series. You can do that easily with [http://www.procode.org/stgit/doc/stg-rebase.html stg rebase]. The first step is to update the <code>master</code> branch of your repository.
----
 
If you are working on a big or controversial patch series, it is very likely that you will have to submit several versions of them, and you will need to rebase your code to match the changes that will be committed to the repository between each revision of your series. You can do that easily with [http://www.procode.org/stgit/doc/stg-rebase.html stg rebase]. The first step is to update the "master" branch of your repository.
 
   
  +
<syntaxhighlight lang="sh" highlight="1">
<pre>
 
stg branch master
+
$ stg branch master
git pull
+
$ git pull
  +
</syntaxhighlight>
</pre>
 
   
 
After that you will need to find the commit ID you want to rebase your series on top of, this can be done using git log. Once you have the commit ID, switch to the branch with your patches and execute:
 
After that you will need to find the commit ID you want to rebase your series on top of, this can be done using git log. Once you have the commit ID, switch to the branch with your patches and execute:
   
  +
<syntaxhighlight lang="sh" highlight="1">
<pre>
 
stg rebase <commit-id>
+
$ stg rebase <commit-id>
  +
</syntaxhighlight>
</pre>
 
   
 
This will pop all your patches, move the branch to the commit specified and then push your patches again. There's a chance that your patches don't apply cleanly on top of this commit, if this is the case stg will complain loudly, and you will have to manually edit the conflicting file. After editing the file, you can add it to your repository again and continue with the rebase:
 
This will pop all your patches, move the branch to the commit specified and then push your patches again. There's a chance that your patches don't apply cleanly on top of this commit, if this is the case stg will complain loudly, and you will have to manually edit the conflicting file. After editing the file, you can add it to your repository again and continue with the rebase:
   
  +
<syntaxhighlight lang="sh" highlight="1">
<pre>
 
git add <conflicting/file>
+
$ git add <conflicting/file>
stg refresh
+
$ stg refresh
stg push
+
$ stg push
  +
</syntaxhighlight>
</pre>
 
   
 
stg rebase is really useful, because it allows you to rebase your series on top of any commit, as an example, you can rebase one of your series on top of another, or rebase a series on top of staging changes.
 
stg rebase is really useful, because it allows you to rebase your series on top of any commit, as an example, you can rebase one of your series on top of another, or rebase a series on top of staging changes.
   
=== What If ===
+
== StGit Tutorials ==
  +
* [http://procode.org/stgit/doc/stg.html StGit Man Pages]
----
 
  +
* [https://events.linuxfoundation.org/sites/events/files/slides/An%20Introduction%20to%20Stacked%20Git.pdf An introduction to Stacked Git]
* Your patch is really big?
 
  +
* [http://procode.org/stgit/doc/tutorial.html StGit Tutorial]
** 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
 
 
=== 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/gitweb/?p=xen.git;a=shortlog;h=refs/heads/staging. They are then automatically tested, and if the tests pass the changes are propagated to the main tree http://xenbits.xen.org/gitweb/?p=xen.git;a=summary.
 
 
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.
 
   
 
[[Category:Developers]]
 
[[Category:Developers]]
 
[[Category:Development Process]]
 
[[Category:Development Process]]
 
[[Category:Xen]]
 
[[Category:Xen]]
 
== 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 [http://git-scm.com/ git] for revision control, are currently in use by Xen:
 
 
- [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=staging/qemu-upstream-unstable.git;a=summary qemu-xen]: new tree used for development, based on the latest stable branch of Upstream QEMU, that currently is available at [http://git.qemu.org/ 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 [http://git.qemu.org/qemu.git 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 ==
 
 
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).
 

Latest revision as of 11:14, 8 August 2019

This document assumes that you are familiar with the following documents

This document lays out basic examples and best practice of how to use StGit to manage Xen patches as part of the patch submission process. To be able to manage the patch contribution more easily, we StGit, which is an application that runs on top of git and provides a functionality similar to Mercurial PatchQueue extension. This tutorial will show how to manage branches with git and StGit, so before proceeding please make sure that StGit is installed.

Similar documents exist for

StGit Basics

StGit is a tool that runs on top of Git which allows you to manage patches in a stack on top of an existing git baseline. The stack of patches that have been created on top of your baseline maps to the patch series you are working on. To get started you have to initialise StGit on your working baseline (e.g. your current development branch of your repository using stg init).

The, you add a new patch to your stack, with the following the basic workflow

stg new <new-patch-id>
...edit patch description
...develop in the tree
stg refresh
...develop some more
stg refresh

You can add several patches this way and then use stg series to list them. This shows your current stack of patches, where patches preceded by minus signs are not applied, patches preceded by plus signs are applied, while your current working patch is highlighted by a > character in the stg series output. The current working patch is always also the current top of your stack of patches.

At any point you can edit the current tree to update your current working patch : Simply edit the files and use the stg refresh command to record your changes. You can use stg refresh -e to update the patch description as well. stg show will show the current (or any) patch.

You can manipulate the stack of patches using the push, pop, goto, sink and float StGit commands. The most basic option to control the stack - and thus the current working patch - is a sequence of pop commands, followed by an edit-refresh cycle and a matching sequence of push commands. This works very well in a review cycle, where typically you move from one patch of a series to another. The goto command can be used if you need to move the current working patch by more than a few positions in the stack.

Before running any command the first time, we recommended that you at least quickly skim through its man pages. Many of the commands have very useful and interesting features that are not listed here: sometimes there are some extra notes which are very useful. Quick usage help is available for the StGit command using stg help <command>.

If you want to rebase your series of patches against a different baseline, or just rebase an existing one you can use the stg pull command. It will pop all the patches, then update your current branch to the upstream revision using git pull, then push your patches back on top of the new base. If conflicts occur you need to resolve them and tell StGit using the stg resolved command and then update the patch using stg refresh and resume by performing a stg push -a.

Generating an initial Patch or Patch Series

Here's a recommendation on how to manage patches with StGit, as suggested by the Xen maintainers. Before you follow the instructions, you may want to read the following short discussion about whether to develop against staging or master branches. Unlike the git guide, this document assumes you are developing against master.

The first thing to do is cloning the xen git repository:

$ git clone git://xenbits.xen.org/xen.git
$ cd xen
$ stg init

This will create a new folder, called xen, and initialises StGit where you will work on your patches.

Create a branch for your changes

We are going to create a branch for each series of patches that we are going to work on. This will allow a developer to work on several patch series at the same time, keeping the patches contained and well classified. Now we will create a new branch on top of the default branch, which is called master

$ stg branch -c my_new_feature

You are now working on a different branch, you can switch back to the master branch at any time by using:

$ stg branch master

Set up a patch (this happens before you develop it)

Now that we are on the branch we wish to use to develop feature X we will start creating patches. The first thing to do is creating a new patch, StGit will ask for a description of the patch, but if unsure you can leave it blank and fill it later. The conventions related to what should be in commit messages are described in Submitting Xen Project Patches. The example below is merely intended to explain the necessary StGit commands: when you submit patches you will likely need more detail than shown in this document.

$ stg new first.patch

Here is an example of a simple description:

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>

The first line in the description will be used as the subject when the patch is sent to the mailing list, so please make sure it contains an accurate description about what the patch is expected to introduce. It should be followed by a more accurate description and finally a "Signed-off-by".

Develop and Test your patch

Now you can starting modifying the code, all your changes will be contained inside this patch.

Modify the commit message

If you want to modify the description of a patch, you should use the edit command

$ stg edit first.patch

Refresh (commit) your patch

When finished, you will have to refresh the patch.

$ stg refresh

If you also want to edit the commit message, you can use

$ stg refresh -e

Develop a second patch in the patch series and commit it

For further patches, you follow the same protocol as outlined in the previous section using a different name for your patch, starting with

$ stg new second.patch

Working on patches in a Patch Series

At this point, we currently have a two patch series consisting of first.patch and second.patch. We are going to add a third.patch as described before, which we can see using

$ stg series --description
+ first.patch  # My first patch
+ second.patch # My second patch
> third.patch  # My third patch

StGit shows patches chronologically ordered from top to bottom. Note that this is the opposite from git log, which by default uses reverse chronological ordering. In the example, third.patch is your current working patch.

If for example you want to work on the first patch, you can choose to perform

$ stg pop
$ stg pop

or

$ stg goto first.patch

showing the following

$ stg series --description
> first.patch  # My first patch
- second.patch # My second patch
- third.patch  # My third patch

The command

$ stg show

shows you the current patch you are working on.

Sending a Patch or Patch Series to xen-devel@

You can find instructions on how to send patches in our Patch Submission Guide. It is important though, that the current working patch is the last patch in the series, otherwise you will submit only a subset of your series.

In the example above, you want to perform

$ stg goto third.patch

before executing the commands outlined in our Patch Submission Guide.

Creating outbound version branches

As as the case with a git workflow, you should create an outbound version branch after you sent a patch for review. This allows you to go back to previous versions easily. If you share a branch of a complex series in your cover letter as suggested here, it is important to do this, such that the branch remains static and code reviewers do not get confused by unexpected changes in the shared git branch.

With stgit, you can do this with stg publish <outbound-branch-name>, which creates a new branch with the patches to publish. In other words, if used consistently you end you end up with a git branch that allows you to save your changes for each revision in a separate git branch.

You can also use the normal git workflow and push the changes to a remote branch, via git push ... <stgit branch>:<remote branch name>.

Addressing Review Comments

Addressing review comments in StGit is much easier than with git, as you can simply move between patches of your series as outlined below

stg goto <patch-id>
...modify the patch
stg refresh -e

and then update the commit message including the change log. This may look something like:

 1 xen/x86: Added trondle feature
 2 
 3 Because, ...
 4 
 5 Signed-off-by: Joe Blogs <joe...@citrix.com> 
 6 --- 
 7 CC: Another Colleague <ano...@citrix.com> 
 8 
 9 Changes in v3:
10 - s/nGRE/nGnRE/g
11 - move security support clarification to a separate patch
12 
13 Changes in v2:
14 - add #define LIBXL_HAVE_MEMORY_POLICY
15 - ability to part the memory policy parameter even if gfn is not passed
16 - rename cache_policy to memory policy

Common tasks

Rebasing a series

If you are working on a big or controversial patch series, it is very likely that you will have to submit several versions of them, and you will need to rebase your code to match the changes that will be committed to the repository between each revision of your series. You can do that easily with stg rebase. The first step is to update the master branch of your repository.

$ stg branch master
$ git pull

After that you will need to find the commit ID you want to rebase your series on top of, this can be done using git log. Once you have the commit ID, switch to the branch with your patches and execute:

$ stg rebase <commit-id>

This will pop all your patches, move the branch to the commit specified and then push your patches again. There's a chance that your patches don't apply cleanly on top of this commit, if this is the case stg will complain loudly, and you will have to manually edit the conflicting file. After editing the file, you can add it to your repository again and continue with the rebase:

$ git add <conflicting/file>
$ stg refresh
$ stg push

stg rebase is really useful, because it allows you to rebase your series on top of any commit, as an example, you can rebase one of your series on top of another, or rebase a series on top of staging changes.

StGit Tutorials