blob: 0fa0143bf3774960b561f747e9b0cb23113257f8 [file] [log] [blame]
Tom Rinidc1ad472022-07-14 08:07:43 -04001.. SPDX-License-Identifier: GPL-2.0+:
2
3U-Boot Development Process
4==========================
5
6Management Summary
7------------------
8
9* Development happens in Release Cycles of 3 months.
10
Tom Rini105bccb2022-07-12 17:34:15 -040011* The first 3 weeks of the cycle are referred to as the Merge Window, which is
12 followed by a Stabilization Period.
Tom Rinidc1ad472022-07-14 08:07:43 -040013
14* Patches with new code get only accepted while the Merge Window is open.
15
16* A patch that is generally in good shape and that was submitted while the
17 Merge Window was open is eligible to go into the upcoming release, even if
18 changes and resubmits are needed.
19
20* During the Stabilization Period, only patches that contain bug fixes get
21 applied.
22
23Phases of the Development Process
24---------------------------------
25
26U-Boot development takes place in `Release Cycles
27<https://www.denx.de/wiki/U-Boot/ReleaseCycle>`_. A Release Cycle lasts
28normally for three months.
29
Tom Rini105bccb2022-07-12 17:34:15 -040030The first three weeks of each Release Cycle are called *Merge Window*.
Tom Rinidc1ad472022-07-14 08:07:43 -040031
32It is followed by a *Stabilization Period*.
33
34The end of a Release Cycle is marked by the release of a new U-Boot version.
35
36Merge Window
37------------
38
Tom Rini105bccb2022-07-12 17:34:15 -040039The Merge Window is the period when new patches get submitted (and hopefully
40accepted) for inclusion into U-Boot mainline. This period lasts for 21 days (3
41weeks) and ends with the release of ``"-rc1"``.
Tom Rinidc1ad472022-07-14 08:07:43 -040042
43This is the only time when new code (like support for new processors or new
44boards, or other new features or reorganization of code) is accepted.
45
46Twilight Time
47-------------
48
49Usually patches do not get accepted as they are - the peer review that takes
Tom Rini50a7adc2022-07-14 08:07:45 -040050place will usually require changes and resubmissions of the patches before they
Tom Rinidc1ad472022-07-14 08:07:43 -040051are considered to be ripe for inclusion into mainline.
52
Tom Rini50a7adc2022-07-14 08:07:45 -040053Also the review often happens not immediately after a patch was submitted,
Tom Rinidc1ad472022-07-14 08:07:43 -040054but only when somebody (usually the responsible custodian) finds time to do
55this.
56
Tom Rini50a7adc2022-07-14 08:07:45 -040057The result is that the final version of such patches gets submitted after the
Tom Rinidc1ad472022-07-14 08:07:43 -040058merge window has been closed.
59
60It is current practice in U-Boot that such patches are eligible to go into the
61upcoming release.
62
Tom Rini50a7adc2022-07-14 08:07:45 -040063The result is that the release of the ``"-rc1"`` version and formal closing of
64the Merge Window does not preclude patches that were already posted from being
65merged for the upcoming release.
Tom Rinidc1ad472022-07-14 08:07:43 -040066
67Stabilization Period
68--------------------
69
70During the Stabilization Period only patches containing bug fixes get
71applied.
72
73Corner Cases
74------------
75
76Sometimes it is not clear if a patch contains a bug fix or not.
77For example, changes that remove dead code, unused macros etc. or
78that contain Coding Style fixes are not strict bug fixes.
79
Tom Rini50a7adc2022-07-14 08:07:45 -040080In such situations it is up to the responsible custodian to decide if they
81apply such patches even when the Merge Window is closed.
Tom Rinidc1ad472022-07-14 08:07:43 -040082
83Exception: at the end of the Stabilization Period only strict bug
84fixes my be applied.
85
Tom Rini50a7adc2022-07-14 08:07:45 -040086Sometimes patches miss the Merge Window slightly - say by a few
Tom Rinidc1ad472022-07-14 08:07:43 -040087hours or even a day. Patch acceptance is not as critical as a
88financial transaction, or such. So if there is such a slight delay,
89the custodian is free to turn a blind eye and accept it anyway. The
90idea of the development process is to make it foreseeable,
91but not to slow down development.
92
93It makes more sense if an engineer spends another day on testing and
94cleanup and submits the patch a couple of hours late, instead of
95submitting a green patch which will waste efforts from several people
96during several rounds of review and reposts.
97
98Differences to the Linux Development Process
99--------------------------------------------
100
101* In Linux, top-level maintainers will collect patches in their trees and send
102 pull requests to Linus as soon as the merge window opens.
103 So far, most U-Boot custodians do not work like that; they send pull requests
104 only at (or even after) the end of the merge window.
105
106* In Linux, the closing of the merge window is marked by the release of the
107 next ``"-rc1"``
108 In U-Boot, ``"-rc1"`` will only be released after all (or at least most of
109 the) patches that were submitted during the merge window have been applied.
110
Tom Rini6349b182022-08-29 12:59:33 -0400111.. _custodians:
112
Tom Rinidc1ad472022-07-14 08:07:43 -0400113Custodians
114----------
115
116The Custodians take responsibility for some area of the U-Boot code. The
Tom Rini50a7adc2022-07-14 08:07:45 -0400117in-tree ``MAINTAINERS`` files list who is responsible for which areas.
Tom Rinidc1ad472022-07-14 08:07:43 -0400118
119It is their responsibility to pick up patches from the mailing list
120that fall into their responsibility, and to process these.
121
122A very important responsibility of each custodian is to provide
123feedback to the submitter of a patch about what is going on: if the
124patch was accepted, or if it was rejected (which exact list of
125reasons), if it needs to be reworked (with respective review
126comments). Even a "I have no time now, will look into it later"
127message is better than nothing. Also, if there are remarks to a
128patch, these should leave no doubt if they were just comments and the
129patch will be accepted anyway, or if the patch should be
130reworked/resubmitted, or if it was rejected.
131
Tom Rini286ed782022-08-29 12:59:34 -0400132Review Process, Git Tags
133------------------------
134
135There are a number of *git tags* that are used to document the origin and the
136processing of patches on their way into the mainline U-Boot code. The following
137is an attempt to document how these are usually handled in the U-Boot project.
138
139In general, we try to follow the established procedures from other projects,
140especially the Linux kernel, but there may be smaller differences. For
141reference, see the Linux kernel's `Submitting patches
142<https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_
143document.
144
145.. _dco:
146
147* Signed-off-by: the *Signed-off-by:* is a line at the end of the commit
148 message by which the signer certifies that they were involved in the development
149 of the patch and that they accept the `Developer Certificate of Origin
150 <https://developercertificate.org/>`_. Following this and adding a
151 ``Signed-off-by:`` line that contains the developer's name and email address
152 is required.
153
154 * Please note that in U-Boot, we do not add a ``Signed-off-by`` tag if we
155 just pass on a patch without any changes.
156
157 * Please note that when importing code from other projects you must say
158 where it comes from, and what revision you are importing. You must not
159 however copy ``Signed-off-by`` or other tags.
160
161* Everybody who can is invited to review and test the changes. Typically, we
162 follow the same guidelines as the Linux kernel for `Acked-by
163 <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#when-to-use-acked-by-cc-and-co-developed-by>`_
164 as well as `Reviewed-by
165 <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`_
166 and similar additional tags.
167
168* Reviewed-by: The patch has been reviewed and found acceptible according to
169 the `Reveiwer's statement of oversight
170 <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight>`_.
171 A *Reviewed-by:* tag is a statement of opinion that the patch is an
172 appropriate modification of the code without any remaining serious technical
173 issues. Any interested reviewer (who has done the work) can offer a
174 *Reviewed-by:* tag for a patch.
175
176* Acked-by: If a person was not directly involved in the preparation or
177 handling of a patch but wishes to signify and record their approval of it
178 then they can arrange to have an *Acked-by:* line added to the patch's
179 changelog.
180
181* Tested-by: A *Tested-by:* tag indicates that the patch has been successfully
182 tested (in some environment) by the person named. Andrew Morton: "I think
183 it's very useful information to have. For a start, it tells you who has the
184 hardware and knows how to build a kernel. So if you're making a change to a
185 driver and want it tested, you can troll the file's changelog looking for
186 people who might be able to help."
187
188* Reported-by: If this patch fixes a problem reported by somebody else,
189 consider adding a *Reported-by:* tag to credit the reporter for their
190 contribution. Please note that this tag should not be added without the
191 reporter's permission, especially if the problem was not reported in a public
192 forum.
193
194* Cc: If a person should have the opportunity to comment on a patch, you may
195 optionally add a *Cc:* tag to the patch. Git tools (git send-email) will then
196 automatically arrange that they receives a copy of the patch when you submit it
197 to the mainling list. This is the only tag which might be added without an
198 explicit action by the person it names. This tag documents that potentially
199 interested parties have been included in the discussion.
200 For example, when your change affects a specific board or driver, then makes
201 a lot of sense to put the respective maintainer of this code on Cc:
202
Tom Rinidc1ad472022-07-14 08:07:43 -0400203Work flow of a Custodian
204------------------------
205
206The normal flow of work in the U-Boot development process will look
207like this:
208
Tom Rini61550732022-07-14 08:07:46 -0400209#. The responsible custodian inspects this patch, especially for:
Tom Rinidc1ad472022-07-14 08:07:43 -0400210
Tom Rini286ed782022-08-29 12:59:34 -0400211 #. The commit message is useful, descriptive and makes correct and
212 appropraite usage of required *git tags*.
213
Tom Rinidc1ad472022-07-14 08:07:43 -0400214 #. :doc:`codingstyle`
215
216 #. Basic logic:
217
218 * The patch fixes a real problem.
219
220 * The patch does not introduce new problems, especially it does not break
221 other boards or architectures
222
Tom Rini61550732022-07-14 08:07:46 -0400223 #. U-Boot Philosophy, as documented in :doc:`designprinciples`.
Tom Rinidc1ad472022-07-14 08:07:43 -0400224
Tom Rini61550732022-07-14 08:07:46 -0400225 #. Applies cleanly to the source tree. The custodian is expected to put in
226 a "best effort" if a patch does not apply cleanly, but can be made to apply
227 still. It is up to the custodian to decide how recent of a commit the
228 patch must be against. It is acceptable to request patches against the
229 last officially released version of U-Boot or newer. Of course a
230 custodian can also accept patches against older code. It can be
231 difficult to find the correct balance between putting too much work on
232 the custodian or too much work on an individual submitting a patch when
233 something does not apply cleanly.
Tom Rinidc1ad472022-07-14 08:07:43 -0400234
Tom Rini50a7adc2022-07-14 08:07:45 -0400235 #. Passes :doc:`ci_testing` as this checks for new warnings and other issues.
Tom Rinidc1ad472022-07-14 08:07:43 -0400236
Tom Rini61550732022-07-14 08:07:46 -0400237#. Note that in some cases more than one custodian may feel responsible for a
238 particular change. To avoid duplicated efforts, the custodian who starts
239 processing the patch should follow up to the email saying they intend to
240 pick it up.
Tom Rinidc1ad472022-07-14 08:07:43 -0400241
Tom Rini61550732022-07-14 08:07:46 -0400242#. Commits must show original author in the ``author`` field and include all of
243 the ``Signed-off-by``, ``Reviewed-by``, etc, tags that have been submitted.
Tom Rinidc1ad472022-07-14 08:07:43 -0400244
Tom Rini61550732022-07-14 08:07:46 -0400245#. The final decision to accept or reject a patch comes down to the custodian
246 in question.
Tom Rinidc1ad472022-07-14 08:07:43 -0400247
Tom Rini61550732022-07-14 08:07:46 -0400248#. If accepted, the custodian adds the patch to their public git repository.
249 Ideally, they will also follow up on the mailing list with some notification
250 that it has been applied. This is not always easy given different custodian
251 workflows and environments however.
Tom Rinidc1ad472022-07-14 08:07:43 -0400252
Tom Rini61550732022-07-14 08:07:46 -0400253#. Although a custodian is supposed to perform their own tests it is a
254 well-known and accepted fact that they needs help from other developers who
255 - for example - have access to the required hardware or other relevant
256 environments. Custodians are expected to ask for assistance with testing
257 when required.
Tom Rinidc1ad472022-07-14 08:07:43 -0400258
Tom Rini61550732022-07-14 08:07:46 -0400259#. Custodians are expected to submit a timely pull request of their git
260 repository to the main repository. It is strongly encouraged that a CI run
261 has been completed prior to submission, but not required.