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