doc/develop/process.rst

   1 .. SPDX-License-Identifier: GPL-2.0+:
   2
   3 U-Boot Development Process
   4 ==========================
   5
   6 Management 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
  23 Phases of the Development Process
  24 ---------------------------------
  25
  26 U-Boot development takes place in `Release Cycles
  27 <https://www.denx.de/wiki/U-Boot/ReleaseCycle>`_.  A Release Cycle lasts
  28 normally for three months.
  29
  30 The first three weeks of each Release Cycle are called *Merge Window*.
  31
  32 It is followed by a *Stabilization Period*.
  33
  34 The end of a Release Cycle is marked by the release of a new U-Boot version.
  35
  36 Merge Window
  37 ------------
  38
  39 The Merge Window is the period when new patches get submitted (and hopefully
  40 accepted) for inclusion into U-Boot mainline. This period lasts for 21 days (3
  41 weeks) and ends with the release of ``"-rc1"``.
  42
  43 This is the only time when new code (like support for new processors or new
  44 boards, or other new features or reorganization of code) is accepted.
  45
  46 Twilight Time
  47 -------------
  48
  49 Usually patches do not get accepted as they are - the peer review that takes
  50 place will usually require changes and resubmissions of the patches before they
  51 are considered to be ripe for inclusion into mainline.
  52
  53 Also the review often happens not immediately after a patch was submitted,
  54 but only when somebody (usually the responsible custodian) finds time to do
  55 this.
  56
  57 The result is that the final version of such patches gets submitted after the
  58 merge window has been closed.
  59
  60 It is current practice in U-Boot that such patches are eligible to go into the
  61 upcoming release.
  62
  63 The result is that the release of the ``"-rc1"`` version and formal closing of
  64 the Merge Window does not preclude patches that were already posted from being
  65 merged for the upcoming release.
  66
  67 Stabilization Period
  68 --------------------
  69
  70 During the Stabilization Period only patches containing bug fixes get
  71 applied.
  72
  73 Corner Cases
  74 ------------
  75
  76 Sometimes it is not clear if a patch contains a bug fix or not.
  77 For example, changes that remove dead code, unused macros etc. or
  78 that contain Coding Style fixes are not strict bug fixes.
  79
  80 In such situations it is up to the responsible custodian to decide if they
  81 apply such patches even when the Merge Window is closed.
  82
  83 Exception: at the end of the Stabilization Period only strict bug
  84 fixes my be applied.
  85
  86 Sometimes patches miss the Merge Window slightly - say by a few
  87 hours or even a day. Patch acceptance is not as critical as a
  88 financial transaction, or such. So if there is such a slight delay,
  89 the custodian is free to turn a blind eye and accept it anyway. The
  90 idea of the development process is to make it foreseeable,
  91 but not to slow down development.
  92
  93 It makes more sense if an engineer spends another day on testing and
  94 cleanup and submits the patch a couple of hours late, instead of
  95 submitting a green patch which will waste efforts from several people
  96 during several rounds of review and reposts.
  97
  98 Differences 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
 113 Custodians
 114 ----------
 115
 116 The Custodians take responsibility for some area of the U-Boot code.  The
 117 in-tree ``MAINTAINERS`` files list who is responsible for which areas.
 118
 119 It is their responsibility to pick up patches from the mailing list
 120 that fall into their responsibility, and to process these.
 121
 122 A very important responsibility of each custodian is to provide
 123 feedback to the submitter of a patch about what is going on: if the
 124 patch was accepted, or if it was rejected (which exact list of
 125 reasons), if it needs to be reworked (with respective review
 126 comments). Even a "I have no time now, will look into it later"
 127 message is better than nothing. Also, if there are remarks to a
 128 patch, these should leave no doubt if they were just comments and the
 129 patch will be accepted anyway, or if the patch should be
 130 reworked/resubmitted, or if it was rejected.
 131
 132 Review Process, Git Tags
 133 ------------------------
 134
 135 There are a number of *git tags* that are used to document the origin and the
 136 processing of patches on their way into the mainline U-Boot code. The following
 137 is an attempt to document how these are usually handled in the U-Boot project.
 138
 139 In general, we try to follow the established procedures from other projects,
 140 especially the Linux kernel, but there may be smaller differences. For
 141 reference, see the Linux kernel's `Submitting patches
 142 <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_
 143 document.
 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
 203 Work flow of a Custodian
 204 ------------------------
 205
 206 The normal flow of work in the U-Boot development process will look
 207 like this:
 208
 209 #. The responsible custodian inspects this patch, especially for:
 210
 211    #. The commit message is useful, descriptive and makes correct and
 212       appropraite 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 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.
 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.