1.. 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 11* The first 3 weeks of the cycle are referred to as the Merge Window, which is 12 followed by a Stabilization Period. 13 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 30The first three weeks of each Release Cycle are called *Merge Window*. 31 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 39The 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"``. 42 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 50place will usually require changes and resubmissions of the patches before they 51are considered to be ripe for inclusion into mainline. 52 53Also the review often happens not immediately after a patch was submitted, 54but only when somebody (usually the responsible custodian) finds time to do 55this. 56 57The result is that the final version of such patches gets submitted after the 58merge window has been closed. 59 60It is current practice in U-Boot that such patches are eligible to go into the 61upcoming release. 62 63The 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. 66 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 80In such situations it is up to the responsible custodian to decide if they 81apply such patches even when the Merge Window is closed. 82 83Exception: at the end of the Stabilization Period only strict bug 84fixes my be applied. 85 86Sometimes patches miss the Merge Window slightly - say by a few 87hours 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 111.. _custodians: 112 113Custodians 114---------- 115 116The Custodians take responsibility for some area of the U-Boot code. The 117in-tree ``MAINTAINERS`` files list who is responsible for which areas. 118 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 132Review 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 acceptable according to 169 the `Reviewer'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 197 it to the mailing 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 203Work flow of a Custodian 204------------------------ 205 206The normal flow of work in the U-Boot development process will look 207like this: 208 209#. The responsible custodian inspects this patch, especially for: 210 211 #. The commit message is useful, descriptive and makes correct and 212 appropriate usage of required *git tags*. 213 214 #. :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 223 #. U-Boot Philosophy, as documented in :doc:`designprinciples`. 224 225 #. 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. 234 235 #. Passes :doc:`ci_testing` as this checks for new warnings and other issues. 236 237#. 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. 241 242#. 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. 244 245#. The final decision to accept or reject a patch comes down to the custodian 246 in question. 247 248#. 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. 252 253#. Although a custodian is supposed to perform their own tests it is a 254 well-known and accepted fact that they need 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. 258 259#. 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. 262