Sign Up
Log In
Log In
or
Sign Up
Places
All Projects
Status Monitor
Collapse sidebar
SUSE:SLE-12-SP5:GA
kernel-docs.2727
README.PATCH-POLICY.SUSE
Overview
Repositories
Revisions
Requests
Users
Attributes
Meta
File README.PATCH-POLICY.SUSE of Package kernel-docs.2727
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
Locations
Projects
Search
Status Monitor
Help
OpenBuildService.org
Documentation
API Documentation
Code of Conduct
Contact
Support
@OBShq
Terms
openSUSE Build Service is sponsored by
The Open Build Service is an
openSUSE project
.
Sign Up
Log In
Places
Places
All Projects
Status Monitor
