Difference between revisions of "Managing Xen Patches with StGit"

From Xen
(Add a link to the similar git-series document)
(Updated the guide to make it more comprehensive)
Line 8: Line 8:
 
* '''Git''': see [[Managing Xen Patches with Git]].
 
* '''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]].
 
* '''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 ==
 +
 +
StGit is a tools 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>).
 +
 +
The, you add a new patch to your stack, with the following the basic workflow
 +
 +
<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 options to control the stack and thus the current working patch through 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 ==
 
== Generating an initial Patch or Patch Series ==
Here's a recommendation on how to send patches, 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>.
+
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">
+
<syntaxhighlight lang="sh" highlight="1,3">
 
$ git clone git://xenbits.xen.org/xen.git
 
$ git clone git://xenbits.xen.org/xen.git
 
$ cd xen
 
$ cd xen
 +
$ stg init
 
</syntaxhighlight>
 
</syntaxhighlight>
  
This will create a new folder, called xen, where you will work on your patches.
+
This will create a new folder, called xen, and initialises StGit where you will work on your patches.
  
 
=== Create a branch for your changes ===
 
=== Create a branch for your changes ===
Line 33: Line 59:
 
$ stg branch master
 
$ stg branch master
 
</syntaxhighlight>
 
</syntaxhighlight>
 
=== Develop a patch in the patch series and commit it ===
 
  
 
==== Set up a patch (this happens before you develop it) ====
 
==== Set up a patch (this happens before you develop it) ====
Line 40: Line 64:
  
 
<syntaxhighlight lang="sh" highlight="1">
 
<syntaxhighlight lang="sh" highlight="1">
$ stg new first_patch_in_the_series
+
$ stg new first.patch
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 60: Line 84:
  
 
==== Modify the commit message ====
 
==== Modify the commit message ====
If you want to modify the description of a patch, you should use the [http://procode.org/stgit/doc/stg-edit.html edit] command:
+
If you want to modify the description of a patch, you should use the [http://procode.org/stgit/doc/stg-edit.html edit] command
  
 
<syntaxhighlight lang="sh" highlight="1">
 
<syntaxhighlight lang="sh" highlight="1">
$ stg edit first_patch_in_the_series
+
$ stg edit first.patch
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 71: Line 95:
 
<syntaxhighlight lang="sh" highlight="1">
 
<syntaxhighlight lang="sh" highlight="1">
 
$ stg refresh
 
$ stg refresh
 +
</syntaxhighlight>
 +
 +
If you also want to edit the commit message, you can use
 +
 +
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg refresh -e
 
</syntaxhighlight>
 
</syntaxhighlight>
  
Line 77: Line 107:
  
 
<syntaxhighlight lang="sh" highlight="1">
 
<syntaxhighlight lang="sh" highlight="1">
$ stg new second_patch_in_the_series
+
$ stg new second.patch
 
</syntaxhighlight>
 
</syntaxhighlight>
  
=== Moving between patches ===
+
=== Working on patches in a Patch Series ===
 +
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
  
If you want to move on to a different patch in 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].
+
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg series --description
 +
+ first.patch  # My first patch
 +
+ 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.
 +
 
 +
If for example you want to work on the first patch, you can choose to perform
 +
 
 +
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg pop
 +
$ stg pop
 +
</syntaxhighlight>
 +
 
 +
or
 +
 
 +
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg goto first.patch
 +
</syntaxhighlight>
 +
 
 +
showing the following
 +
 
 +
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg series --description
 +
> first.patch  # My first patch
 +
- second.patch # My second patch
 +
- third.patch  # My third patch
 +
</syntaxhighlight>
 +
 
 +
The command
 +
 
 +
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg show
 +
</syntaxhighlight>
 +
 
 +
shows you the current patch you are working on.
  
 
== Sending a Patch or Patch Series to xen-devel@ ==
 
== Sending a Patch or Patch Series to xen-devel@ ==
You can find instructions on how to send patches in our [[Submitting_Xen_Project_Patches#send|Patch Submission Guide]].
+
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.
 +
 
 +
In the example above, you want to perform
 +
 
 +
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg goto third.patch
 +
</syntaxhighlight>
 +
 
 +
before executing the commands outlined in our [[Submitting_Xen_Project_Patches#send|Patch Submission Guide]].
 +
 
 +
== 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
 +
 
 +
<syntaxhighlight lang="sh" highlight="1,4,6">
 +
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:
 +
 
 +
<syntaxhighlight lang="diff" highlight="9-11" line>
 +
xen/x86: Added trondle feature
 +
 
 +
Because, ...
 +
 
 +
Signed-off-by: Joe Blogs <joe...@citrix.com>
 +
---
 +
CC: Another Colleague <ano...@citrix.com>
 +
 
 +
Changes in v3:
 +
- s/nGRE/nGnRE/g
 +
- move security support clarification to a separate patch
 +
 
 +
Changes in v2:
 +
- add #define LIBXL_HAVE_MEMORY_POLICY
 +
- ability to part the memory policy parameter even if gfn is not passed
 +
- rename cache_policy to memory policy
 +
</syntaxhighlight>
  
 
== Common tasks ==
 
== Common tasks ==
Line 114: Line 220:
  
 
== StGit Tutorials ==
 
== 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]
 
* [https://events.linuxfoundation.org/sites/events/files/slides/An%20Introduction%20to%20Stacked%20Git.pdf An introduction to Stacked Git]
 
* [http://procode.org/stgit/doc/tutorial.html StGit Tutorial]
 
* [http://procode.org/stgit/doc/tutorial.html StGit Tutorial]

Revision as of 08:05, 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 tools 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 options to control the stack and thus the current working patch through 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.

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