Simon Glass | 37c42b7 | 2022-08-09 13:49:57 -0600 | [diff] [blame] | 1 | .. SPDX-License-Identifier: GPL-2.0+ |
| 2 | |
| 3 | Sending patches |
| 4 | =============== |
| 5 | |
Tom Rini | 6349b18 | 2022-08-29 12:59:33 -0400 | [diff] [blame^] | 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. |
Simon Glass | 37c42b7 | 2022-08-09 13:49:57 -0600 | [diff] [blame] | 15 | |
Tom Rini | 6349b18 | 2022-08-29 12:59:33 -0400 | [diff] [blame^] | 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. |
Simon Glass | 37c42b7 | 2022-08-09 13:49:57 -0600 | [diff] [blame] | 19 | |
Tom Rini | 6349b18 | 2022-08-29 12:59:33 -0400 | [diff] [blame^] | 20 | Using patman |
| 21 | ------------ |
Simon Glass | 37c42b7 | 2022-08-09 13:49:57 -0600 | [diff] [blame] | 22 | |
| 23 | You can use a tool called patman to prepare, check and sent patches. It creates |
| 24 | change logs, cover letters and patch notes. It also simplified the process of |
| 25 | sending multiple versions of a series. |
| 26 | |
| 27 | See more details at :doc:`patman`. |
Tom Rini | 6349b18 | 2022-08-29 12:59:33 -0400 | [diff] [blame^] | 28 | |
| 29 | General Patch Submission Rules |
| 30 | ------------------------------ |
| 31 | |
| 32 | * All patches must be sent to the `u-boot@lists.denx.de |
| 33 | <https://lists.denx.de/listinfo/u-boot>`_ mailing list. |
| 34 | |
| 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). |
| 39 | |
| 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. |
| 43 | |
| 44 | * Patches should always contain exactly one complete logical change, i. e. |
| 45 | |
| 46 | * Changes that contain different, unrelated modifications shall be submitted |
| 47 | as *separate* patches, one patch per changeset. |
| 48 | |
| 49 | * If one logical set of modifications affects or creates several files, all |
| 50 | these changes shall be submitted in a *single* patch. |
| 51 | |
| 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. |
| 55 | |
| 56 | * Some comments on running ``checkpatch.pl``: |
| 57 | |
| 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. |
| 61 | |
| 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 |
| 64 | example. |
| 65 | |
| 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. |
| 69 | |
| 70 | * For minor modifications (e.g. changed arguments of a function call), |
| 71 | adhere to the present codingstyle 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. |
| 74 | |
| 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. |
| 82 | |
| 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 |
| 91 | |
| 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. |
| 95 | |
| 96 | * The start of the subject should be a meaningfull tag (arm:, ppc:, tegra:, |
| 97 | net:, ext2:, etc) |
| 98 | |
| 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 |
| 101 | do this. |
| 102 | |
| 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 |
| 107 | example:: |
| 108 | |
| 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 |
| 114 | |
| 115 | * In the message body, include a description of your changes. |
| 116 | |
| 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 |
| 119 | something. |
| 120 | |
| 121 | * For new features: a description of the feature and your implementation. |
| 122 | |
| 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. |
| 125 | |
| 126 | * If your description gets too long, that's a strong indication that you should |
| 127 | split up your patch. |
| 128 | |
| 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. |
| 132 | |
| 133 | Attributing Code, Copyrights, Signing |
| 134 | ------------------------------------- |
| 135 | |
| 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``. |
| 138 | |
| 139 | * If you change or add *significant* parts to a file, then please make sure to |
| 140 | add your copyright to that file, for example like this:: |
| 141 | |
| 142 | (C) Copyright 2010 Joe Hacker <jh@hackers.paradise.com> |
| 143 | |
| 144 | Please do *not* include a detailed description of your |
| 145 | changes. We use the *git* commit messages for this purpose. |
| 146 | |
| 147 | * If you add new files, please always make sure that these contain your |
| 148 | copyright note and a GPLv2+ SPDX-License-Identifier, for example like this:: |
| 149 | |
| 150 | (C) Copyright 2010 Joe Hacker <jh@hackers.paradise.com> |
| 151 | |
| 152 | SPDX-License-Identifier:<TAB>GPL-2.0+ |
| 153 | |
| 154 | * If you are copying or adapting code from other projects, like the Linux |
| 155 | kernel, or BusyBox, or similar, please make sure to state clearly where you |
| 156 | copied the code from, and provide terse but precise information which exact |
| 157 | version or even commit ID was used. Follow the ideas of this note from the |
| 158 | Linux "SubmittingPatches" document:: |
| 159 | |
| 160 | Special note to back-porters: It seems to be a common and useful practice |
| 161 | to insert an indication of the origin of a patch at the top of the commit |
| 162 | message (just after the subject line) to facilitate tracking. For instance, |
| 163 | here's what we see in 2.6-stable : |
| 164 | |
| 165 | Date: Tue May 13 19:10:30 2008 +0000 |
| 166 | |
| 167 | SCSI: libiscsi regression in 2.6.25: fix nop timer handling |
| 168 | |
| 169 | commit 4cf1043593db6a337f10e006c23c69e5fc93e722 upstream |
| 170 | |
| 171 | And here's what appears in 2.4 : |
| 172 | |
| 173 | Date: Tue May 13 22:12:27 2008 +0200 |
| 174 | |
| 175 | wireless, airo: waitbusy() won't delay |
| 176 | |
| 177 | [backport of 2.6 commit b7acbdfbd1f277c1eb23f344f899cfa4cd0bf36a] |
| 178 | |
| 179 | Whatever the format, this information provides a valuable help to people |
| 180 | tracking your trees, and to people trying to trouble-shoot bugs in your |
| 181 | tree. |
| 182 | |
| 183 | Commit message conventions |
| 184 | -------------------------- |
| 185 | |
| 186 | Please adhere to the following conventions when writing your commit |
| 187 | log messages. |
| 188 | |
| 189 | * The first line of the log message is the summary line. Keep this less than 70 |
| 190 | characters long. |
| 191 | |
| 192 | * Don't use periods to end the summary line (e.g., don't do "Add support for |
| 193 | X.") |
| 194 | |
| 195 | * Use the present tense in your summary line (e.g., "Add support for X" rather |
| 196 | than "Added support for X"). Furthermore, use the present tense in your log |
| 197 | message to describe what the patch is doing. This isn't a strict rule -- it's |
| 198 | OK to use the past tense for describing things that were happening in the old |
| 199 | code for example. |
| 200 | |
| 201 | * Use the imperative tense in your summary line (e.g., "Add support for X" |
| 202 | rather than "Adds support for X"). In general, you can think of the summary |
| 203 | line as "this commit is meant to 'Add support for X'" |
| 204 | |
| 205 | * If applicable, prefix the summary line with a word describing what area of |
| 206 | code is being affected followed by a colon. This is a standard adopted by |
| 207 | both U-Boot and Linux. For example, if your change affects all mpc85xx |
| 208 | boards, prefix your summary line with "mpc85xx:". If your change affects the |
| 209 | PCI common code, prefix your summary line with "pci:". The best thing to do |
| 210 | is look at the "git log <file>" output to see what others have done so you |
| 211 | don't break conventions. |
| 212 | |
| 213 | * Insert a blank line after the summary line |
| 214 | |
| 215 | * For bug fixes, it's good practice to briefly describe how things behaved |
| 216 | before this commit |
| 217 | |
| 218 | * Put a detailed description after the summary and blank line. If the summary |
| 219 | line is sufficient to describe the change (e.g. it is a trivial spelling |
| 220 | correction or whitespace update), you can omit the blank line and detailed |
| 221 | description. |
| 222 | |
| 223 | * End your log message with S.O.B. (Signed-off-by) line. This is done |
| 224 | automatically when you use ``git commit -s``. |
| 225 | |
| 226 | * Keep EVERY line under 72 characters. That is, your message should be |
| 227 | line-wrapped with line-feeds. However, don't get carried away and wrap it too |
| 228 | short either since this also looks funny. |
| 229 | |
| 230 | * Detail level: The audience of the commit log message that you should cater to |
| 231 | is those familiar with the underlying source code you are modifying, but who |
| 232 | are _not_ familiar with the patch you are submitting. They should be able to |
| 233 | determine what is being changed and why. Avoid excessive low-level detail. |
| 234 | Before submitting, re-read your commit log message with this audience in mind |
| 235 | and adjust as needed. |
| 236 | |
| 237 | Sending updated patch versions |
| 238 | ------------------------------ |
| 239 | |
| 240 | It is pretty normal that the first version of a patch you are submitting does |
| 241 | not get accepted as is, and that you are asked to submit another, improved |
| 242 | version. |
| 243 | |
| 244 | When re-posting such a new version of your patch(es), please always make sure |
| 245 | to observe the following rules. |
| 246 | |
| 247 | * Make an appropriate note that this is a re-submission in the subject line, |
| 248 | eg. "[PATCH v2] Add support for feature X". ``git format-patch |
| 249 | --subject-prefix="PATCH v2"`` can be used in this case (see the example |
| 250 | below). |
| 251 | |
| 252 | * Please make sure to keep a "change log", i. e. a description of what you have |
| 253 | changed compared to previous versions of this patch. This change log should |
| 254 | be added below the "---" line in the patch, which starts the "comment |
| 255 | section", i. e. which contains text that does not get included into the |
| 256 | actual commit message. |
| 257 | Note: it is *not* sufficient to provide a change log in some cover letter |
| 258 | that gets sent as a separate message with the patch series. The reason is |
| 259 | that such cover letters are not as easily reviewed in our `patchwork queue |
| 260 | <http://patchwork.ozlabs.org/project/uboot/list/>`_ so they are not helpful |
| 261 | to any reviewers using this tool. Example:: |
| 262 | |
| 263 | From: Joe Hacker <jh@hackers.paradise.com> |
| 264 | Date: Thu, 1 Jan 2222 12:21:22 +0200 |
| 265 | Subject: [PATCH 1/2 v3] FOO: add timewarp-support |
| 266 | |
| 267 | This patch adds timewarp-support for the FOO family of processors. |
| 268 | |
| 269 | adapted for the current kernel structures. |
| 270 | |
| 271 | Signed-off-by: Joe Hacker <jh@hackers.paradise.com> |
| 272 | Cc: Tom Maintainer <tm@u-boot.custodians.org> |
| 273 | --- |
| 274 | Changes for v2: |
| 275 | - Coding Style cleanup |
| 276 | - fixed miscalculation of time-space discontinuities |
| 277 | Changes for v3: |
| 278 | - fixed compiler warnings observed with GCC-17.3.5 |
| 279 | - worked around integer overflow in warp driver |
| 280 | |
| 281 | arch/foo/cpu/spacetime.c | 8 + |
| 282 | drivers/warp/Kconfig | 7 + |
| 283 | drivers/warp/Makefile | 42 +++ |
| 284 | drivers/warp/warp-core.c | 255 +++++++++++++++++++++++++ |
| 285 | |
| 286 | * Make sure that your mailer adds or keeps correct ``In-reply-to:`` and |
| 287 | ``References:`` headers, so threading of messages is working and everybody |
| 288 | can see that the new message refers to some older posting of the same topic. |
| 289 | |
| 290 | Uncommented and un-threaded repostings are extremely annoying and |
| 291 | time-consuming, as we have to try to remember if anything similar has been |
| 292 | posted before, look up the old threads, and then manually compare if anything |
| 293 | has been changed, or what. |
| 294 | |
| 295 | If you have problems with your e-mail client, for example because it mangles |
| 296 | white space or wraps long lines, then please read this article about `Email |
| 297 | Clients and Patches <http://kerneltrap.org/Linux/Email_Clients_and_Patches>`_. |
| 298 | |
| 299 | Notes |
| 300 | ----- |
| 301 | |
| 302 | 1. U-Boot is Free Software that can redistributed and/or modified under the |
| 303 | terms of the `GNU General Public License |
| 304 | <http://www.fsf.org/licensing/licenses/gpl.html>`_ (GPL). Currently (July |
| 305 | 2009) version 2 of the GPL applies. Please see :download:`Licensing |
| 306 | <../../Licenses/README>` for details. To allow that later versions of U-Boot |
| 307 | may be released under a later version of the GPL, all new code that gets |
| 308 | added to U-Boot shall use a "GPL-2.0+" SPDX-License-Identifier. |
| 309 | |
| 310 | 2. All code must follow the :doc:`codingstyle` requirements. |
| 311 | |
| 312 | 3. Before sending the patch, you *must* run the ``MAKEALL`` script on your |
| 313 | patched source tree and make sure that no errors or warnings are reported |
| 314 | for any of the boards. Well, at least not any more warnings than without |
| 315 | your patch. It is *strongly* recommended to verify that out-of-tree |
| 316 | building (with ``-O`` _make_ option resp. ``BUILD_DIR`` environment |
| 317 | variable) is still working. For example, run ``BUILD_DIR=/tmp/u-boot-build ./MAKEALL``. |
| 318 | Please also run ``MAKEALL`` for *at least one other architecture* than the one |
| 319 | you made your modifications in. |
| 320 | |
| 321 | 4. If you modify existing code, make sure that your new code does not add to |
| 322 | the memory footprint of the code. Remember: Small is beautiful! When adding |
| 323 | new features, these should compile conditionally only (using the |
| 324 | configuration system resp. #ifdef), and the resulting code with the new |
| 325 | feature disabled must not need more memory than the old code without your |
| 326 | modification. |
| 327 | |
| 328 | Patch Tracking |
| 329 | -------------- |
| 330 | |
| 331 | Like some other project U-Boot uses `Patchwork <http://patchwork.ozlabs.org/>`_ |
| 332 | to track the state of patches. This is one of the reasons why it is mandatory |
| 333 | to submit all patches to the U-Boot mailing list - only then they will be |
| 334 | picked up by patchwork. |
| 335 | |
| 336 | At http://patchwork.ozlabs.org/project/uboot/list/ you can find the list of |
| 337 | open U-Boot patches. By using the "Filters" link (Note: requires JavaScript) |
| 338 | you can also select other views, for example, to include old patches that have, |
| 339 | for example, already been applied or rejected. |
| 340 | |
| 341 | A Custodian has additional privileges and can: |
| 342 | |
| 343 | * **Delegate** a patch |
| 344 | |
| 345 | * **Change the state** of a patch. The following states exist: |
| 346 | |
| 347 | * New |
| 348 | |
| 349 | * Under Review |
| 350 | |
| 351 | * Accepted |
| 352 | |
| 353 | * Rejected |
| 354 | |
| 355 | * RFC |
| 356 | |
| 357 | * Not Applicable |
| 358 | |
| 359 | * Changes Requested |
| 360 | |
| 361 | * Awaiting Upstream |
| 362 | |
| 363 | * Superseeded |
| 364 | |
| 365 | * Deferred |
| 366 | |
| 367 | * Archived |
| 368 | |
| 369 | Patchwork work-flow |
| 370 | ^^^^^^^^^^^^^^^^^^^ |
| 371 | |
| 372 | At the moment we are in the process of defining our work-flow with |
| 373 | Patchwork, so I try to summarize what the states and state changes |
| 374 | mean; most of this information is based on this `mail thread |
| 375 | <http://old.nabble.com/patchwork-states-and-workflow-td19579954.html>`_. |
| 376 | |
| 377 | * New: Patch has been submitted to the list, and none of the maintainers has |
| 378 | changed it's state since. |
| 379 | |
| 380 | * Under Review: |
| 381 | |
| 382 | * Accepted: When a patch has been applied to a custodian repository that gets |
| 383 | used for pulling from into upstream, they are put into "accepted" state. |
| 384 | |
| 385 | * Rejected: Rejected means we just don't want to do what the patch does. |
| 386 | |
| 387 | * RFC: The patch is not intended to be applied to any of the mainline |
| 388 | repositories, but merely for discussing or testing some idea or new feature. |
| 389 | |
| 390 | * Not Applicable: The patch does not apply cleanly against the current U-Boot |
| 391 | repository, most probably because it was made against a much older version of |
| 392 | U-Boot, or because the submitter's mailer mangled it (for example by |
| 393 | converting TABs into SPACEs, or by breaking long lines). |
| 394 | |
| 395 | * Changes Requested: The patch looks mostly OK, but requires some rework before |
| 396 | it will be accepted for mainline. |
| 397 | |
| 398 | * Awaiting Upstream: |
| 399 | |
| 400 | * Superseeded: Patches are marked as 'superseeded' when the poster submits a |
| 401 | new version of these patches. |
| 402 | |
| 403 | * Deferred: Deferred usually means the patch depends on something else that |
| 404 | isn't upstream, such as patches that only apply against some specific other |
| 405 | repository. |
| 406 | |
| 407 | * Archived: Archiving puts the patch away somewhere where it doesn't appear in |
| 408 | the normal pages and needs extra effort to get to. |
| 409 | |
| 410 | We also can put patches in a "bundle". I don't know yet if that has any deeper |
| 411 | sense but to mark them to be handled together, like a patch series that |
| 412 | logically belongs together. |
| 413 | |
| 414 | Apply patches |
| 415 | ^^^^^^^^^^^^^ |
| 416 | |
| 417 | To apply a patch from the `patchwork queue |
| 418 | <http://patchwork.ozlabs.org/project/uboot/list/>`_ using ``git``, download the |
| 419 | mbox file and apply it using:: |
| 420 | |
| 421 | git am file |
| 422 | |
| 423 | The `openembedded wiki <http://wiki.openembedded.net/>`_ also provides a script |
| 424 | named `pw-am.sh |
| 425 | <http://cgit.openembedded.org/cgit.cgi/openembedded/tree/contrib/patchwork/pw-am.sh>`_ |
| 426 | which can be used to fetch an 'mbox' patch from patchwork and git am it:: |
| 427 | |
| 428 | usage: pw-am.sh <number> |
| 429 | example: 'pw-am.sh 71002' will get and apply the patch from http://patchwork.ozlabs.org/patch/71002/ |
| 430 | |
| 431 | Update the state of patches |
| 432 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 433 | |
| 434 | You have to register to be able to update the state of patches. You can use the |
| 435 | Web interface, `pwclient`, or `pwparser`. |
| 436 | |
| 437 | pwclient |
| 438 | ^^^^^^^^ |
| 439 | |
| 440 | The `pwclient` command line tool can be used for example to retrieve patches, |
| 441 | search the queue or update the state. |
| 442 | |
| 443 | All necessary information for `pwclient` is linked from the bottom of |
| 444 | http://patchwork.ozlabs.org/project/uboot/ |
| 445 | |
| 446 | Use:: |
| 447 | |
| 448 | pwclient help |
| 449 | |
| 450 | for an overview on how to use it. |
| 451 | |
| 452 | pwparser |
| 453 | ^^^^^^^^ |
| 454 | |
| 455 | See http://www.mail-archive.com/patchwork@lists.ozlabs.org/msg00057.html |
| 456 | |
| 457 | Review Process, Git Tags |
| 458 | ------------------------ |
| 459 | |
| 460 | There are a number of *git tags* that are used to document the origin |
| 461 | and the processing of patches on their way into the mainline U-Boot |
| 462 | code. The following is an attempt to document how these are usually |
| 463 | handled in the U-Boot project. In general, we try to follow the |
| 464 | established procedures from other projects, especially the Linux |
| 465 | kernel, but there may be smaller differences. For reference, see |
| 466 | the Linux kernel's `Submitting patches <https://www.kernel.org/doc/html/latest/process/submitting-patches.html>`_ document. |
| 467 | |
| 468 | * Signed-off-by: the *Signed-off-by:* is a line at the end of the commit |
| 469 | message by which the signer certifies that he was involved in the development |
| 470 | of the patch and that he accepts the `Developer Certificate of Origin |
| 471 | <https://developercertificate.org/>`_. In U-Boot, we typically do not add a |
| 472 | *Signed-off-by:* if we just pass on a patch without any changes. |
| 473 | |
| 474 | * Reviewed-by: The patch has been reviewed and found acceptible according to |
| 475 | the `Reveiwer's statement of oversight |
| 476 | <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#reviewer-s-statement-of-oversight>`_. |
| 477 | A *Reviewed-by:* tag is a statement of opinion that the patch is an |
| 478 | appropriate modification of the code without any remaining serious technical |
| 479 | issues. Any interested reviewer (who has done the work) can offer a |
| 480 | *Reviewed-by:* tag for a patch. |
| 481 | |
| 482 | * Acked-by: If a person was not directly involved in the preparation or |
| 483 | handling of a patch but wishes to signify and record their approval of it |
| 484 | then they can arrange to have an *Acked-by:* line added to the patch's |
| 485 | changelog. |
| 486 | |
| 487 | * Tested-by: A *Tested-by:* tag indicates that the patch has been successfully |
| 488 | tested (in some environment) by the person named. Andrew Morton: "I think |
| 489 | it's very useful information to have. For a start, it tells you who has the |
| 490 | hardware and knows how to build a kernel. So if you're making a change to a |
| 491 | driver and want it tested, you can troll the file's changelog looking for |
| 492 | people who might be able to help." |
| 493 | |
| 494 | * Reported-by: If this patch fixes a problem reported by somebody else, |
| 495 | consider adding a *Reported-by:* tag to credit the reporter for their |
| 496 | contribution. Please note that this tag should not be added without the |
| 497 | reporter's permission, especially if the problem was not reported in a public |
| 498 | forum. |
| 499 | |
| 500 | * Cc: If a person should have the opportunity to comment on a patch, you may |
| 501 | optionally add a *Cc:* tag to the patch. Git tools (git send-email) will then |
| 502 | automatically arrange that he receives a copy of the patch when you submit it |
| 503 | to the mainling list. This is the only tag which might be added without an |
| 504 | explicit action by the person it names. This tag documents that potentially |
| 505 | interested parties have been included in the discussion. |
| 506 | For example, when your change affects a specific board or driver, then makes |
| 507 | a lot of sense to put the respective maintainer of this code on Cc: |
| 508 | |
| 509 | Note that Patchwork automatically tracks and collects such git tags |
| 510 | from follow-up mails, so it is usually better to apply a patch through |
| 511 | the Patchwork commandline interface than just manually applying it |
| 512 | from a posting on the mailing list (in which case you have to do all |
| 513 | the tracking and adding of git tags yourself). |