Patches and Feature Requests

Before you begin to implement any new ideas or concepts it is always a good idea to present your plans on the u-boot-users mailing list. U-Boot supports a huge amount of very different systems, and it is often impossible for the individual developer to oversee the consequences of a specific change to all architectures. Discussing concepts early can help you to avoid spending effort on code which, when submitted as a patch, might be rejected and/or will need lots of rework because it does not fit for some reason. Early peer review is an important resource - use it.

A good introduction how to prepare for submitting patches can be found in the LWN article How to Get Your Change Into the Linux Kernel - the same rules apply to U-Boot, too:

General Patch Submission Rules

• All patches must be sent to the u-boot@lists.denx.de mailing list.
• Patches should always contain exactly one complete logical change, i. e.
  • Changes that contain different, unrelated modifications shall be submitted as separate patches, one patch per changeset.
  • If one logical set of modifications affects or creates several files, all these changes shall be submitted in a single patch.
• Send your patches as plain text messages: no HTML, no MIME, no links, no compression, no attachments. Just plain text.
  The best way the generate patches is by using the "git format-patch" command.
  Please use the "master" branch of the mainline U-Boot git repository (git://git.denx.de/u-boot.git) as reference, unless (usually late in a release cycle) there has been an announcement to use the "next" branch of this repository instead.
• Make sure that your mailer does not mangle the patch by automatic changes like wrapping of longer lines etc.
  The best way to send patches is by not using your regular mail tool, but by using the "git send-email" command instead.
• Choose a meaningful Subject: - keep in mind that the Subject will also be visible as headline of your commit message. Make sure the subject does not exceed 60 characters or so.
• Include the string "PATCH" in the Subject: line of your message, e. g. "[PATCH] Add support for feature X". git format-patch should automatically do this.
  • If you are re-sending a modified version of a patch which you have already submitted, make note of it in the subject line, eg "[PATCH v2] Add support for feature X". =git format-patch --subject-prefix="PATCH v2"= can be used in this case.
• If you are sending a patch series composed of multiple patches, make sure their titles clearly state the patch order and total number of patches (git format-patch -n). Also, often times an introductory email describing what the patchset does is useful (git format-patch -n --cover-letter). As an example:
  • [PATCH 0/3] Add support for new SuperCPU2000
    (This email does not contain a patch, just a description)
  • [PATCH 1/3] Add core support for SuperCPU2000
  • [PATCH 2/3] Add support for SuperCPU2000's on-chip I2C controller
  • [PATCH 3/3] Add support for SuperCPU2000's on-chip UART
• In the message body, include a description of your changes.
  • For bug fixes: a description of the bug and how your patch fixes this bug. Please try to include a way of demonstrating that the patch actually fixes something.
  • For new features: a description of the feature and your implementation.
  • Additional comments which you don't want included in U-Boot's history can be included below the first "---" in the message body.
• If your description gets too long, that's a strong indication that you should split up your patch.
• Remember that there is a size limit of 100 kB on the mailing list. In most cases, you did something wrong if your patch exceeds this limit. Think again if you should not split it into separate logical parts. If your patch, uncompressed, exceeds this limit, and you are absolutely sure that you should not split it, then provide a URL (link) pointing to your patch instead. Make sure that the URL remains valid for a long time (i. e. years); using some "pastebin" etc. is not sufficient.
• Sign your changes, i. e. add a "Signed-off-by:" line to the message body. This is automatically added to a commit if =git commit -s= is ran.

Log message conventions

Please adhere to the following conventions when writing your commit log messages:

• The first line of the log message is the summary line. Keep this less than 70 characters long.
• Don't use periods to end the summary line (e.g., don't do "Add support for X.")
• Use the present tense in your summary line (e.g., "Add support for X" rather than "Added support for X"). Furthermore, use the present tense in your log message to describe what the patch is doing. This isn't a strict rule -- it's OK to use the past tense for describing things that were happening in the old code for example.
• Use the imperative tense in your summary line (e.g., "Add support for X" rather than "Adds support for X"). In general, you can think of the summary line as "this commit is meant to 'Add support for X'"
• If applicable, prefix the summary line with a word describing what area of code is being affected followed by a colon. This is a standard adopted by both U-Boot and Linux. For example, if your change affects all mpc85xx boards, prefix your summary line with "mpc85xx:". If your change affects the PCI common code, prefix your summary line with "pci:". The best thing to do is look at the "git log " output to see what others have done so you don't break conventions.
• Insert a blank line after the summary line
• For bug fixes, it's good practice to briefly describe how things behaved before this commit
• Put a detailed description after the summary and blank line. If the summary line is sufficient to describe the change, you can omit the blank line and detailed description.
• End your log message with S.O.B. (Signed-off-by) line. This is done automatically when you use "git commit -s".
• Keep EVERY line under 72 characters. That is, your message should be line-wrapped with line-feeds. However, don't get carried away and wrap it too short either since this also looks funny.
• Detail level: The audience of the commit log message that you should cater to is those familiar with the underlying source code you are modifying, but who are not familiar with the patch you are submitting. They should be able to determine what is being changed and why. Avoid excessive low-level detail. Before submitting, re-read your commit log message with this audience in mind and adjust as needed.

If you have problems with your e-mail client, for example because it mangles white space or wraps long lines, then please read this article about Email Clients and Patches .

Note:

U-Boot is Free Software that can redistributed and/or modified under the terms of the GNU General Public License (GPL). Currently (July 2009) version 2 of the GPL applies. There are plans to move later versions of U-Boot to version 3 of the GPL, thus all new code that gets added to U-Boot shall use GPLv3-compatible licensing, for example using the common "GPL, either version 2, or (at your option) any later version" phrase.

Note 2:

All code must follow the U-Boot Coding Style requirements.

Note 3:

Before sending the patch, you must run the MAKEALL script on your patched source tree and make sure that no errors or warnings are reported for any of the boards. Well, at least not any more warnings than without your patch.

It is strongly recommended to verify that out-of-tree building (with "-O" -make_ option resp. "BUILD_DIR" environment variable) is still working. For example, run:

$ BUILD_DIR=/tmp/u-boot-build ./MAKEALL

Please also run MAKEALL for at least one other architecture than the one you made your modifications in.

Note 4:

If you modify existing code, make sure that your new code does not add to the memory footprint of the code.

Remember

Small is beautiful! When adding new features, these should compile conditionally only (using the configuration system resp. #ifdef), and the resulting code with the new feature disabled must not need more memory than the old code without your modification.