File README.PATCH-POLICY.SUSE of Package kernel-docs-rt (Revision 71cb8e846dd5fff9992b1b3181ab3d0e)
Currently displaying revision 71cb8e846dd5fff9992b1b3181ab3d0e , Show latest
315
1
SUSE Linux Enterprise Patch Policy
2
----------------------------------
3
4
Summary
5
-------
6
7
The SUSE Linux Enterprise (SLE) patch policy mirrors the mainline Linux
8
community's policy for accepting changes. Each commit must contain a
9
small and "obvious" change that can be reviewed individually and, once
10
applied, be able to be used as a bisection point. The kernel should be
11
able to build (and boot) between each applied patch. Since the SLE
12
kernel is based on an official upstream kernel release and is followed by
13
a hardening process, we expect that nearly all of the patches applied to the
14
base release will be from subsequent official upstream releases indended to
15
address specific issues or to allow for hardware/feature enablement.
16
17
18
Background
19
----------
20
21
Before covering the policy itself, we'll discuss a bit of background on
22
how the source code tree is organized. If you've used the SLE kernel source
23
(kernel-source.git[1]) tree before, you've probably noticed that, unlike
24
the mainline Linux kernel, we don't use a source-level git repository as
25
our "base." Instead, we use an official kernel.org Linux tar archive as
26
the base and add a series of patches on top of it. This carries with it
27
several benefits. The biggest is that we add metadata "tags" to our
28
patches that allow us to easily associate patches with particular feature
29
requests, bug reports, and/or the pedigree of the patch. Due to the nature
30
of some of our feature requests, we also must occasionally carry patches
31
that, for one reason or another, haven't been accepted into the mainline
32
kernel repository yet. With a full (published[2]) git repository, it would
33
be difficult to associate the initial commit for a particular feature with
34
any subsequent changes to it. Another benefit is more superficial: with the
35
use of separate patches, we (and our users) are able to tell, at a glance,
36
which patches are in any given kernel release simply by looking at
37
the source package. Patches are grouped into subsystems (including
38
architecture, "core" vm/scheduler, VFS, individual file systems, driver
39
core, networking core, block layer, and leaf drivers) so finding patches
40
that affect a particular part of the kernel can be easily found. Patches
41
are placed in directories such as patches.fixes, patches.suse, etc. When
42
submitting patches for inclusion, it's not necessary to choose a directory.
43
We'll put them in the appropriate place.
44
45
Historically, this approach has worked well but has limited options for
46
typical debugging techniques such as bisection. The application of the
47
patch series results in our fully operational SLE kernel but stopping
48
the patch series midway can result in an unbuildable source tree.
49
Beginning with the SLE11 SP2 development cycle, we've published a fully
50
expanded git repository (kernel.git[2]) that exactly represents the code
51
as if it were originally used as a standard source code tree repository.
52
This allows us to work with the individual patches *and* have the ability
53
to bisect the tree as the changes are applied. It also makes it easier for
54
partners unfamiliar with how our source tree works to make the transition.
55
56
57
Format
58
------
59
The SLE patch format follows very closely what you would see on any
60
mailing list associated with Linux kernel development. A SLE patch is
61
formatted like an RFC822 mbox-style mail message, with a few extensions.
62
If the patch is coming from the mainline Linux repository or a subsystem
63
maintainer repository, SUSE has tools published here[3] that can make
64
adding these tags nearly painless.
65
66
Each patch should contain the "From" and "Subject" headers found in any
67
email message. The From should contain the name and email address of the
68
patch author. The Subject should contain a short description of the
69
patch, prefixed with the subsystem affected.
70
71
e.g.
72
From: Jeff Mahoney <jeffm@suse.com>
73
Subject: init: print hello world at boot time
74
75
Beyond that, we require several more headers, the full description of
76
the patch, the certification tags used in the mainline kernel, and the patch
77
contents.
78
79
The headers we require are as follows:
80
81
Git-commit: [a-f0-9]{40}
82
- Contains the SHA-1 git commit ID of the patch in either the mainline
83
kernel repository[4] or an official maintainer repository.
84
85
Git-repo: URL-to-git-repo (starting with git://)
86
- The URL to the git repository containing the commit. This tag can be
87
omitted if the commit is from the mainline kernel repository.
88
89
Patch-mainline: vMajor.Minor.Patch{-optional-rc}
90
- The official kernel release that contains this patch. In the case of a
91
patch accepted into a maintainer branch, "Queued in subsystem
92
maintainer repo" can be used. If the patch has been submitted to a
93
subsystem mailing list for review and is nearly certain to be accepted,
94
"Submitted <date> <list@site.org>" can be used. Otherwise, if the
95
patch will never be in the upstream kernel, e.g. in the case of
96
vendor-specific
97
version numbers, etc, then "No" followed by the reason why it will
98
not be accepted (or submitted). Please note that the reason must be
99
compelling for it to be allowed into our kernel repository.
100
101
References: list of references
102
- There must be a reason for each patch to be included into the kernel
103
repository. It can be a fix in response to a bug report or a patch
104
submitted as part of the feature development cycle for a release. We
105
use a shorthand to indicate why a particular patch will be included
106
and it's possible to use more than one.
107
108
For Feature requests, the feature will have to have gone through our
109
feature tracking tool, FATE. Each feature request will have an ID
110
associated with it and it can be added to the References tag using
111
FATE#number, e.g. FATE#12345.
112
113
For fixes for bug reports (or patches for feature requests submitted
114
via Bugzilla, the shorthand is bnc#number. bnc is shorthand for
115
bugzilla.novell.com. There are others such as bko, for
116
bugzilla.kernel.org.
117
118
Next is the full description of the patch, which should explain why the
119
patch is needed and an overview of what it does.
120
121
The last "header" portion of the patch contains the certification tags, which
122
consist of "Signed-off-by" and "Acked-by." We, and the upstream Linux
123
community depend on patch submitters to "own" their submission and certify
124
they have the right to submit code to the kernel repository. For patches
125
coming from the mainline Linux kernel repository, the certification tags
126
are already in place and we only need the submitter's tag added (if not
127
already part of the original patch). Likewise, the SUSE engineer who
128
includes the submission in our kernel tree, will add their own "Acked-by"
129
tag.
130
131
There may be an optional diffstat -p1 output added before the patch content.
132
133
The patch content itself should be in "-ab" format where the patch header
134
itself only contains the filename without any timestamps.
135
136
Here's an example of a complete patch:
137
138
-------->8--------
139
From: Upstream Committer <coder@somesite.com>
140
Subject: init: print hello world on boot
141
Patch-mainline: v3.8-rc1
142
Git-commit: deadbeefc0ffeeb1a4b1a4b1a4b1a4b1a4b1a4b1a4
143
References: FATE#12134 bnc#23123
144
145
The kernel started off like every other project. Let's add the hello
146
world message in honor of its roots.
147
148
Signed-off-by: Upstream Committer <coder@somesite.com>
149
Tested-by: Bill User <bill.user@example.com>
150
Acked-by: Jeff Mahoney <jeffm@suse.com>
151
---
152
init/main.c | 1 +
153
1 file changed, 1 insertion(+)
154
155
--- a/init/main.c
156
+++ b/init/main.c
157
@@ -807,6 +807,7 @@ static noinline int init_post(void)
158
system_state = SYSTEM_RUNNING;
159
numa_default_policy();
160
161
+ printk("Hello world!\n");
162
163
current->signal->flags |= SIGNAL_UNKILLABLE;
164
165
--------8<--------
166
167
168
Patch Inclusion Rules
169
---------------------
170
171
As mentioned in the summary, we expect that most patches to the SLE kernel
172
will come from subsequent official upstream kernel releases or from subsystem
173
maintainer repositories (which imply that the patch will ultimately be
174
a part of an official upstream Linux release). The SLE kernel contains
175
hardware enablement driver enhancement/backports for a wide range of devices
176
offered by many vendors. In many cases, the drivers are self-contained
177
but many others have shared dependencies on common infrastructure.
178
179
The shared dependencies on common infrastructure combined with the need
180
to be able to bisect the resulting kernel means that we must require
181
all partners to submit patch series consisting of individual patches that
182
match upstream commits. In the case where a commit affects multiple drivers,
183
it is acceptable to only contain the portions that effect a particular
184
driver as long as it is annotated by appending "(partial)" to the Git-commit
185
line and documenting what is included or dropped. An example using the
186
patch tools is included below.
187
188
189
Tools
190
-----
191
We understand that there are a bunch of rules to follow and that implementing
192
them all can be tedious. We have a set of tools, published here[3], to make
193
working with the patches a lot easier.
194
195
There are two tools: fixpatch and exportpatch. Fixpatch will add missing
196
headers and formatting to existing patches, assuming there's at least a
197
Git-commit tag present. Exportpatch, given a list of commit IDs on the
198
commandline, will search for each commit in the configured repositories
199
and export the patches.
200
201
There are several command line options that are useful.
202
203
-w|--write -- will write out each commit into a separate file. The filenames
204
are based on the subject of the header and the filenames will
205
be output on stdout for use directly in a series file.
206
207
-d DIR|--dir=DIR -- will write out each commit into a designated directory.
208
The default is to write into the current directory.
209
-f|--force -- By default exportpatch will not export commits that are local
210
to the repository on disk. It will also refuse to overwrite
211
existing patch files. This option overrides these checks.
212
-F REF|--reference=REFERENCE -- Adds References automatically and can be
213
specified multiple times.
214
-x EXTRACT | --extract EXTRACT -- It it sometimes desirable to split out
215
chunks of patches that affect only a
216
particular section of the code. This option
217
accepts pathnames to extract. Anything
218
not specified will be skipped. Paths ending
219
with / designate everything under that
220
hierarchy. This also adds a (partial)
221
notation to the Git-commit tag and adds
222
a Patch-filtered: tag indicating which
223
paths were used to extract.
224
225
There are also two other features that are used automatically. The first is
226
that 3-way merge diffs are handled automatically such that a new, exact
227
two-way diff is generated. Note that both the -x option and the automatic
228
handling of merge commits can generate empty patches -- empty patches are
229
skipped entirely and no files are generated.
230
231
A quick example for generating the patches necessary for a backport of the
232
ixgbe driver against the 3.0 kernel. Please note that it (obviously) skips
233
any infrastructure changes required for the patches to build. The Acked-by
234
tags will automatically be added unless you were involved in the original
235
upstream commit process.
236
237
exportpatch -w -d ixgbe -x drivers/net/ixgbe/ \
238
-x drivers/net/ethernet/intel/ixgbe/ \
239
-F "FATE#12345" -F "bnc#12354" \
240
$(git log v3.0.. --pretty=oneline -- drivers/net/ixgbe \
241
drivers/net/ethernet/intel/ixgbe |cut -b 1-40) > ixgbe/series
242
243
The first patch in that series looks like this:
244
--------8<--------
245
From 6403eab143205a45a5493166ff8bf7e3646f4a77 Mon Sep 17 00:00:00 2001
246
From: Joe Perches <joe@perches.com>
247
Date: Fri, 3 Jun 2011 11:51:20 +0000
248
Subject: drivers/net: Remove unnecessary semicolons
249
Git-commit: 6403eab143205a45a5493166ff8bf7e3646f4a77 (partial)
250
Patch-mainline: v3.1-rc1
251
References: FATE#12345 bnc#12354
252
Patch-filtered: drivers/net/ixgbe/ drivers/net/ethernet/intel/ixgbe/
253
254
Semicolons are not necessary after switch/while/for/if braces
255
so remove them.
256
257
Signed-off-by: Joe Perches <joe@perches.com>
258
Signed-off-by: David S. Miller <davem@davemloft.net>
259
Acked-by: Jeff Mahoney <jeffm@suse.com>
260
---
261
262
drivers/net/ixgbe/ixgbe_82599.c | 4 ++--
263
drivers/net/ixgbe/ixgbe_common.c | 4 ++--
264
2 files changed, 4 insertions(+), 4 deletions(-)
265
266
--- a/drivers/net/ixgbe/ixgbe_82599.c
267
+++ b/drivers/net/ixgbe/ixgbe_82599.c
268
@@ -1157,7 +1157,7 @@ s32 ixgbe_init_fdir_signature_82599(struct ixgbe_hw *hw, u32 pballoc)
269
default:
270
/* bad value */
271
return IXGBE_ERR_CONFIG;
272
- };
273
+ }
274
275
/* Move the flexible bytes to use the ethertype - shift 6 words */
276
fdirctrl |= (0x6 << IXGBE_FDIRCTRL_FLEX_SHIFT);
277
@@ -1245,7 +1245,7 @@ s32 ixgbe_init_fdir_perfect_82599(struct ixgbe_hw *hw, u32 pballoc)
278
default:
279
/* bad value */
280
return IXGBE_ERR_CONFIG;
281
- };
282
+ }
283
284
/* Turn perfect match filtering on */
285
fdirctrl |= IXGBE_FDIRCTRL_PERFECT_MATCH;
286
287
--- a/drivers/net/ixgbe/ixgbe_common.c
288
+++ b/drivers/net/ixgbe/ixgbe_common.c
289
@@ -1292,7 +1292,7 @@ static s32 ixgbe_ready_eeprom(struct ixgbe_hw *hw)
290
291
udelay(5);
292
ixgbe_standby_eeprom(hw);
293
- };
294
+ }
295
296
/*
297
* On some parts, SPI write time could vary from 0-20mSec on 3.3V
298
@@ -1374,7 +1374,7 @@ static void ixgbe_shift_out_eeprom_bits(struct ixgbe_hw *hw, u16 data,
299
* EEPROM
300
*/
301
mask = mask >> 1;
302
- };
303
+ }
304
305
/* We leave the "DI" bit set to "0" when we leave this routine. */
306
eec &= ~IXGBE_EEC_DI;
307
308
-------->8--------
309
310
Links:
311
[1]: http://kernel.suse.com/cgit/kernel-source/log/?h=SLE12
312
[2]: http://kernel.suse.com/cgit/kernel/log/?h=SLE12
313
[3]: http://download.opensuse.org/repositories/Kernel:/tools/
314
[4]: http://git.kernel.org/cgit/linux/kernel/git/torvalds/linux.git
315