Managing Xen Patches with Git-series
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
This document lays out a very basic example on how to use git-series. Git series is an add-on to git implemented in Rust.
For installation instructions see https://github.com/git-series/git-series/blob/master/README.md Before you install git-series, you will need to have install if not on your system yet
- Rust: see https://www.rust-lang.org/tools/install
- cmake: see https://cmake.org/download/ - note that this dependency is not documented in the git-series README file, which is why it is covered here. Also note that after an install, the command line tools are not installed automatically for all operating systems. Go to the UI and select Tools > How to Install for Command line use.
Similar documents exist for
Before you consider using git-series, please check out the following youtube video:
- Minutes 0:00 to 13:28: Explains the problem that git-series solves. Note that this is worthwhile watching regardless of whether you choose to use git-series
- Minutes 13:28 to 24:30: Demo of git-series
- Minutes 24:30 to 40:24: How does git-series work internally and interacts with git
- Minutes 24:30 to end: Discussion - worthwhile watching
Git-series integrates primarily with the workflow as outlined in Managing Xen Patches with Git with some differences:
- It does not require you to create a branch for your work
- It allows you to seamlessly work on multiple series by switching between them
- It retains the history of working on your series (when you use Managing Xen Patches with Git, you have to create branches manually to achieve the same effect): you can easily go back to older versions of a series if you need to
- It allows for very easy re-basing of a series onto a different base branch
- It understands and tracks the concept of a cover letter
- It seamlessly integrates into the workflow
Compared to Managing Xen Patches with StGit, git-series does not give you the capability to switch seamlessly between patches in your series. You will have to use the workflow as outlined in Using autosquash to optimize the workflow.
Generating an initial Patch Series
The basic workflow looks as follows:
# Start the series $ git series start my-featurename # Create or edit the cover letter: the first line of the cover letter is the title # as it appears in the e-mail $ git series cover # Before you start your work you need to base your patch series on a baseline, such as $ git checkout my-baseline # e.g. master, staging, etc. $ git series base HEAD # Make your changes in the usual way using git commits for individual patches ... # Now commit and format the series and format it for sending $ git series commit -a -m 'Version 1 of series'
git series log: show the history of the series
git series status: shows any changes staged for the next git series commit
git series checkout: switch between patch series you work on - uncommitted changes are saved
git series rebase: rebase series onto a different baseline or interactively using
Sending a Patch Series to xen-devel@
The main difference between the work-flow outlined in Managing Xen Patches with Git and this workflow is
that instead of using
git format, you must use
git series format in
step 1. The command
has fewer options compared to
git format, most notably the
-ocommand is missing: this means patches are always stored in your git root
--threadis always used by default and does not need to be specified
$ git series format
The following command line options can be used as normal:
[-v N | --reroll-count=N]
Step 2 is then used with the following modification
$ ./scripts/add_maintainers.pl -d .
while step 3 is exactly followed as outlined in the workflow.
Addressing Review Comments
Addressing review comments happens following the workflow as outlined in Addressing Review Comments.
# Make your changes in the usual way using git commits and autosquash for # individual patches ... # Update the cover letter and add what you changed in this version $ git series cover # Now commit and format the series and format it for sending $ git series commit -a -m 'Version 2 of series' $ git series format --reroll-count=2