SUSE Linux Enterprise Patch Policy

----------------------------------

Summary

-------

The SUSE Linux Enterprise (SLE) patch policy mirrors the mainline Linux

community's policy for accepting changes.  Each commit must contain a

small and "obvious" change that can be reviewed individually and, once

applied, be able to be used as a bisection point.  The kernel should be

able to build (and boot) between each applied patch.  Since the SLE

kernel is based on an official upstream kernel release and is followed by

a hardening process, we expect that nearly all of the patches applied to the

base release will be from subsequent official upstream releases indended to

address specific issues or to allow for hardware/feature enablement.

Background

----------

Before covering the policy itself, we'll discuss a bit of background on

how the source code tree is organized.  If you've used the SLE kernel source

(kernel-source.git[1]) tree before, you've probably noticed that, unlike

the mainline Linux kernel, we don't use a source-level git repository as

our "base."  Instead, we use an official kernel.org Linux tar archive as

the base and add a series of patches on top of it.  This carries with it

several benefits.  The biggest is that we add metadata "tags" to our

patches that allow us to easily associate patches with particular feature

requests, bug reports, and/or the pedigree of the patch.  Due to the nature

of some of our feature requests, we also must occasionally carry patches

that, for one reason or another, haven't been accepted into the mainline

kernel repository yet.  With a full (published[2]) git repository, it would

be difficult to associate the initial commit for a particular feature with

any subsequent changes to it.  Another benefit is more superficial: with the

use of separate patches, we (and our users) are able to tell, at a glance,

which patches are in any given kernel release simply by looking at

the source package.  Patches are grouped into subsystems (including

architecture, "core" vm/scheduler, VFS, individual file systems, driver

core, networking core, block layer, and leaf drivers) so finding patches

that affect a particular part of the kernel can be easily found.  Patches

are placed in directories such as patches.fixes, patches.suse, etc.  When

submitting patches for inclusion, it's not necessary to choose a directory.

We'll put them in the appropriate place.

Historically, this approach has worked well but has limited options for

typical debugging techniques such as bisection.  The application of the

patch series results in our fully operational SLE kernel but stopping

the patch series midway can result in an unbuildable source tree.  

Beginning with the SLE11 SP2 development cycle, we've published a fully

expanded git repository (kernel.git[2]) that exactly represents the code

as if it were originally used as a standard source code tree repository.

This allows us to work with the individual patches *and* have the ability

to bisect the tree as the changes are applied.  It also makes it easier for

partners unfamiliar with how our source tree works to make the transition.

Format

------

The SLE patch format follows very closely what you would see on any

mailing list associated with Linux kernel development.  A SLE patch is

formatted like an RFC822 mbox-style mail message, with a few extensions.

If the patch is coming from the mainline Linux repository or a subsystem

maintainer repository, SUSE has tools published here[3] that can make

adding these tags nearly painless.

Each patch should contain the "From" and "Subject" headers found in any

email message.  The From should contain the name and email address of the

patch author.  The Subject should contain a short description of the

patch, prefixed with the subsystem affected.

e.g.

From: Jeff Mahoney <jeffm@suse.com>

Subject: init: print hello world at boot time

Beyond that, we require several more headers, the full description of

the patch, the certification tags used in the mainline kernel, and the patch

contents.

The headers we require are as follows:

Git-commit: [a-f0-9]{40}

- Contains the SHA-1 git commit ID of the patch in either the mainline

  kernel repository[4] or an official maintainer repository.

Git-repo: URL-to-git-repo (starting with git://)

- The URL to the git repository containing the commit.  This tag can be

  omitted if the commit is from the mainline kernel repository.

Patch-mainline: vMajor.Minor.Patch{-optional-rc}

- The official kernel release that contains this patch.  In the case of a

  patch accepted into a maintainer branch, "Queued in subsystem

  maintainer repo" can be used.  If the patch has been submitted to a

  subsystem mailing list for review and is nearly certain to be accepted,

  "Submitted <date> <list@site.org>" can be used.  Otherwise, if the

  patch will never be in the upstream kernel, e.g. in the case of

  vendor-specific

  version numbers, etc, then "No" followed by the reason why it will

  not be accepted (or submitted).  Please note that the reason must be

  compelling for it to be allowed into our kernel repository.

References: list of references

- There must be a reason for each patch to be included into the kernel

  repository.  It can be a fix in response to a bug report or a patch

  submitted as part of the feature development cycle for a release.  We

  use a shorthand to indicate why a particular patch will be included

  and it's possible to use more than one.

  For Feature requests, the feature will have to have gone through our

  feature tracking tool, FATE.  Each feature request will have an ID

  associated with it and it can be added to the References tag using

  FATE#number, e.g. FATE#12345.

  For fixes for bug reports (or patches for feature requests submitted

  via Bugzilla, the shorthand is bnc#number.  bnc is shorthand for

  bugzilla.novell.com.  There are others such as bko, for

  bugzilla.kernel.org.

Next is the full description of the patch, which should explain why the

patch is needed and an overview of what it does. 

The last "header" portion of the patch contains the certification tags, which

consist of "Signed-off-by" and "Acked-by." We, and the upstream Linux

community depend on patch submitters to "own" their submission and certify

they have the right to submit code to the kernel repository.  For patches

coming from the mainline Linux kernel repository, the certification tags

are already in place and we only need the submitter's tag added (if not

already part of the original patch).  Likewise, the SUSE engineer who

includes the submission in our kernel tree, will add their own "Acked-by"

tag.

There may be an optional diffstat -p1 output added before the patch content.

The patch content itself should be in "-ab" format where the patch header

itself only contains the filename without any timestamps.

Here's an example of a complete patch:

-------->8--------

From: Upstream Committer <coder@somesite.com>

Subject: init: print hello world on boot

Patch-mainline: v3.8-rc1

Git-commit: deadbeefc0ffeeb1a4b1a4b1a4b1a4b1a4b1a4b1a4

References: FATE#12134 bnc#23123

The kernel started off like every other project.  Let's add the hello

world message in honor of its roots.

Signed-off-by: Upstream Committer <coder@somesite.com>

Tested-by: Bill User <bill.user@example.com>

Acked-by: Jeff Mahoney <jeffm@suse.com>

---

 init/main.c |    1 +

 1 file changed, 1 insertion(+)

--- a/init/main.c

+++ b/init/main.c

@@ -807,6 +807,7 @@ static noinline int init_post(void)

        system_state = SYSTEM_RUNNING;

        numa_default_policy();

+       printk("Hello world!\n");

        current->signal->flags |= SIGNAL_UNKILLABLE;

--------8<--------

Patch Inclusion Rules

---------------------

As mentioned in the summary, we expect that most patches to the SLE kernel

will come from subsequent official upstream kernel releases or from subsystem

maintainer repositories (which imply that the patch will ultimately be

a part of an official upstream Linux release).  The SLE kernel contains

hardware enablement driver enhancement/backports for a wide range of devices

offered by many vendors.  In many cases, the drivers are self-contained

but many others have shared dependencies on common infrastructure.

The shared dependencies on common infrastructure combined with the need

to be able to bisect the resulting kernel means that we must require

all partners to submit patch series consisting of individual patches that

match upstream commits.  In the case where a commit affects multiple drivers,

it is acceptable to only contain the portions that effect a particular

driver as long as it is annotated by appending "(partial)" to the Git-commit

line and documenting what is included or dropped.  An example using the

patch tools is included below.

Tools

-----

We understand that there are a bunch of rules to follow and that implementing

them all can be tedious.  We have a set of tools, published here[3], to make

working with the patches a lot easier.

There are two tools: fixpatch and exportpatch.  Fixpatch will add missing

headers and formatting to existing patches, assuming there's at least a

Git-commit tag present.  Exportpatch, given a list of commit IDs on the

commandline, will search for each commit in the configured repositories

and export the patches.

There are several command line options that are useful.

-w|--write -- will write out each commit into a separate file.  The filenames

              are based on the subject of the header and the filenames will

	      be output on stdout for use directly in a series file.

-d DIR|--dir=DIR -- will write out each commit into a designated directory.

                    The default is to write into the current directory.

-f|--force -- By default exportpatch will not export commits that are local

	      to the repository on disk.  It will also refuse to overwrite

	      existing patch files.  This option overrides these checks.

-F REF|--reference=REFERENCE -- Adds References automatically and can be

			        specified multiple times.

-x EXTRACT | --extract EXTRACT -- It it sometimes desirable to split out

				  chunks of patches that affect only a

				  particular section of the code.  This option

				  accepts pathnames to extract.  Anything

				  not specified will be skipped.  Paths ending

				  with / designate everything under that

				  hierarchy.  This also adds a (partial)

				  notation to the Git-commit tag and adds

				  a Patch-filtered: tag indicating which

				  paths were used to extract.

There are also two other features that are used automatically.  The first is

that 3-way merge diffs are handled automatically such that a new, exact

two-way diff is generated.  Note that both the -x option and the automatic

handling of merge commits can generate empty patches -- empty patches are

skipped entirely and no files are generated.

A quick example for generating the patches necessary for a backport of the

ixgbe driver against the 3.0 kernel.  Please note that it (obviously) skips

any infrastructure changes required for the patches to build.  The Acked-by

tags will automatically be added unless you were involved in the original

upstream commit process.

exportpatch -w -d ixgbe -x drivers/net/ixgbe/ \

            -x drivers/net/ethernet/intel/ixgbe/ \

	    -F "FATE#12345" -F "bnc#12354" \

	    $(git log v3.0.. --pretty=oneline -- drivers/net/ixgbe \

	      drivers/net/ethernet/intel/ixgbe |cut -b 1-40) > ixgbe/series

The first patch in that series looks like this:

--------8<--------

From 6403eab143205a45a5493166ff8bf7e3646f4a77 Mon Sep 17 00:00:00 2001

From: Joe Perches <joe@perches.com>

Date: Fri, 3 Jun 2011 11:51:20 +0000

Subject: drivers/net: Remove unnecessary semicolons

Git-commit: 6403eab143205a45a5493166ff8bf7e3646f4a77 (partial)

Patch-mainline: v3.1-rc1

References: FATE#12345 bnc#12354

Patch-filtered: drivers/net/ixgbe/ drivers/net/ethernet/intel/ixgbe/

Semicolons are not necessary after switch/while/for/if braces

so remove them.

Signed-off-by: Joe Perches <joe@perches.com>

Signed-off-by: David S. Miller <davem@davemloft.net>

Acked-by: Jeff Mahoney <jeffm@suse.com>

---

 drivers/net/ixgbe/ixgbe_82599.c  |    4 ++--

 drivers/net/ixgbe/ixgbe_common.c |    4 ++--

 2 files changed, 4 insertions(+), 4 deletions(-)

--- a/drivers/net/ixgbe/ixgbe_82599.c

+++ b/drivers/net/ixgbe/ixgbe_82599.c

@@ -1157,7 +1157,7 @@ s32 ixgbe_init_fdir_signature_82599(struct ixgbe_hw *hw, u32 pballoc)

 	default:

 		/* bad value */

 		return IXGBE_ERR_CONFIG;

-	};

+	}

 	/* Move the flexible bytes to use the ethertype - shift 6 words */

 	fdirctrl |= (0x6 << IXGBE_FDIRCTRL_FLEX_SHIFT);

@@ -1245,7 +1245,7 @@ s32 ixgbe_init_fdir_perfect_82599(struct ixgbe_hw *hw, u32 pballoc)

 	default:

 		/* bad value */

 		return IXGBE_ERR_CONFIG;

-	};

+	}

 	/* Turn perfect match filtering on */

 	fdirctrl |= IXGBE_FDIRCTRL_PERFECT_MATCH;

--- a/drivers/net/ixgbe/ixgbe_common.c

+++ b/drivers/net/ixgbe/ixgbe_common.c

@@ -1292,7 +1292,7 @@ static s32 ixgbe_ready_eeprom(struct ixgbe_hw *hw)

 		udelay(5);

 		ixgbe_standby_eeprom(hw);

-	};

+	}

 	/*

 	 * On some parts, SPI write time could vary from 0-20mSec on 3.3V

@@ -1374,7 +1374,7 @@ static void ixgbe_shift_out_eeprom_bits(struct ixgbe_hw *hw, u16 data,

 		 * EEPROM

 		 */

 		mask = mask >> 1;

-	};

+	}

 	/* We leave the "DI" bit set to "0" when we leave this routine. */

 	eec &= ~IXGBE_EEC_DI;

-------->8--------

Links:

[1]: http://kernel.suse.com/cgit/kernel-source/log/?h=SLE12

[2]: http://kernel.suse.com/cgit/kernel/log/?h=SLE12

[3]: http://download.opensuse.org/repositories/Kernel:/tools/

[4]: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git