1 .. SPDX-License-Identifier: GPL-2.0+
6 *Before you begin* to implement any new ideas or concepts it is always a good
7 idea to present your plans on the `U-Boot mailing list
8 <https://lists.denx.de/listinfo/u-boot>`_. U-Boot supports a huge amount of
9 very different systems, and it is often impossible for the individual developer
10 to oversee the consequences of a specific change to all architectures.
11 Discussing concepts early can help you to avoid spending effort on code which,
12 when submitted as a patch, might be rejected and/or will need lots of rework
13 because it does not fit for some reason. Early peer review is an important
14 resource - use it. Being familiar with the :doc:`process` is also important.
16 A good introduction how to prepare for submitting patches can be found in the
17 LWN article `How to Get Your Change Into the Linux Kernel
18 <http://lwn.net/Articles/139918/>`_ as the same rules apply to U-Boot, too.
23 You can use a tool called patman to prepare, check and send patches. It creates
24 change logs, cover letters and patch notes. It also simplifies the process of
25 sending multiple versions of a series.
27 See more details at :doc:`patman`.
29 General Patch Submission Rules
30 ------------------------------
32 * All patches must be sent to the `u-boot@lists.denx.de
33 <https://lists.denx.de/listinfo/u-boot>`_ mailing list.
35 * If your patch affects the code maintained by one of the :ref:`custodians`, CC
36 them when emailing your patch. The easiest way to make sure you don't forget
37 this even when you resubmit the patch later is to add a ``Cc: name
38 <address>`` line after your ``Signed-off-by:`` line (see the example below).
40 * Take a look at the commit logs of the files you are modifying. Authors of
41 past commits might have input to your change, so also CC them if you think
42 they may have feedback.
44 * Patches should always contain exactly one complete logical change, i.e.
46 * Changes that contain different, unrelated modifications shall be submitted
47 as *separate* patches, one patch per changeset.
49 * If one logical set of modifications affects or creates several files, all
50 these changes shall be submitted in a *single* patch.
52 * Non-functional changes, i.e. whitespace and reformatting changes, should be
53 done in separate patches marked as ``cosmetic``. This separation of functional
54 and cosmetic changes greatly facilitates the review process.
56 * Some comments on running :doc:`checkpatch.pl <checkpatch>`:
58 * Checkpatch is a tool that can help you find some style problems, but is
59 imperfect, and the things it complains about are of varying importance.
60 So use common sense in interpreting the results.
62 * Warnings that clearly only make sense in the Linux kernel can be ignored.
63 This includes ``Use #include <linux/$file> instead of <asm/$file>`` for
66 * If you encounter warnings for existing code, not modified by your patch,
67 consider submitting a separate, cosmetic-only patch -- clearly described
68 as such -- that *precedes* your substantive patch.
70 * For minor modifications (e.g. changed arguments of a function call),
71 adhere to the present coding style of the module. Relating checkpatch
72 warnings can be ignored in this case. A respective note in the commit or
73 cover letter why they are ignored is desired.
75 * Send your patches as plain text messages: no HTML, no MIME, no links, no
76 compression, no attachments. Just plain text. The best way the generate
77 patches is by using the ``git format-patch`` command. Please use the
78 ``master`` branch of the mainline U-Boot git repository
79 (``https://source.denx.de/u-boot/u-boot.git``) as reference, unless (usually
80 late in a release cycle) there has been an announcement to use the ``next``
81 branch of this repository instead.
83 * Make sure that your mailer does not mangle the patch by automatic changes
84 like wrapping of longer lines etc.
85 The best way to send patches is by not using your regular mail tool, but by
86 using either ``git send-email`` or the ``git imap-send`` command instead.
87 If you believe you need to use a mailing list for testing (instead of any
88 regular mail address you own), we have a special test list for such purposes.
89 It would be best to subscribe to the list for the duration of your tests to
90 avoid repeated moderation - see https://lists.denx.de/listinfo/test
92 * Choose a meaningful Subject: - keep in mind that the Subject will also be
93 visible as headline of your commit message. Make sure the subject does not
94 exceed 60 characters or so.
96 * The start of the subject should be a meaningful tag (arm:, ppc:, tegra:,
99 * Include the string "PATCH" in the Subject: line of your message, e. g.
100 "[PATCH] Add support for feature X". ``git format-patch`` should automatically
103 * If you are sending a patch series composed of multiple patches, make sure
104 their titles clearly state the patch order and total number of patches (``git
105 format-patch -n``). Also, often times an introductory email describing what
106 the patchset does is useful (``git format-patch -n --cover-letter``). As an
109 [PATCH 0/3] Add support for new SuperCPU2000
110 (This email does not contain a patch, just a description)
111 [PATCH 1/3] Add core support for SuperCPU2000
112 [PATCH 2/3] Add support for SuperCPU2000's on-chip I2C controller
113 [PATCH 3/3] Add support for SuperCPU2000's on-chip UART
115 * In the message body, include a description of your changes.
117 * For bug fixes: a description of the bug and how your patch fixes this bug.
118 Please try to include a way of demonstrating that the patch actually fixes
121 * For new features: a description of the feature and your implementation.
123 * Additional comments which you don't want included in U-Boot's history can be
124 included below the first "---" in the message body.
126 * If your description gets too long, that's a strong indication that you should
129 * Remember that there is a size limit of 100 kB on the mailing list. In most
130 cases, you did something wrong if your patch exceeds this limit. Think again
131 if you should not split it into separate logical parts.
133 Attributing Code, Copyrights, Signing
134 -------------------------------------
136 * Sign your changes, i. e. add a *Signed-off-by:* line to the message body.
137 This can be automated by using ``git commit -s``. Please see the
138 :ref:`Developer Certificate of Origin <dco>` section for more details here.
140 * If you change or add *significant* parts to a file, then please make sure to
141 add your copyright to that file, for example like this::
143 (C) Copyright 2010 Joe Hacker <jh@hackers.paradise.com>
145 Please do *not* include a detailed description of your
146 changes. We use the *git* commit messages for this purpose.
148 * If you add new files, please always make sure that these contain your
149 copyright note and a GPLv2+ SPDX-License-Identifier, for example like this::
151 (C) Copyright 2010 Joe Hacker <jh@hackers.paradise.com>
153 SPDX-License-Identifier:<TAB>GPL-2.0+
155 * If you are copying or adapting code from other projects, like the Linux
156 kernel, or BusyBox, or similar, please make sure to state clearly where you
157 copied the code from, and provide terse but precise information which exact
158 version or even commit ID was used. Follow the ideas of this note from the
159 Linux "SubmittingPatches" document::
161 Special note to back-porters: It seems to be a common and useful practice
162 to insert an indication of the origin of a patch at the top of the commit
163 message (just after the subject line) to facilitate tracking. For instance,
164 here's what we see in 2.6-stable :
166 Date: Tue May 13 19:10:30 2008 +0000
168 SCSI: libiscsi regression in 2.6.25: fix nop timer handling
170 commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream
172 And here's what appears in 2.4 :
174 Date: Tue May 13 22:12:27 2008 +0200
176 wireless, airo: waitbusy() won't delay
178 [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]
180 Whatever the format, this information provides a valuable help to people
181 tracking your trees, and to people trying to trouble-shoot bugs in your
184 Commit message conventions
185 --------------------------
187 Please adhere to the following conventions when writing your commit
190 * The first line of the log message is the summary line. Keep this less than 70
193 * Don't use periods to end the summary line (e.g., don't do "Add support for
196 * Use the present tense in your summary line (e.g., "Add support for X" rather
197 than "Added support for X"). Furthermore, use the present tense in your log
198 message to describe what the patch is doing. This isn't a strict rule -- it's
199 OK to use the past tense for describing things that were happening in the old
202 * Use the imperative tense in your summary line (e.g., "Add support for X"
203 rather than "Adds support for X"). In general, you can think of the summary
204 line as "this commit is meant to 'Add support for X'"
206 * If applicable, prefix the summary line with a word describing what area of
207 code is being affected followed by a colon. This is a standard adopted by
208 both U-Boot and Linux. For example, if your change affects all mpc85xx
209 boards, prefix your summary line with "mpc85xx:". If your change affects the
210 PCI common code, prefix your summary line with "pci:". The best thing to do
211 is look at the "git log <file>" output to see what others have done so you
212 don't break conventions.
214 * Insert a blank line after the summary line
216 * For bug fixes, it's good practice to briefly describe how things behaved
219 * Put a detailed description after the summary and blank line. If the summary
220 line is sufficient to describe the change (e.g. it is a trivial spelling
221 correction or whitespace update), you can omit the blank line and detailed
224 * End your log message with S.O.B. (Signed-off-by) line. This is done
225 automatically when you use ``git commit -s``. Please see the
226 :ref:`Developer Certificate of Origin <dco>` section for more details here.
228 * Keep EVERY line under 72 characters. That is, your message should be
229 line-wrapped with line-feeds. However, don't get carried away and wrap it too
230 short either since this also looks funny.
232 * Detail level: The audience of the commit log message that you should cater to
233 is those familiar with the underlying source code you are modifying, but who
234 are _not_ familiar with the patch you are submitting. They should be able to
235 determine what is being changed and why. Avoid excessive low-level detail.
236 Before submitting, re-read your commit log message with this audience in mind
237 and adjust as needed.
239 Sending updated patch versions
240 ------------------------------
242 It is pretty normal that the first version of a patch you are submitting does
243 not get accepted as is, and that you are asked to submit another, improved
246 When re-posting such a new version of your patch(es), please always make sure
247 to observe the following rules.
249 * Make an appropriate note that this is a re-submission in the subject line,
250 e.g. "[PATCH v2] Add support for feature X". ``git format-patch
251 --subject-prefix="PATCH v2"`` can be used in this case (see the example
254 * Please make sure to keep a "change log", i.e. a description of what you have
255 changed compared to previous versions of this patch. This change log should
256 be added below the "---" line in the patch, which starts the "comment
257 section", i.e. which contains text that does not get included into the
258 actual commit message.
259 Note: it is *not* sufficient to provide a change log in some cover letter
260 that gets sent as a separate message with the patch series. The reason is
261 that such cover letters are not as easily reviewed in our `patchwork queue
262 <http://patchwork.ozlabs.org/project/uboot/list/>`_ so they are not helpful
263 to any reviewers using this tool. Example::
265 From: Joe Hacker <jh@hackers.paradise.com>
266 Date: Thu, 1 Jan 2222 12:21:22 +0200
267 Subject: [PATCH 1/2 v3] FOO: add timewarp-support
269 This patch adds timewarp-support for the FOO family of processors.
271 adapted for the current kernel structures.
273 Signed-off-by: Joe Hacker <jh@hackers.paradise.com>
274 Cc: Tom Maintainer <tm@u-boot.custodians.org>
277 - Coding Style cleanup
278 - fixed miscalculation of time-space discontinuities
280 - fixed compiler warnings observed with GCC-17.3.5
281 - worked around integer overflow in warp driver
283 arch/foo/cpu/spacetime.c | 8 +
284 drivers/warp/Kconfig | 7 +
285 drivers/warp/Makefile | 42 +++
286 drivers/warp/warp-core.c | 255 +++++++++++++++++++++++++
288 * Make sure that your mailer adds or keeps correct ``In-reply-to:`` and
289 ``References:`` headers, so threading of messages is working and everybody
290 can see that the new message refers to some older posting of the same topic.
292 Uncommented and un-threaded repostings are extremely annoying and
293 time-consuming, as we have to try to remember if anything similar has been
294 posted before, look up the old threads, and then manually compare if anything
295 has been changed, or what.
297 If you have problems with your e-mail client, for example because it mangles
298 white space or wraps long lines, then please read this article about `Email
299 Clients and Patches <http://kerneltrap.org/Linux/Email_Clients_and_Patches>`_.
304 1. U-Boot is Free Software that can redistributed and/or modified under the
305 terms of the `GNU General Public License
306 <http://www.fsf.org/licensing/licenses/gpl.html>`_ (GPL). Currently (August
307 2022) version 2 of the GPL applies. Please see :download:`Licensing
308 <../../Licenses/README>` for details. To allow that later versions of U-Boot
309 may be released under a later version of the GPL, all new code that gets
310 added to U-Boot shall use a "GPL-2.0+" SPDX-License-Identifier.
312 2. All code must follow the :doc:`codingstyle` requirements.
314 3. Before sending the patch, you *must* run some form of local testing.
315 Submitting a patch that does not build or function correctly is a mistake. For
316 non-trivial patches, either building a number of platforms locally or making
317 use of :doc:`ci_testing` is strongly encouraged in order to avoid problems
318 that can be found when attempting to merge the patch.
320 4. If you modify existing code, make sure that your new code does not add to
321 the memory footprint of the code. Remember: Small is beautiful! When adding
322 new features follow the guidelines laid out in :doc:`system_configuration`.
327 Like some other projects, U-Boot uses `Patchwork <http://patchwork.ozlabs.org/>`_
328 to track the state of patches. This is one of the reasons why it is mandatory
329 to submit all patches to the U-Boot mailing list - only then they will be
330 picked up by patchwork.
332 At http://patchwork.ozlabs.org/project/uboot/list/ you can find the list of
333 open U-Boot patches. By using the "Filters" link (Note: requires JavaScript)
334 you can also select other views, for example, to include old patches that have,
335 for example, already been applied or rejected.
337 Note that Patchwork automatically tracks and collects a number of git tags from
338 follow-up mails, so it is usually better to apply a patch through the Patchwork
339 commandline interface than just manually applying it from a posting on the
340 mailing list (in which case you have to do all the tracking and adding of git
341 tags yourself). This also obviates the need of a developer to resubmit a patch
342 only in order to collect these tags.
344 A Custodian has additional privileges and can:
346 * **Delegate** a patch
348 * **Change the state** of a patch. The following states exist:
375 The following are a "rule of thumb" as to how the states are used in patchwork
376 today. Not all states are used by all custodians.
378 * New: Patch has been submitted to the list, and none of the maintainers has
379 changed it's state since.
381 * Under Review: A custodian is reviewing the patch currently.
383 * Accepted: When a patch has been applied to a custodian repository that gets
384 used for pulling from into upstream, they are put into "accepted" state.
386 * Rejected: Rejected means we just don't want to do what the patch does.
388 * RFC: The patch is not intended to be applied to any of the mainline
389 repositories, but merely for discussing or testing some idea or new feature.
391 * Not Applicable: The patch either was not intended to be applied, as it was
392 a debugging or discussion aide that patchwork picked up, or was cross-posted
393 to our list but intended for another project entirely.
395 * Changes Requested: The patch looks mostly OK, but requires some rework before
396 it will be accepted for mainline.
398 * Awaiting Upstream: A custodian may have applied this to the ``next`` branch
399 and has not merged yet to master, or has queued the patch up to be submitted
400 to be merged, but has not yet.
402 * Superseeded: Patches are marked as 'superseeded' when the poster submits a
403 new version of these patches.
405 * Deferred: Deferred usually means the patch depends on something else that
406 isn't upstream, such as patches that only apply against some specific other
407 repository. This is also used when a patch has been in patchwork for over a
408 year and it is unlikely to be applied as-is.
410 * Archived: Archiving puts the patch away somewhere where it doesn't appear in
411 the normal pages and needs extra effort to get to.
416 To apply a patch from the `patchwork queue
417 <http://patchwork.ozlabs.org/project/uboot/list/>`_ using ``git``, download the
418 mbox file and apply it using::
422 The `openembedded wiki <http://wiki.openembedded.net/>`_ also provides a script
424 <http://cgit.openembedded.org/cgit.cgi/openembedded/tree/contrib/patchwork/pw-am.sh>`_
425 which can be used to fetch an 'mbox' patch from patchwork and git am it::
427 usage: pw-am.sh <number>
428 example: 'pw-am.sh 71002' will get and apply the patch from http://patchwork.ozlabs.org/patch/71002/
430 Update the state of patches
431 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
433 You have to register to be able to update the state of patches. You can use the
434 Web interface, `pwclient`, or `pwparser`.
439 The `pwclient` command line tool can be used for example to retrieve patches,
440 search the queue or update the state.
442 All necessary information for `pwclient` is linked from the bottom of
443 http://patchwork.ozlabs.org/project/uboot/
449 for an overview on how to use it.
454 See http://www.mail-archive.com/patchwork@lists.ozlabs.org/msg00057.html