doc/develop/sending_patches.rst - u-boot - Git at Google


            
            .. SPDX-License-Identifier: GPL-2.0+


            Sending patches

            
            ===============


            *Before you begin* to implement any new ideas or concepts it is always a good

            
            idea to present your plans on the `U-Boot mailing list

            
            <https://lists.denx.de/listinfo/u-boot>`_. 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. Being familiar with the :doc:`process` is also important.


            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

            
            <http://lwn.net/Articles/139918/>`_ as the same rules apply to U-Boot, too.


            Using patman

            
            ------------


            You can use a tool called patman to prepare, check and send patches. It creates

            
            change logs, cover letters and patch notes. It also simplifies the process of

            
            sending multiple versions of a series.


            See more details at :doc:`patman`.


            General Patch Submission Rules

            
            ------------------------------


            * All patches must be sent to the `u-boot@lists.denx.de

            
              <https://lists.denx.de/listinfo/u-boot>`_ mailing list.


            * If your patch affects the code maintained by one of the :ref:`custodians`, CC

            
              them when emailing your patch. The easiest way to make sure you don't forget

            
              this even when you resubmit the patch later is to add a ``Cc: name

            
              <address>`` line after your ``Signed-off-by:`` line (see the example below).


            * Take a look at the commit logs of the files you are modifying. Authors of

            
              past commits might have input to your change, so also CC them if you think

            
              they may have feedback.


            * 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.


            * Non-functional changes, i.e. whitespace and reformatting changes, should be

            
              done in separate patches marked as ``cosmetic``. This separation of functional

            
              and cosmetic changes greatly facilitates the review process.


            * Some comments on running :doc:`checkpatch.pl <checkpatch>`:


               * Checkpatch is a tool that can help you find some style problems, but is

            
                 imperfect, and the things it complains about are of varying importance.

            
                 So use common sense in interpreting the results.


               * Warnings that clearly only make sense in the Linux kernel can be ignored.

            
                 This includes ``Use #include <linux/$file> instead of <asm/$file>`` for

            
                 example.


               * If you encounter warnings for existing code, not modified by your patch,

            
                 consider submitting a separate, cosmetic-only patch -- clearly described

            
                 as such -- that *precedes* your substantive patch.


               * For minor modifications (e.g. changed arguments of a function call),

            
                 adhere to the present coding style of the module. Relating checkpatch

            
                 warnings can be ignored in this case. A respective note in the commit or

            
                 cover letter why they are ignored is desired.


            * 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

            
              (``https://source.denx.de/u-boot/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 either ``git send-email`` or the ``git imap-send`` command instead.

            
              If you believe you need to use a mailing list for testing (instead of any

            
              regular mail address you own), we have a special test list for such purposes.

            
              It would be best to subscribe to the list for the duration of your tests to

            
              avoid repeated moderation - see https://lists.denx.de/listinfo/test


            * 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.


            * The start of the subject should be a meaningful tag (arm:, ppc:, tegra:,

            
              net:, ext2:, etc)


            * 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 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.


            Attributing Code, Copyrights, Signing

            
            -------------------------------------


            * Sign your changes, i. e. add a *Signed-off-by:* line to the message body.

            
              This can be automated by using ``git commit -s``. Please see the

            
              :ref:`Developer Certificate of Origin <dco>` section for more details here.


            * If you change or add *significant* parts to a file, then please make sure to

            
              add your copyright to that file, for example like this::


               (C) Copyright 2010  Joe Hacker <jh@hackers.paradise.com>


            	  Please do *not* include a detailed description of your

            
            	  changes. We use the *git* commit messages for this purpose.


            * If you add new files, please always make sure that these contain your

            
              copyright note and a GPLv2+ SPDX-License-Identifier, for example like this::


               (C) Copyright 2010  Joe Hacker <jh@hackers.paradise.com>


               SPDX-License-Identifier:<TAB>GPL-2.0+


            * If you are copying or adapting code from other projects, like the Linux

            
              kernel, or BusyBox, or similar, please make sure to state clearly where you

            
              copied the code from, and provide terse but precise information which exact

            
              version or even commit ID was used. Follow the ideas of this note from the

            
              Linux "SubmittingPatches" document::


               Special note to back-porters: It seems to be a common and useful practice

            
               to insert an indication of the origin of a patch at the top of the commit

            
               message (just after the subject line) to facilitate tracking. For instance,

            
               here's what we see in 2.6-stable :


            	 Date:	Tue May 13 19:10:30 2008 +0000


            		  SCSI: libiscsi regression in 2.6.25: fix nop timer handling


            		  commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream


               And here's what appears in 2.4 :


            	 Date:	Tue May 13 22:12:27 2008 +0200


            		  wireless, airo: waitbusy() won't delay


            		  [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]


            Whatever the format, this information provides a valuable help to people

            
            tracking your trees, and to people trying to trouble-shoot bugs in your

            
            tree.


            Commit 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 <file>" 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 (e.g. it is a trivial spelling

            
              correction or whitespace update), 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``. Please see the

            
              :ref:`Developer Certificate of Origin <dco>` section for more details here.


            * 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.


            Sending updated patch versions

            
            ------------------------------


            It is pretty normal that the first version of a patch you are submitting does

            
            not get accepted as is, and that you are asked to submit another, improved

            
            version.


            When re-posting such a new version of your patch(es), please always make sure

            
            to observe the following rules.


            * Make an appropriate note that this is a re-submission in the subject line,

            
              e.g. "[PATCH v2] Add support for feature X". ``git format-patch

            
              --subject-prefix="PATCH v2"`` can be used in this case (see the example

            
              below).


            * Please make sure to keep a "change log", i.e. a description of what you have

            
              changed compared to previous versions of this patch. This change log should

            
              be added below the "---" line in the patch, which starts the "comment

            
              section", i.e. which contains text that does not get included into the

            
              actual commit message.

            
              Note: it is *not* sufficient to provide a change log in some cover letter

            
              that gets sent as a separate message with the patch series. The reason is

            
              that such cover letters are not as easily reviewed in our `patchwork queue

            
              <http://patchwork.ozlabs.org/project/uboot/list/>`_ so they are not helpful

            
              to any reviewers using this tool. Example::


               From: Joe Hacker <jh@hackers.paradise.com>

            
               Date: Thu, 1 Jan 2222 12:21:22 +0200

            
               Subject: [PATCH 1/2 v3] FOO: add timewarp-support


               This patch adds timewarp-support for the FOO family of processors.


               adapted for the current kernel structures.


               Signed-off-by: Joe Hacker <jh@hackers.paradise.com>

            
               Cc: Tom Maintainer <tm@u-boot.custodians.org>

            
               ---

            
               Changes for v2:

            
               - Coding Style cleanup

            
               - fixed miscalculation of time-space discontinuities

            
               Changes for v3:

            
               - fixed compiler warnings observed with GCC-17.3.5

            
               - worked around integer overflow in warp driver


                arch/foo/cpu/spacetime.c |	 8 +

            
                drivers/warp/Kconfig     |	 7 +

            
                drivers/warp/Makefile    |	42 +++

            
                drivers/warp/warp-core.c | 255 +++++++++++++++++++++++++


            * Make sure that your mailer adds or keeps correct ``In-reply-to:`` and

            
              ``References:`` headers, so threading of messages is working and everybody

            
              can see that the new message refers to some older posting of the same topic.


            Uncommented and un-threaded repostings are extremely annoying and

            
            time-consuming, as we have to try to remember if anything similar has been

            
            posted before, look up the old threads, and then manually compare if anything

            
            has been changed, or what.


            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 <http://kerneltrap.org/Linux/Email_Clients_and_Patches>`_.


            Notes

            
            -----


            1. U-Boot is Free Software that can redistributed and/or modified under the

            
               terms of the `GNU General Public License

            
               <http://www.fsf.org/licensing/licenses/gpl.html>`_ (GPL). Currently (August

            
               2022) version 2 of the GPL applies. Please see :download:`Licensing

            
               <../../Licenses/README>` for details. To allow that later versions of U-Boot

            
               may be released under a later version of the GPL, all new code that gets

            
               added to U-Boot shall use a "GPL-2.0+" SPDX-License-Identifier.


            2. All code must follow the :doc:`codingstyle` requirements.


            3. Before sending the patch, you *must* run some form of local testing.

            
               Submitting a patch that does not build or function correctly is a mistake. For

            
               non-trivial patches, either building a number of platforms locally or making

            
               use of :doc:`ci_testing` is strongly encouraged in order to avoid problems

            
               that can be found when attempting to merge the patch.


            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 follow the guidelines laid out in :doc:`system_configuration`.


            Patch Tracking

            
            --------------


            Like some other projects, U-Boot uses `Patchwork <http://patchwork.ozlabs.org/>`_

            
            to track the state of patches. This is one of the reasons why it is mandatory

            
            to submit all patches to the U-Boot mailing list - only then they will be

            
            picked up by patchwork.


            At http://patchwork.ozlabs.org/project/uboot/list/ you can find the list of

            
            open U-Boot patches. By using the "Filters" link (Note: requires JavaScript)

            
            you can also select other views, for example, to include old patches that have,

            
            for example, already been applied or rejected.


            Note that Patchwork automatically tracks and collects a number of git tags from

            
            follow-up mails, so it is usually better to apply a patch through the Patchwork

            
            commandline interface than just manually applying it from a posting on the

            
            mailing list (in which case you have to do all the tracking and adding of git

            
            tags yourself). This also obviates the need of a developer to resubmit a patch

            
            only in order to collect these tags.


            A Custodian has additional privileges and can:


            * **Delegate** a patch


            * **Change the state** of a patch. The following states exist:


               * New


               * Under Review


               * Accepted


               * Rejected


               * RFC


               * Not Applicable


               * Changes Requested


               * Awaiting Upstream


               * Superseeded


               * Deferred


               * Archived


            Patchwork work-flow

            
            ^^^^^^^^^^^^^^^^^^^


            The following are a "rule of thumb" as to how the states are used in patchwork

            
            today. Not all states are used by all custodians.


            * New: Patch has been submitted to the list, and none of the maintainers has

            
              changed it's state since.


            * Under Review: A custodian is reviewing the patch currently.


            * Accepted: When a patch has been applied to a custodian repository that gets

            
              used for pulling from into upstream, they are put into "accepted" state.


            * Rejected: Rejected means we just don't want to do what the patch does.


            * RFC: The patch is not intended to be applied to any of the mainline

            
              repositories, but merely for discussing or testing some idea or new feature.


            * Not Applicable: The patch either was not intended to be applied, as it was

            
              a debugging or discussion aide that patchwork picked up, or was cross-posted

            
              to our list but intended for another project entirely.


            * Changes Requested: The patch looks mostly OK, but requires some rework before

            
              it will be accepted for mainline.


            * Awaiting Upstream: A custodian may have applied this to the ``next`` branch

            
              and has not merged yet to master, or has queued the patch up to be submitted

            
              to be merged, but has not yet.


            * Superseeded: Patches are marked as 'superseeded' when the poster submits a

            
              new version of these patches.


            * Deferred: Deferred usually means the patch depends on something else that

            
              isn't upstream, such as patches that only apply against some specific other

            
              repository. This is also used when a patch has been in patchwork for over a

            
              year and it is unlikely to be applied as-is.


            * Archived: Archiving puts the patch away somewhere where it doesn't appear in

            
              the normal pages and needs extra effort to get to.


            Apply patches

            
            ^^^^^^^^^^^^^


            To apply a patch from the `patchwork queue

            
            <http://patchwork.ozlabs.org/project/uboot/list/>`_ using ``git``, download the

            
            mbox file and apply it using::


               git am file


            The `openembedded wiki <http://wiki.openembedded.net/>`_ also provides a script

            
            named `pw-am.sh

            
            <http://cgit.openembedded.org/cgit.cgi/openembedded/tree/contrib/patchwork/pw-am.sh>`_

            
            which can be used to fetch an 'mbox' patch from patchwork and git am it::


               usage: pw-am.sh <number>

            
               example: 'pw-am.sh 71002' will get and apply the patch from http://patchwork.ozlabs.org/patch/71002/


            Update the state of patches

            
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^


            You have to register to be able to update the state of patches. You can use the

            
            Web interface, `pwclient`, or `pwparser`.


            pwclient

            
            ^^^^^^^^


            The `pwclient` command line tool can be used for example to retrieve patches,

            
            search the queue or update the state.


            All necessary information for `pwclient` is linked from the bottom of

            
            http://patchwork.ozlabs.org/project/uboot/


            Use::


               pwclient help


            for an overview on how to use it.


            pwparser

            
            ^^^^^^^^


            See http://www.mail-archive.com/patchwork@lists.ozlabs.org/msg00057.html
	.. SPDX-License-Identifier: GPL-2.0+

	Sending patches
	===============

	Before you begin to implement any new ideas or concepts it is always a good
	idea to present your plans on the `U-Boot mailing list
	<https://lists.denx.de/listinfo/u-boot>`_. 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. Being familiar with the :doc:`process` is also important.

	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
	<http://lwn.net/Articles/139918/>`_ as the same rules apply to U-Boot, too.

	Using patman
	------------

	You can use a tool called patman to prepare, check and send patches. It creates
	change logs, cover letters and patch notes. It also simplifies the process of
	sending multiple versions of a series.

	See more details at :doc:`patman`.

	General Patch Submission Rules
	------------------------------

	* All patches must be sent to the `u-boot@lists.denx.de
	<https://lists.denx.de/listinfo/u-boot>`_ mailing list.

	* If your patch affects the code maintained by one of the :ref:`custodians`, CC
	them when emailing your patch. The easiest way to make sure you don't forget
	this even when you resubmit the patch later is to add a ``Cc: name
	<address>`` line after your ``Signed-off-by:`` line (see the example below).

	* Take a look at the commit logs of the files you are modifying. Authors of
	past commits might have input to your change, so also CC them if you think
	they may have feedback.

	* 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.

	* Non-functional changes, i.e. whitespace and reformatting changes, should be
	done in separate patches marked as ``cosmetic``. This separation of functional
	and cosmetic changes greatly facilitates the review process.

	* Some comments on running :doc:`checkpatch.pl <checkpatch>`:

	* Checkpatch is a tool that can help you find some style problems, but is
	imperfect, and the things it complains about are of varying importance.
	So use common sense in interpreting the results.

	* Warnings that clearly only make sense in the Linux kernel can be ignored.
	This includes ``Use #include <linux/$file> instead of <asm/$file>`` for
	example.

	* If you encounter warnings for existing code, not modified by your patch,
	consider submitting a separate, cosmetic-only patch -- clearly described
	as such -- that precedes your substantive patch.

	* For minor modifications (e.g. changed arguments of a function call),
	adhere to the present coding style of the module. Relating checkpatch
	warnings can be ignored in this case. A respective note in the commit or
	cover letter why they are ignored is desired.

	* 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
	(``https://source.denx.de/u-boot/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 either ``git send-email`` or the ``git imap-send`` command instead.
	If you believe you need to use a mailing list for testing (instead of any
	regular mail address you own), we have a special test list for such purposes.
	It would be best to subscribe to the list for the duration of your tests to
	avoid repeated moderation - see https://lists.denx.de/listinfo/test

	* 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.

	* The start of the subject should be a meaningful tag (arm:, ppc:, tegra:,
	net:, ext2:, etc)

	* 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 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.

	Attributing Code, Copyrights, Signing
	-------------------------------------

	* Sign your changes, i. e. add a Signed-off-by: line to the message body.
	This can be automated by using ``git commit -s``. Please see the
	:ref:`Developer Certificate of Origin <dco>` section for more details here.

	* If you change or add significant parts to a file, then please make sure to
	add your copyright to that file, for example like this::

	(C) Copyright 2010 Joe Hacker <jh@hackers.paradise.com>

	Please do not include a detailed description of your
	changes. We use the git commit messages for this purpose.

	* If you add new files, please always make sure that these contain your
	copyright note and a GPLv2+ SPDX-License-Identifier, for example like this::

	(C) Copyright 2010 Joe Hacker <jh@hackers.paradise.com>

	SPDX-License-Identifier:<TAB>GPL-2.0+

	* If you are copying or adapting code from other projects, like the Linux
	kernel, or BusyBox, or similar, please make sure to state clearly where you
	copied the code from, and provide terse but precise information which exact
	version or even commit ID was used. Follow the ideas of this note from the
	Linux "SubmittingPatches" document::

	Special note to back-porters: It seems to be a common and useful practice
	to insert an indication of the origin of a patch at the top of the commit
	message (just after the subject line) to facilitate tracking. For instance,
	here's what we see in 2.6-stable :

	Date: Tue May 13 19:10:30 2008 +0000

	SCSI: libiscsi regression in 2.6.25: fix nop timer handling

	commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream

	And here's what appears in 2.4 :

	Date: Tue May 13 22:12:27 2008 +0200

	wireless, airo: waitbusy() won't delay

	[backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a]

	Whatever the format, this information provides a valuable help to people
	tracking your trees, and to people trying to trouble-shoot bugs in your
	tree.

	Commit 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 <file>" 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 (e.g. it is a trivial spelling
	correction or whitespace update), 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``. Please see the
	:ref:`Developer Certificate of Origin <dco>` section for more details here.

	* 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.

	Sending updated patch versions
	------------------------------

	It is pretty normal that the first version of a patch you are submitting does
	not get accepted as is, and that you are asked to submit another, improved
	version.

	When re-posting such a new version of your patch(es), please always make sure
	to observe the following rules.

	* Make an appropriate note that this is a re-submission in the subject line,
	e.g. "[PATCH v2] Add support for feature X". ``git format-patch
	--subject-prefix="PATCH v2"`` can be used in this case (see the example
	below).

	* Please make sure to keep a "change log", i.e. a description of what you have
	changed compared to previous versions of this patch. This change log should
	be added below the "---" line in the patch, which starts the "comment
	section", i.e. which contains text that does not get included into the
	actual commit message.
	Note: it is not sufficient to provide a change log in some cover letter
	that gets sent as a separate message with the patch series. The reason is
	that such cover letters are not as easily reviewed in our `patchwork queue
	<http://patchwork.ozlabs.org/project/uboot/list/>`_ so they are not helpful
	to any reviewers using this tool. Example::

	From: Joe Hacker <jh@hackers.paradise.com>
	Date: Thu, 1 Jan 2222 12:21:22 +0200
	Subject: [PATCH 1/2 v3] FOO: add timewarp-support

	This patch adds timewarp-support for the FOO family of processors.

	adapted for the current kernel structures.

	Signed-off-by: Joe Hacker <jh@hackers.paradise.com>
	Cc: Tom Maintainer <tm@u-boot.custodians.org>
	---
	Changes for v2:
	- Coding Style cleanup
	- fixed miscalculation of time-space discontinuities
	Changes for v3:
	- fixed compiler warnings observed with GCC-17.3.5
	- worked around integer overflow in warp driver

	arch/foo/cpu/spacetime.c \| 8 +
	drivers/warp/Kconfig \| 7 +
	drivers/warp/Makefile \| 42 +++
	drivers/warp/warp-core.c \| 255 +++++++++++++++++++++++++

	* Make sure that your mailer adds or keeps correct ``In-reply-to:`` and
	``References:`` headers, so threading of messages is working and everybody
	can see that the new message refers to some older posting of the same topic.

	Uncommented and un-threaded repostings are extremely annoying and
	time-consuming, as we have to try to remember if anything similar has been
	posted before, look up the old threads, and then manually compare if anything
	has been changed, or what.

	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 <http://kerneltrap.org/Linux/Email_Clients_and_Patches>`_.

	Notes
	-----

	1. U-Boot is Free Software that can redistributed and/or modified under the
	terms of the `GNU General Public License
	<http://www.fsf.org/licensing/licenses/gpl.html>`_ (GPL). Currently (August
	2022) version 2 of the GPL applies. Please see :download:`Licensing
	<../../Licenses/README>` for details. To allow that later versions of U-Boot
	may be released under a later version of the GPL, all new code that gets
	added to U-Boot shall use a "GPL-2.0+" SPDX-License-Identifier.

	2. All code must follow the :doc:`codingstyle` requirements.

	3. Before sending the patch, you must run some form of local testing.
	Submitting a patch that does not build or function correctly is a mistake. For
	non-trivial patches, either building a number of platforms locally or making
	use of :doc:`ci_testing` is strongly encouraged in order to avoid problems
	that can be found when attempting to merge the patch.

	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 follow the guidelines laid out in :doc:`system_configuration`.

	Patch Tracking
	--------------

	Like some other projects, U-Boot uses `Patchwork <http://patchwork.ozlabs.org/>`_
	to track the state of patches. This is one of the reasons why it is mandatory
	to submit all patches to the U-Boot mailing list - only then they will be
	picked up by patchwork.

	At http://patchwork.ozlabs.org/project/uboot/list/ you can find the list of
	open U-Boot patches. By using the "Filters" link (Note: requires JavaScript)
	you can also select other views, for example, to include old patches that have,
	for example, already been applied or rejected.

	Note that Patchwork automatically tracks and collects a number of git tags from
	follow-up mails, so it is usually better to apply a patch through the Patchwork
	commandline interface than just manually applying it from a posting on the
	mailing list (in which case you have to do all the tracking and adding of git
	tags yourself). This also obviates the need of a developer to resubmit a patch
	only in order to collect these tags.

	A Custodian has additional privileges and can:

	* Delegate a patch

	* Change the state of a patch. The following states exist:

	* New

	* Under Review

	* Accepted

	* Rejected

	* RFC

	* Not Applicable

	* Changes Requested

	* Awaiting Upstream

	* Superseeded

	* Deferred

	* Archived

	Patchwork work-flow
	^^^^^^^^^^^^^^^^^^^

	The following are a "rule of thumb" as to how the states are used in patchwork
	today. Not all states are used by all custodians.

	* New: Patch has been submitted to the list, and none of the maintainers has
	changed it's state since.

	* Under Review: A custodian is reviewing the patch currently.

	* Accepted: When a patch has been applied to a custodian repository that gets
	used for pulling from into upstream, they are put into "accepted" state.

	* Rejected: Rejected means we just don't want to do what the patch does.

	* RFC: The patch is not intended to be applied to any of the mainline
	repositories, but merely for discussing or testing some idea or new feature.

	* Not Applicable: The patch either was not intended to be applied, as it was
	a debugging or discussion aide that patchwork picked up, or was cross-posted
	to our list but intended for another project entirely.

	* Changes Requested: The patch looks mostly OK, but requires some rework before
	it will be accepted for mainline.

	* Awaiting Upstream: A custodian may have applied this to the ``next`` branch
	and has not merged yet to master, or has queued the patch up to be submitted
	to be merged, but has not yet.

	* Superseeded: Patches are marked as 'superseeded' when the poster submits a
	new version of these patches.

	* Deferred: Deferred usually means the patch depends on something else that
	isn't upstream, such as patches that only apply against some specific other
	repository. This is also used when a patch has been in patchwork for over a
	year and it is unlikely to be applied as-is.

	* Archived: Archiving puts the patch away somewhere where it doesn't appear in
	the normal pages and needs extra effort to get to.

	Apply patches
	^^^^^^^^^^^^^

	To apply a patch from the `patchwork queue
	<http://patchwork.ozlabs.org/project/uboot/list/>`_ using ``git``, download the
	mbox file and apply it using::

	git am file

	The `openembedded wiki <http://wiki.openembedded.net/>`_ also provides a script
	named `pw-am.sh
	<http://cgit.openembedded.org/cgit.cgi/openembedded/tree/contrib/patchwork/pw-am.sh>`_
	which can be used to fetch an 'mbox' patch from patchwork and git am it::

	usage: pw-am.sh <number>
	example: 'pw-am.sh 71002' will get and apply the patch from http://patchwork.ozlabs.org/patch/71002/

	Update the state of patches
	^^^^^^^^^^^^^^^^^^^^^^^^^^^

	You have to register to be able to update the state of patches. You can use the
	Web interface, `pwclient`, or `pwparser`.

	pwclient
	^^^^^^^^

	The `pwclient` command line tool can be used for example to retrieve patches,
	search the queue or update the state.

	All necessary information for `pwclient` is linked from the bottom of
	http://patchwork.ozlabs.org/project/uboot/

	Use::

	pwclient help

	for an overview on how to use it.

	pwparser
	^^^^^^^^

	See http://www.mail-archive.com/patchwork@lists.ozlabs.org/msg00057.html