Patchqueue Guidelines

We patch many components in OpenXT but we currenly have some big patchques:

• xen
• linux
• qemu
• refpolicy

Working with these can be confusing at times, this page is an attempt to clarify that.

First, patchqueues are handled using quilt. Please read Dealing with quilt

The general idea

The main concept we try to enforce in our patchqueues is to regroup modification into feature-based patches.

This means if you're writing a new feature, you want to write a new patch, and if you're fixing a bug in an OpenXT feature, you'll amend an existing patch.

In the case where you're fixing a bug that's not part of an OpenXT feature, then making a new patch usually makes the most sense (ideally a backport of an upstream patch).

The case of refpolicy

"refpolicy" is the SELinux Reference Policy (https://github.com/TresysTechnology/refpolicy).

In OpenXT, we use it as a base for our SELinux policy.

We have a bunch of patches against it, but most of what we do is create new modules for OpenXT-specific components.

Those 2 kinds of modifications used to be (and still are in stable-5 and stable-4) all part of one big patchqueue.

It was confusing, so we decided to stop using patches to create all those new files, and use patches only for what we're ... patching.

We now have a bunch of new files, that we overlay on top of the refpolicy tree, plus the patches against the refpolicy bits.

So now, when working in the refpolicy patchqueue, if your modification is against an original refpolicy file, then update/create a patch.

However, if the modification is in an OpenXT module, just modify the file in xenclient-oe.

The patch comment header

In the bigger patch repos we use a standard patch comment header at the beginning of all patches. It basically looks like the example below. If you are adding patches, please use this comment block format. If you are changing patched, please update the comment block where appropriate. If you are not sure if the patch queue is one that uses the comment block, look at the other patches. The primary patch queues that use it are Linux/Xen/QEMU/TBOOT.

################################################################################
SHORT DESCRIPTION: 
################################################################################
One or two lines...

################################################################################
LONG DESCRIPTION: 
################################################################################
As many lines as it takes for describe the patch. If this patch is really just
a port from somewhere else, you can just reference the original patches
information.

################################################################################
CHANGELOG 
################################################################################
Original: John Doe, john.doe@buck.com
Ported: Jane Doe, jane.doe@fawn.com, 8/27/2015
etc...

################################################################################
REMOVAL 
################################################################################
If there are conditions where it can be removed, explain them here. If not then
leave it blank.

################################################################################
UPSTREAM PLAN 
################################################################################
If there is a plan to upstream it, explain it here. If there is none, leave it
blank.

################################################################################
INTERNAL DEPENDENCIES 
################################################################################
Does this patch have dependencies on other patches etc. If not, leave it blank.

################################################################################
PATCHES 
################################################################################
(Actual patches start right here)