Difference between revisions of "Managing Xen Patches with StGit"

From Xen
m (Removed extra formatting)
(Brought the document structure and formatting into line with Managing_Xen_Patches_with_Git)
Line 1: Line 1:
{{InfoLeft|This page applies to the following '''all subprojects and teams''': [http://xenproject.org/developers/teams/pvops.html PVOPS], [http://xenproject.org/developers/teams/hypervisor.html Hypervisor], [http://xenproject.org/developers/teams/arm-hypervisor.html ARM Hypervisor], [http://xenproject.org/developers/teams/embedded-and-automotive.html Embedded and Automotive PV Drivers] and [http://xenproject.org/developers/teams/windows-pv-drivers.html Windows PV Drivers]. You will find repository information on each team's each webpage!}}
+
This document assumes that you are familiar with the following documents
 +
* [[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
  
== How To Generate and Submit a Patch to Xen using StGit ==
+
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 Project Hypervisor 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. Trees of other teams are listed on [http://xenproject.org/developers/teams.html each teams website] (typically in a highlighted box on the right of each page called ''<Project Name> Resources'' or ''<Project Name> Code'') or our [http://xenbits.xen.org/gitweb/ gitweb instance].
+
Similar documents exist for  
 +
* '''Git''': see [[Managing Xen Patches with Git]].
  
=== Recommended git extensions ===
+
== 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>.
  
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 branches with git and StGit, so before proceeding please make sure that StGit is installed.
+
The first thing to do is cloning the xen git repository:
  
=== Generating a patch series===
+
<syntaxhighlight lang="sh" highlight="1">
Here's a recommendation on how to send patches, as suggested by the Xen maintainers.  
+
$ git clone git://xenbits.xen.org/xen.git
 +
$ cd xen
 +
</syntaxhighlight>
  
<br>
+
This will create a new folder, called xen, where you will work on your patches.
{{InfoLeft|This guide primarily explains how to use StGit: for '''a complete description of conventions related to sending patches, see [[Submitting Xen Project Patches]]'''.}}
 
  
The first thing to do is cloning the xen git repository:
+
=== 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 <code>master</code>
  
<pre>
+
<syntaxhighlight lang="sh" highlight="1">
git clone git://xenbits.xen.org/xen.git
+
$ stg branch -c my_new_feature
</pre>
+
</syntaxhighlight>
  
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".
+
You are now working on a different branch, you can switch back to the <code>master</code> branch at any time by using:
  
<pre>
+
<syntaxhighlight lang="sh" highlight="1">
stg branch -c my_new_feature
+
$ stg branch master
</pre>
+
</syntaxhighlight>
  
You are now working on a different branch, you can switch back to the "master" branch at any time by using:
+
=== Develop a patch in the patch series and commit it ===
  
<pre>
+
==== Set up a patch (this happens before you develop it) ====
stg branch master
+
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.
</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.
+
<syntaxhighlight lang="sh" highlight="1">
 
+
$ stg new first_patch_in_the_series
<pre>
+
</syntaxhighlight>
stg new first_patch_in_the_series
 
</pre>
 
  
 
Here is an example of a simple description:
 
Here is an example of a simple description:
  
<pre>
+
<syntaxhighlight lang="sh" highlight="1">
 
foobar: Add a new trondle calls
 
foobar: Add a new trondle calls
  
Line 48: Line 51:
  
 
Signed-off-by: Joe Smith <joe.smith@citrix.com>
 
Signed-off-by: Joe Smith <joe.smith@citrix.com>
</pre>
+
</syntaxhighlight>
  
 
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".
  
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.
+
==== 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 [http://procode.org/stgit/doc/stg-edit.html edit] command:
 +
 
 +
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg edit first_patch_in_the_series
 +
</syntaxhighlight>
  
<pre>
+
==== Refresh (commit) your patch ====
stg refresh
+
When finished, you will have to refresh the patch.
stg new second_patch_in_the_series
 
</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:
+
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg refresh
 +
</syntaxhighlight>
 +
 
 +
=== 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
 +
 
 +
<syntaxhighlight lang="sh" highlight="1">
 +
$ stg new second_patch_in_the_series
 +
</syntaxhighlight>
  
<pre>
+
=== Moving between patches ===
stg edit first_patch_in_the_series
 
</pre>
 
  
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].
+
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].
  
=== Sending a patch 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]].
  
=== Common tasks ===
+
== Common tasks ==
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.
+
 
 +
=== 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.
  
<pre>
+
<syntaxhighlight lang="sh" highlight="1">
stg branch master
+
$ stg branch master
git pull
+
$ git pull
</pre>
+
</syntaxhighlight>
  
 
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:
  
<pre>
+
<syntaxhighlight lang="sh" highlight="1">
stg rebase <commit-id>
+
$ stg rebase <commit-id>
</pre>
+
</syntaxhighlight>
  
 
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:
  
<pre>
+
<syntaxhighlight lang="sh" highlight="1">
git add <conflicting/file>
+
$ git add <conflicting/file>
stg refresh
+
$ stg refresh
stg push
+
$ stg push
</pre>
+
</syntaxhighlight>
  
 
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.

Revision as of 19:19, 7 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

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 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

This will create a new folder, called xen, 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

Develop a patch in the patch series and commit it

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_in_the_series

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_in_the_series

Refresh (commit) your patch

When finished, you will have to refresh the patch.

$ stg refresh

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_in_the_series

Moving between patches

If you want to move on to a different patch in the series, you can use the following StGit commands, push, pop and goto.

Sending a Patch or Patch Series to xen-devel@

You can find instructions on how to send patches in our Patch Submission Guide.

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