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

• Git: see Managing Xen Patches with Git.
• StGit: see Managing Xen Patches with StGit.

Git-series Basics

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 19:43: Instructions on how to format a series and send pull requests based on one
  • Minutes 20:20: Working on multiple series in parallel
• 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'

Useful commands:

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

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

• -o command is missing: this means patches are always stored in your git root
• --thread is 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]
• [--rfc]
• [--subject-prefix=Subject-Prefix]

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

git-series Tutorials

• README
• Man Page
• Video recording of git-series with demo