Difference between revisions of "Managing Xen Patches with Git"

From Xen
(Reworked for staging rather than master; Added: "Addressing Review Comments")
Line 31: Line 31:
 
This process automatically creates a local branch called <code>master</code> that will track the XenProject.org branch called <code>master</code>.
 
This process automatically creates a local branch called <code>master</code> that will track the XenProject.org branch called <code>master</code>.
   
The branch called <code>staging</code> is the bleeding-edge of commits; this is tested regularly with the <code>xen.org</code> build and regression testing system, and when it pases, is pushed to the <code>master</code> branch. It is suggested to develop patches based on the <code>master</code> branch.
+
The branch called <code>staging</code> is the bleeding-edge of commits: this branch is tested regularly with the <code>xenproject.org</code> build and regression testing system, and when it passes, changes are pushed to the <code>master</code> branch. However, <code>master</code> can be significantly behind <code>staging</code>.
  +
  +
From the contributor's point of view, this gives a choice of
  +
* Use <code>staging</code> as a development baseline and have it apply easily to the tree when all changes are approved. This exposes you to the risk of importing showstopper bugs which prevent you from building or testing. This happens very infrequently, which is why we recommend that people '''develop against staging'''.
  +
* Use <code>master</code> which may mean that your change wont apply to <code>staging</code>. When this occurs your committer ought to try and resolve merge conflicts: however this does not always happen. Thus, it makes sense to rebase against <code>staging</code> when you are close to completing the code review process.
  +
  +
The remainder of this document assumes you develop against the <code>staging</code> branch.
   
 
=== Create a branch for your changes ===
 
=== Create a branch for your changes ===
When you want to introduce a change, start by making a new branch based on the most recent change in the <code>master</code> branch.
+
When you want to introduce a change, start by making a new branch based on the most recent change in the <code>staging</code> branch.
  +
  +
<syntaxhighlight lang="sh" highlight="1">
  +
$ git checkout -b staging remotes/origin/staging
  +
Branch staging set up to track remote branch staging from origin.
  +
Switched to a new branch 'staging'
  +
</syntaxhighlight>
   
 
<syntaxhighlight lang="sh" highlight="1">
 
<syntaxhighlight lang="sh" highlight="1">
$ git checkout -b out/trondle-calls master
+
$ git checkout -b out/trondle-calls staging
 
Switched to a new branch 'out/trondle-calls'
 
Switched to a new branch 'out/trondle-calls'
 
</syntaxhighlight>
 
</syntaxhighlight>
Line 80: Line 92:
 
Every single commit you make on your branch becomes a patch when you submit it. If your change consists of multiple commits, you will be committing a patch series. Information related to Xen Project conventions around patches and patch series can be found [[Submitting_Xen_Project_Patches#What_is_in_a_patch_and_a_patch_series.3F|here]].
 
Every single commit you make on your branch becomes a patch when you submit it. If your change consists of multiple commits, you will be committing a patch series. Information related to Xen Project conventions around patches and patch series can be found [[Submitting_Xen_Project_Patches#What_is_in_a_patch_and_a_patch_series.3F|here]].
   
  +
== Sending a Patch to xen-devel@ ==
 
== Sending a patch 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 ==
+
== Addressing Review Comments ==
  +
Once you sent the initial patch or patch series, you are likely to get review comments on each patch or just some of them. Let's assume you have just sent v1 of a series on <code>my-feature-branch</code> which is made up of the following three patches.
   
=== Changes based on staging ===
 
If you want to make a local branch based on <code>staging</code> rather than <code>master</code> (for example, to fix a changeset which has caused the XenProject.org nightly testing to fail), you can do the following:
 
 
<syntaxhighlight lang="sh" highlight="1">
 
<syntaxhighlight lang="sh" highlight="1">
  +
$ git log --oneline --decorate
$ git checkout -b staging remotes/origin/staging
 
  +
ccc3333 (HEAD, my-feature-branch) My third patch
Branch staging set up to track remote branch staging from origin.
 
  +
bbb2222 My second patch
Switched to a new branch 'staging'
 
  +
aaa1111 My first patch
  +
9999999 (master) Old stuff on master
 
</syntaxhighlight>
 
</syntaxhighlight>
Then in the commands above, you would use "staging" instead of "master" as the base branch.
 
...
 
   
  +
You got feedback that needs to be addressed on the first patch and the second patch which requires re-working these patches. When re-sending the series, you are expected to '''retain the order and number''' of patches in the second revision.
  +
  +
You could just commit these two changes with a message like “Fix first patch” and "Fix second patch" and worry about squashing it later, but then you have to remember which commit fixes which patch and manually re-order the list of commits in an interactive rebase. Git can do all of this automatically.
  +
  +
== References ==
  +
* [https://git-scm.com/docs/ All git docs]
  +
* [https://git-scm.com/docs/git-commit git-commit]
  +
* [https://git-scm.com/docs/git-rebase git-rebase]
   
 
[[Category:Developers]]
 
[[Category:Developers]]

Revision as of 15:09, 7 August 2019

This document assumes that you are familiar with the following documents

It lays out basic examples and best practice of how to use Git to manage Xen patches as part of the submission process.

Similar documents exist for

  • StGit, a Python application providing similar functionality to Quilt (i.e. pushing/popping patches to/from a stack) on top of Git. You can find instructions at Managing Xen Patches with StGit.

Generating an initial Patch or Patch Series

Begin by cloning the git repo from XenProject.org:

$ git clone git://xenbits.xenproject.org/xen.git xen.git

At this point you should have xenbits set up as the remote repostiory called "origin":

$ git branch -a
* master
  remotes/origin/HEAD -> origin/master
  remotes/origin/master
  remotes/origin/stable-4.0
  remotes/origin/stable-4.1
  remotes/origin/stable-4.2
  remotes/origin/staging
  remotes/origin/staging-4.0
  remotes/origin/staging-4.1
  remotes/origin/staging-4.2

This process automatically creates a local branch called master that will track the XenProject.org branch called master.

The branch called staging is the bleeding-edge of commits: this branch is tested regularly with the xenproject.org build and regression testing system, and when it passes, changes are pushed to the master branch. However, master can be significantly behind staging.

From the contributor's point of view, this gives a choice of

  • Use staging as a development baseline and have it apply easily to the tree when all changes are approved. This exposes you to the risk of importing showstopper bugs which prevent you from building or testing. This happens very infrequently, which is why we recommend that people develop against staging.
  • Use master which may mean that your change wont apply to staging. When this occurs your committer ought to try and resolve merge conflicts: however this does not always happen. Thus, it makes sense to rebase against staging when you are close to completing the code review process.

The remainder of this document assumes you develop against the staging branch.

Create a branch for your changes

When you want to introduce a change, start by making a new branch based on the most recent change in the staging branch.

$ git checkout -b staging remotes/origin/staging
Branch staging set up to track remote branch staging from origin.
Switched to a new branch 'staging'
$ git checkout -b out/trondle-calls staging
Switched to a new branch 'out/trondle-calls'

Develop and Test your change

Then edit the source files you want to change. You can see which files have changed by using git status.

Commit your change to your branch

When you're done editing, use git add to specify which file changes you want included in the changeset, and then use git commit to make a commit. You will be prompted to make a changset description. 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 git commands: when you submit patches you will likely need more detail than shown in this document.

$ git status
# On branch out/trondle-calls
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
#	modified:   foobar/zot.c
#	modified:   foobar/zot.h
#
no changes added to commit (use "git add" and/or "git commit -a")
$ git add foobar/zot.c foobar/zot.h
$ git commit

Alternatively, you can commit all changes using "git commit -a":

$ git commit -a
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>

Patches vs. Patch Series

Every single commit you make on your branch becomes a patch when you submit it. If your change consists of multiple commits, you will be committing a patch series. Information related to Xen Project conventions around patches and patch series can be found here.

Sending a Patch to xen-devel@

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

Addressing Review Comments

Once you sent the initial patch or patch series, you are likely to get review comments on each patch or just some of them. Let's assume you have just sent v1 of a series on my-feature-branch which is made up of the following three patches.

$ git log --oneline --decorate
ccc3333 (HEAD, my-feature-branch) My third patch
bbb2222 My second patch
aaa1111 My first patch
9999999 (master) Old stuff on master

You got feedback that needs to be addressed on the first patch and the second patch which requires re-working these patches. When re-sending the series, you are expected to retain the order and number of patches in the second revision.

You could just commit these two changes with a message like “Fix first patch” and "Fix second patch" and worry about squashing it later, but then you have to remember which commit fixes which patch and manually re-order the list of commits in an interactive rebase. Git can do all of this automatically.

References