blob: 501af5d5febabbb0bc3eb6f121417f864ba82393
1 | .. _stable_kernel_rules: |
2 | |
3 | Everything you ever wanted to know about Linux -stable releases |
4 | =============================================================== |
5 | |
6 | Rules on what kind of patches are accepted, and which ones are not, into the |
7 | "-stable" tree: |
8 | |
9 | - It must be obviously correct and tested. |
10 | - It cannot be bigger than 100 lines, with context. |
11 | - It must fix only one thing. |
12 | - It must fix a real bug that bothers people (not a, "This could be a |
13 | problem..." type thing). |
14 | - It must fix a problem that causes a build error (but not for things |
15 | marked CONFIG_BROKEN), an oops, a hang, data corruption, a real |
16 | security issue, or some "oh, that's not good" issue. In short, something |
17 | critical. |
18 | - Serious issues as reported by a user of a distribution kernel may also |
19 | be considered if they fix a notable performance or interactivity issue. |
20 | As these fixes are not as obvious and have a higher risk of a subtle |
21 | regression they should only be submitted by a distribution kernel |
22 | maintainer and include an addendum linking to a bugzilla entry if it |
23 | exists and additional information on the user-visible impact. |
24 | - New device IDs and quirks are also accepted. |
25 | - No "theoretical race condition" issues, unless an explanation of how the |
26 | race can be exploited is also provided. |
27 | - It cannot contain any "trivial" fixes in it (spelling changes, |
28 | whitespace cleanups, etc). |
29 | - It must follow the |
30 | :ref:`Documentation/SubmittingPatches <submittingpatches>` |
31 | rules. |
32 | - It or an equivalent fix must already exist in Linus' tree (upstream). |
33 | |
34 | |
35 | Procedure for submitting patches to the -stable tree |
36 | ---------------------------------------------------- |
37 | |
38 | - If the patch covers files in net/ or drivers/net please follow netdev stable |
39 | submission guidelines as described in |
40 | Documentation/networking/netdev-FAQ.txt |
41 | - Security patches should not be handled (solely) by the -stable review |
42 | process but should follow the procedures in |
43 | :ref:`Documentation/SecurityBugs <securitybugs>`. |
44 | |
45 | For all other submissions, choose one of the following procedures |
46 | ----------------------------------------------------------------- |
47 | |
48 | .. _option_1: |
49 | |
50 | Option 1 |
51 | ******** |
52 | |
53 | To have the patch automatically included in the stable tree, add the tag |
54 | |
55 | .. code-block:: none |
56 | |
57 | Cc: stable@vger.kernel.org |
58 | |
59 | in the sign-off area. Once the patch is merged it will be applied to |
60 | the stable tree without anything else needing to be done by the author |
61 | or subsystem maintainer. |
62 | |
63 | .. _option_2: |
64 | |
65 | Option 2 |
66 | ******** |
67 | |
68 | After the patch has been merged to Linus' tree, send an email to |
69 | stable@vger.kernel.org containing the subject of the patch, the commit ID, |
70 | why you think it should be applied, and what kernel version you wish it to |
71 | be applied to. |
72 | |
73 | .. _option_3: |
74 | |
75 | Option 3 |
76 | ******** |
77 | |
78 | Send the patch, after verifying that it follows the above rules, to |
79 | stable@vger.kernel.org. You must note the upstream commit ID in the |
80 | changelog of your submission, as well as the kernel version you wish |
81 | it to be applied to. |
82 | |
83 | :ref:`option_1` is **strongly** preferred, is the easiest and most common. |
84 | :ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed |
85 | worthy at the time it is applied to a public git tree (for instance, because |
86 | it deserves more regression testing first). :ref:`option_3` is especially |
87 | useful if the patch needs some special handling to apply to an older kernel |
88 | (e.g., if API's have changed in the meantime). |
89 | |
90 | Note that for :ref:`option_3`, if the patch deviates from the original |
91 | upstream patch (for example because it had to be backported) this must be very |
92 | clearly documented and justified in the patch description. |
93 | |
94 | The upstream commit ID must be specified with a separate line above the commit |
95 | text, like this: |
96 | |
97 | .. code-block:: none |
98 | |
99 | commit <sha1> upstream. |
100 | |
101 | Additionally, some patches submitted via Option 1 may have additional patch |
102 | prerequisites which can be cherry-picked. This can be specified in the following |
103 | format in the sign-off area: |
104 | |
105 | .. code-block:: none |
106 | |
107 | Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle |
108 | Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle |
109 | Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic |
110 | Cc: <stable@vger.kernel.org> # 3.3.x |
111 | Signed-off-by: Ingo Molnar <mingo@elte.hu> |
112 | |
113 | The tag sequence has the meaning of: |
114 | |
115 | .. code-block:: none |
116 | |
117 | git cherry-pick a1f84a3 |
118 | git cherry-pick 1b9508f |
119 | git cherry-pick fd21073 |
120 | git cherry-pick <this commit> |
121 | |
122 | Also, some patches may have kernel version prerequisites. This can be |
123 | specified in the following format in the sign-off area: |
124 | |
125 | .. code-block:: none |
126 | |
127 | Cc: <stable@vger.kernel.org> # 3.3.x |
128 | |
129 | The tag has the meaning of: |
130 | |
131 | .. code-block:: none |
132 | |
133 | git cherry-pick <this commit> |
134 | |
135 | For each "-stable" tree starting with the specified version. |
136 | |
137 | Following the submission: |
138 | |
139 | - The sender will receive an ACK when the patch has been accepted into the |
140 | queue, or a NAK if the patch is rejected. This response might take a few |
141 | days, according to the developer's schedules. |
142 | - If accepted, the patch will be added to the -stable queue, for review by |
143 | other developers and by the relevant subsystem maintainer. |
144 | |
145 | |
146 | Review cycle |
147 | ------------ |
148 | |
149 | - When the -stable maintainers decide for a review cycle, the patches will be |
150 | sent to the review committee, and the maintainer of the affected area of |
151 | the patch (unless the submitter is the maintainer of the area) and CC: to |
152 | the linux-kernel mailing list. |
153 | - The review committee has 48 hours in which to ACK or NAK the patch. |
154 | - If the patch is rejected by a member of the committee, or linux-kernel |
155 | members object to the patch, bringing up issues that the maintainers and |
156 | members did not realize, the patch will be dropped from the queue. |
157 | - At the end of the review cycle, the ACKed patches will be added to the |
158 | latest -stable release, and a new -stable release will happen. |
159 | - Security patches will be accepted into the -stable tree directly from the |
160 | security kernel team, and not go through the normal review cycle. |
161 | Contact the kernel security team for more details on this procedure. |
162 | |
163 | Trees |
164 | ----- |
165 | |
166 | - The queues of patches, for both completed versions and in progress |
167 | versions can be found at: |
168 | |
169 | http://git.kernel.org/?p=linux/kernel/git/stable/stable-queue.git |
170 | |
171 | - The finalized and tagged releases of all stable kernels can be found |
172 | in separate branches per version at: |
173 | |
174 | http://git.kernel.org/?p=linux/kernel/git/stable/linux-stable.git |
175 | |
176 | |
177 | Review committee |
178 | ---------------- |
179 | |
180 | - This is made up of a number of kernel developers who have volunteered for |
181 | this task, and a few that haven't. |
182 |