kernel-source-longterm/README.PATCH-POLICY.SUSE

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 intended 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 tree
at <https://github.com/SUSE/kernel-source> 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
must also occasionally carry patches that, for one reason or another, haven't
been accepted into the mainline kernel repository yet. With a full 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.

This approach works 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. To help this and similar scenarios, we publish also
a fully expanded Git repository at <https://github.com/SUSE/kernel> which
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 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.

For instance:

    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 required headers 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 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

  A specific reason must exist 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, a Jira instance at <https://jira.suse.com/>. Each feature
  request will have an ID associated with it and it can be added to the
  References tag using jsc#id, e.g. jsc#PED-12345.

  For fixes to bug reports or patches for feature requests submitted via
  Bugzilla at <https://bugzilla.suse.com/>, the shorthand is bsc#number. Other
  shorthands referring to different Bugzilla instances are possible too, such as
  bko, for <https://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 only the submitter's tag needs to be added, unless one is also 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.

The remaining part of the patch is the actual diff with changes. The patch
content should be in the "-ab" format where the patch header itself only
contains the filename without any timestamps. An optional `diffstat -p1` output
may also be included.

Here's an example of a complete patch:

```
From: Upstream Committer <coder@somesite.com>
Subject: init: print hello world on boot
Patch-mainline: v3.8-rc1
Git-commit: deadbeefc0ffeeb1a4b1a4b1a4b1a4b1a4b1a4b1a4
References: jsc#PED-12134 bsc#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;
 
```


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 where the patch is on its way to become 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 include the portions that affect 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. SUSE has a set of tools to make working with the
patches a lot easier. They are called patchtools and published at
<https://download.opensuse.org/repositories/Kernel:/tools/>.

Two important tools are included: fixpatch and exportpatch. Fixpatch adds
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 command
line, searches for each commit in the configured repositories and exports the
patches.

Exportpatch has a number of options, the following list shows the most useful
ones:

* `-w` | `--write`

  Write out each commit into a separate file. The filenames are based on the
  subject of the header and they get output on stdout for use directly in a
  series file.

* `-d DIR` | `--dir=DIR`

  Write out each commit into a designated directory. The default is to write
  into the current directory.

* `-F REF` | `--reference=REFERENCE`

  Add a References tag to the patch output using the specified reference, can be
  repeated 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 the "(partial)" notation to
  the Git-commit tag and adds a Patch-filtered tag indicating which paths were
  used to extract.

Refer to the exportpatch(1) manual page for more details and a complete list of
all options.

One useful feature of exportpatch is that 3-way merge diffs are handled
automatically such that a new, exact 2-way diff is generated. Note that both the
`-x` option and the automatic handling of merge commits can generate empty
patches. Such patches are skipped entirely and no files are generated.

As a quick example, the following invocation would generate patches necessary
for a backport of the ixgbe driver from v3.2 against the v3.0 kernel:

    $ exportpatch -w -d ixgbe \
        -x drivers/net/ixgbe/ -x drivers/net/ethernet/intel/ixgbe/ \
        -F "jsc#PED-12345" -F "bsc#12354" \
        $(git log v3.0..v3.2 --pretty=oneline -- \
            drivers/net/ixgbe drivers/net/ethernet/intel/ixgbe | \
          cut -b 1-40) \
        > ixgbe/series

The tool automatically adds an Acked-by tag to the created patches unless you
were involved in the original upstream commit process. Be aware that the
produced result (obviously) doesn't include any infrastructure changes that
might be needed for the patches to build.

The first patch in the series looks like this:

```
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: jsc#PED-12345 bsc#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;

```