blob: 3973556250e17050a32309edd7b225554c81e394 [file] [log] [blame]
Mauro Carvalho Chehab609d99a2016-09-19 08:07:56 -03001.. _stable_kernel_rules:
2
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -03003Everything you ever wanted to know about Linux -stable releases
4===============================================================
Greg KHfc185d92005-07-29 12:14:34 -07005
Jesper Juhle48e9902006-01-09 20:53:59 -08006Rules on what kind of patches are accepted, and which ones are not, into the
7"-stable" tree:
Greg KHfc185d92005-07-29 12:14:34 -07008
9 - It must be obviously correct and tested.
Matt LaPlante84eb8d02006-10-03 22:53:09 +020010 - It cannot be bigger than 100 lines, with context.
Greg KHfc185d92005-07-29 12:14:34 -070011 - It must fix only one thing.
12 - It must fix a real bug that bothers people (not a, "This could be a
Jesper Juhle48e9902006-01-09 20:53:59 -080013 problem..." type thing).
Greg KHfc185d92005-07-29 12:14:34 -070014 - 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
Jesper Juhle48e9902006-01-09 20:53:59 -080016 security issue, or some "oh, that's not good" issue. In short, something
17 critical.
Mel Gorman8191e0d2012-06-21 11:36:50 +010018 - 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.
Josh Boyer79cd80a12008-10-24 10:10:42 -040024 - New device IDs and quirks are also accepted.
Jesper Juhle48e9902006-01-09 20:53:59 -080025 - No "theoretical race condition" issues, unless an explanation of how the
26 race can be exploited is also provided.
Matt LaPlante84eb8d02006-10-03 22:53:09 +020027 - It cannot contain any "trivial" fixes in it (spelling changes,
Jesper Juhle48e9902006-01-09 20:53:59 -080028 whitespace cleanups, etc).
Mauro Carvalho Chehabdca22a62016-09-21 08:51:05 -030029 - It must follow the
Mauro Carvalho Chehab8c27ceff32016-10-18 10:12:27 -020030 :ref:`Documentation/process/submitting-patches.rst <submittingpatches>`
Mauro Carvalho Chehabdca22a62016-09-21 08:51:05 -030031 rules.
Stefan Richter959fb1c2010-04-01 22:01:52 +020032 - It or an equivalent fix must already exist in Linus' tree (upstream).
Greg KHfc185d92005-07-29 12:14:34 -070033
34
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030035Procedure for submitting patches to the -stable tree
36----------------------------------------------------
Greg KHfc185d92005-07-29 12:14:34 -070037
Dave Chilukb76fc282014-06-24 10:11:26 -050038 - If the patch covers files in net/ or drivers/net please follow netdev stable
39 submission guidelines as described in
Tobin C. Harding287f4fa2018-07-26 15:02:26 +100040 :ref:`Documentation/networking/netdev-FAQ.rst <netdev-FAQ>`
Greg Kroah-Hartmana41e8f22019-01-22 19:46:32 +010041 after first checking the stable networking queue at
Jakub Kicinski460cd172020-11-09 19:51:20 -080042 https://patchwork.kernel.org/bundle/netdev/stable/?state=*
Greg Kroah-Hartmana41e8f22019-01-22 19:46:32 +010043 to ensure the requested patch is not already queued up.
Brian Norris5de61e72014-12-18 14:55:53 -080044 - Security patches should not be handled (solely) by the -stable review
Mauro Carvalho Chehabdca22a62016-09-21 08:51:05 -030045 process but should follow the procedures in
Mauro Carvalho Chehab8c27ceff32016-10-18 10:12:27 -020046 :ref:`Documentation/admin-guide/security-bugs.rst <securitybugs>`.
Brian Norris5de61e72014-12-18 14:55:53 -080047
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030048For all other submissions, choose one of the following procedures
49-----------------------------------------------------------------
Brian Norris5de61e72014-12-18 14:55:53 -080050
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030051.. _option_1:
Brian Norris5de61e72014-12-18 14:55:53 -080052
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030053Option 1
54********
55
56To have the patch automatically included in the stable tree, add the tag
57
58.. code-block:: none
59
Josh Boyer5fa22422011-10-17 21:16:39 -040060 Cc: [email protected]
Brian Norris5de61e72014-12-18 14:55:53 -080061
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030062in the sign-off area. Once the patch is merged it will be applied to
63the stable tree without anything else needing to be done by the author
64or subsystem maintainer.
Brian Norris5de61e72014-12-18 14:55:53 -080065
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030066.. _option_2:
Brian Norris5de61e72014-12-18 14:55:53 -080067
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030068Option 2
69********
Brian Norris5de61e72014-12-18 14:55:53 -080070
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030071After the patch has been merged to Linus' tree, send an email to
72stable@vger.kernel.org containing the subject of the patch, the commit ID,
73why you think it should be applied, and what kernel version you wish it to
74be applied to.
Brian Norris5de61e72014-12-18 14:55:53 -080075
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030076.. _option_3:
Christoffer Dallbde1b292015-05-13 22:01:07 +020077
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -030078Option 3
79********
80
81Send the patch, after verifying that it follows the above rules, to
82stable@vger.kernel.org. You must note the upstream commit ID in the
83changelog of your submission, as well as the kernel version you wish
84it to be applied to.
85
86:ref:`option_1` is **strongly** preferred, is the easiest and most common.
87:ref:`option_2` and :ref:`option_3` are more useful if the patch isn't deemed
88worthy at the time it is applied to a public git tree (for instance, because
89it deserves more regression testing first). :ref:`option_3` is especially
90useful if the patch needs some special handling to apply to an older kernel
91(e.g., if API's have changed in the meantime).
92
93Note that for :ref:`option_3`, if the patch deviates from the original
94upstream patch (for example because it had to be backported) this must be very
95clearly documented and justified in the patch description.
Christoffer Dallbde1b292015-05-13 22:01:07 +020096
97The upstream commit ID must be specified with a separate line above the commit
98text, like this:
99
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300100.. code-block:: none
101
Christoffer Dallbde1b292015-05-13 22:01:07 +0200102 commit <sha1> upstream.
Brian Norris5de61e72014-12-18 14:55:53 -0800103
Federico Vagab04c11c2019-01-20 12:16:29 +0100104Additionally, some patches submitted via :ref:`option_1` may have additional
105patch prerequisites which can be cherry-picked. This can be specified in the
106following format in the sign-off area:
Sebastian Andrzej Siewior8e9b9362009-12-06 12:24:31 +0100107
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300108.. code-block:: none
109
Paul Gortmaker2584f522012-06-05 11:15:50 -0400110 Cc: <stable@vger.kernel.org> # 3.3.x: a1f84a3: sched: Check for idle
111 Cc: <stable@vger.kernel.org> # 3.3.x: 1b9508f: sched: Rate-limit newidle
112 Cc: <stable@vger.kernel.org> # 3.3.x: fd21073: sched: Fix affinity logic
113 Cc: <stable@vger.kernel.org> # 3.3.x
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300114 Signed-off-by: Ingo Molnar <mingo@elte.hu>
Sebastian Andrzej Siewior8e9b9362009-12-06 12:24:31 +0100115
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300116The tag sequence has the meaning of:
117
118.. code-block:: none
119
Sebastian Andrzej Siewior8e9b9362009-12-06 12:24:31 +0100120 git cherry-pick a1f84a3
121 git cherry-pick 1b9508f
122 git cherry-pick fd21073
123 git cherry-pick <this commit>
124
David Daneyfdc81b72015-03-26 10:09:08 -0700125Also, some patches may have kernel version prerequisites. This can be
126specified in the following format in the sign-off area:
127
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300128.. code-block:: none
129
Johan Hovoldcf903e92017-04-03 15:53:34 +0200130 Cc: <stable@vger.kernel.org> # 3.3.x
David Daneyfdc81b72015-03-26 10:09:08 -0700131
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300132The tag has the meaning of:
133
134.. code-block:: none
135
David Daneyfdc81b72015-03-26 10:09:08 -0700136 git cherry-pick <this commit>
137
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300138For each "-stable" tree starting with the specified version.
David Daneyfdc81b72015-03-26 10:09:08 -0700139
Brian Norris5de61e72014-12-18 14:55:53 -0800140Following the submission:
141
Jesper Juhle48e9902006-01-09 20:53:59 -0800142 - The sender will receive an ACK when the patch has been accepted into the
143 queue, or a NAK if the patch is rejected. This response might take a few
144 days, according to the developer's schedules.
145 - If accepted, the patch will be added to the -stable queue, for review by
Stefan Richter46cdf8712008-02-08 23:26:02 +0100146 other developers and by the relevant subsystem maintainer.
Greg KHfc185d92005-07-29 12:14:34 -0700147
148
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300149Review cycle
150------------
Greg KHfc185d92005-07-29 12:14:34 -0700151
Jesper Juhle48e9902006-01-09 20:53:59 -0800152 - When the -stable maintainers decide for a review cycle, the patches will be
153 sent to the review committee, and the maintainer of the affected area of
154 the patch (unless the submitter is the maintainer of the area) and CC: to
155 the linux-kernel mailing list.
156 - The review committee has 48 hours in which to ACK or NAK the patch.
Greg KHfc185d92005-07-29 12:14:34 -0700157 - If the patch is rejected by a member of the committee, or linux-kernel
Jesper Juhle48e9902006-01-09 20:53:59 -0800158 members object to the patch, bringing up issues that the maintainers and
159 members did not realize, the patch will be dropped from the queue.
160 - At the end of the review cycle, the ACKed patches will be added to the
161 latest -stable release, and a new -stable release will happen.
162 - Security patches will be accepted into the -stable tree directly from the
163 security kernel team, and not go through the normal review cycle.
Greg KHfc185d92005-07-29 12:14:34 -0700164 Contact the kernel security team for more details on this procedure.
165
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300166Trees
167-----
Paul Gortmaker2584f522012-06-05 11:15:50 -0400168
169 - The queues of patches, for both completed versions and in progress
170 versions can be found at:
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300171
Andrii Bordunovc1aa3872017-08-13 23:43:43 +0300172 https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable-queue.git
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300173
Paul Gortmaker2584f522012-06-05 11:15:50 -0400174 - The finalized and tagged releases of all stable kernels can be found
175 in separate branches per version at:
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300176
Andrii Bordunovc1aa3872017-08-13 23:43:43 +0300177 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
Paul Gortmaker2584f522012-06-05 11:15:50 -0400178
Greg KHfc185d92005-07-29 12:14:34 -0700179
Mauro Carvalho Chehab5fe270a2016-09-19 08:07:51 -0300180Review committee
181----------------
Greg KHfc185d92005-07-29 12:14:34 -0700182
Jesper Juhle48e9902006-01-09 20:53:59 -0800183 - This is made up of a number of kernel developers who have volunteered for
184 this task, and a few that haven't.