1.. SPDX-License-Identifier: CC-BY-SA-2.0-UK 2 3Contributing Changes to a Component 4************************************ 5 6Contributions to the Yocto Project and OpenEmbedded are very welcome. 7Because the system is extremely configurable and flexible, we recognize 8that developers will want to extend, configure or optimize it for their 9specific uses. 10 11.. _ref-why-mailing-lists: 12 13Contributing through mailing lists --- Why not using web-based workflows? 14========================================================================= 15 16Both Yocto Project and OpenEmbedded have many key components that are 17maintained by patches being submitted on mailing lists. We appreciate this 18approach does look a little old fashioned when other workflows are available 19through web technology such as GitHub, GitLab and others. Since we are often 20asked this question, we’ve decided to document the reasons for using mailing 21lists. 22 23One significant factor is that we value peer review. When a change is proposed 24to many of the core pieces of the project, it helps to have many eyes of review 25go over them. Whilst there is ultimately one maintainer who needs to make the 26final call on accepting or rejecting a patch, the review is made by many eyes 27and the exact people reviewing it are likely unknown to the maintainer. It is 28often the surprise reviewer that catches the most interesting issues! 29 30This is in contrast to the "GitHub" style workflow where either just a 31maintainer makes that review, or review is specifically requested from 32nominated people. We believe there is significant value added to the codebase 33by this peer review and that moving away from mailing lists would be to the 34detriment of our code. 35 36We also need to acknowledge that many of our developers are used to this 37mailing list workflow and have worked with it for years, with tools and 38processes built around it. Changing away from this would result in a loss 39of key people from the project, which would again be to its detriment. 40 41The projects are acutely aware that potential new contributors find the 42mailing list approach off-putting and would prefer a web-based GUI. 43Since we don’t believe that can work for us, the project is aiming to ensure 44`patchwork <https://patchwork.yoctoproject.org/>`__ is available to help track 45patch status and also looking at how tooling can provide more feedback to users 46about patch status. We are looking at improving tools such as ``patchtest`` to 47test user contributions before they hit the mailing lists and also at better 48documenting how to use such workflows since we recognise that whilst this was 49common knowledge a decade ago, it might not be as familiar now. 50 51Preparing Changes for Submission 52================================ 53 54Set up Git 55---------- 56 57The first thing to do is to install Git packages. Here is an example 58on Debian and Ubuntu:: 59 60 sudo apt install git-core git-email 61 62Then, you need to set a name and e-mail address that Git will 63use to identify your commits:: 64 65 git config --global user.name "Ada Lovelace" 66 git config --global user.email "ada.lovelace@gmail.com" 67 68By default, Git adds a signature line at the end of patches containing the Git 69version. We suggest to remove it as it doesn't add useful information. 70 71Remove it with the following command:: 72 73 git config --global format.signature "" 74 75Clone the Git repository for the component to modify 76---------------------------------------------------- 77 78After identifying the component to modify as described in the 79":doc:`../contributor-guide/identify-component`" section, clone the 80corresponding Git repository. Here is an example for OpenEmbedded-Core:: 81 82 git clone https://git.openembedded.org/openembedded-core 83 cd openembedded-core 84 85Create a new branch 86------------------- 87 88Then, create a new branch in your local Git repository 89for your changes, starting from the reference branch in the upstream 90repository (often called ``master``):: 91 92 $ git checkout <ref-branch> 93 $ git checkout -b my-changes 94 95If you have completely unrelated sets of changes to submit, you should even 96create one branch for each set. 97 98Implement and commit changes 99---------------------------- 100 101In each branch, you should group your changes into small, controlled and 102isolated ones. Keeping changes small and isolated aids review, makes 103merging/rebasing easier and keeps the change history clean should anyone need 104to refer to it in future. 105 106To this purpose, you should create *one Git commit per change*, 107corresponding to each of the patches you will eventually submit. 108See `further guidance <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#separate-your-changes>`__ 109in the Linux kernel documentation if needed. 110 111For example, when you intend to add multiple new recipes, each recipe 112should be added in a separate commit. For upgrades to existing recipes, 113the previous version should usually be deleted as part of the same commit 114to add the upgraded version. 115 116#. *Stage Your Changes:* Stage your changes by using the ``git add`` 117 command on each file you modified. If you want to stage all the 118 files you modified, you can even use the ``git add -A`` command. 119 120#. *Commit Your Changes:* This is when you can create separate commits. For 121 each commit to create, use the ``git commit -s`` command with the files 122 or directories you want to include in the commit:: 123 124 $ git commit -s file1 file2 dir1 dir2 ... 125 126 To include **a**\ ll staged files:: 127 128 $ git commit -sa 129 130 - The ``-s`` option of ``git commit`` adds a "Signed-off-by:" line 131 to your commit message. There is the same requirement for contributing 132 to the Linux kernel. Adding such a line signifies that you, the 133 submitter, have agreed to the `Developer's Certificate of Origin 1.1 134 <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#sign-your-work-the-developer-s-certificate-of-origin>`__ 135 as follows: 136 137 .. code-block:: none 138 139 Developer's Certificate of Origin 1.1 140 141 By making a contribution to this project, I certify that: 142 143 (a) The contribution was created in whole or in part by me and I 144 have the right to submit it under the open source license 145 indicated in the file; or 146 147 (b) The contribution is based upon previous work that, to the best 148 of my knowledge, is covered under an appropriate open source 149 license and I have the right under that license to submit that 150 work with modifications, whether created in whole or in part 151 by me, under the same open source license (unless I am 152 permitted to submit under a different license), as indicated 153 in the file; or 154 155 (c) The contribution was provided directly to me by some other 156 person who certified (a), (b) or (c) and I have not modified 157 it. 158 159 (d) I understand and agree that this project and the contribution 160 are public and that a record of the contribution (including all 161 personal information I submit with it, including my sign-off) is 162 maintained indefinitely and may be redistributed consistent with 163 this project or the open source license(s) involved. 164 165 - Provide a single-line summary of the change and, if more 166 explanation is needed, provide more detail in the body of the 167 commit. This summary is typically viewable in the "shortlist" of 168 changes. Thus, providing something short and descriptive that 169 gives the reader a summary of the change is useful when viewing a 170 list of many commits. You should prefix this short description 171 with the recipe name (if changing a recipe), or else with the 172 short form path to the file being changed. 173 174 .. note:: 175 176 To find a suitable prefix for the commit summary, a good idea 177 is to look for prefixes used in previous commits touching the 178 same files or directories:: 179 180 git log --oneline <paths> 181 182 - For the body of the commit message, provide detailed information 183 that describes what you changed, why you made the change, and the 184 approach you used. It might also be helpful if you mention how you 185 tested the change. Provide as much detail as you can in the body 186 of the commit message. 187 188 .. note:: 189 190 If the single line summary is enough to describe a simple 191 change, the body of the commit message can be left empty. 192 193 - If the change addresses a specific bug or issue that is associated 194 with a bug-tracking ID, include a reference to that ID in your 195 detailed description. For example, the Yocto Project uses a 196 specific convention for bug references --- any commit that addresses 197 a specific bug should use the following form for the detailed 198 description. Be sure to use the actual bug-tracking ID from 199 Bugzilla for bug-id:: 200 201 Fixes [YOCTO #bug-id] 202 203 detailed description of change 204 205#. *Crediting contributors:* By using the ``git commit --amend`` command, 206 you can add some tags to the commit description to credit other contributors 207 to the change: 208 209 - ``Reported-by``: name and email of a person reporting a bug 210 that your commit is trying to fix. This is a good practice 211 to encourage people to go on reporting bugs and let them 212 know that their reports are taken into account. 213 214 - ``Suggested-by``: name and email of a person to credit for the 215 idea of making the change. 216 217 - ``Tested-by``, ``Reviewed-by``: name and email for people having 218 tested your changes or reviewed their code. These fields are 219 usually added by the maintainer accepting a patch, or by 220 yourself if you submitted your patches to early reviewers, 221 or are submitting an unmodified patch again as part of a 222 new iteration of your patch series. 223 224 - ``CC:`` Name and email of people you want to send a copy 225 of your changes to. This field will be used by ``git send-email``. 226 227 See `more guidance about using such tags 228 <https://www.kernel.org/doc/html/latest/process/submitting-patches.html#using-reported-by-tested-by-reviewed-by-suggested-by-and-fixes>`__ 229 in the Linux kernel documentation. 230 231Test your changes 232----------------- 233 234For each contributions you make, you should test your changes as well. 235For this the Yocto Project offers several types of tests. Those tests cover 236different areas and it depends on your changes which are feasible. For example run: 237 238 - For changes that affect the build environment: 239 240 - ``bitbake-selftest``: for changes within BitBake 241 242 - ``oe-selftest``: to test combinations of BitBake runs 243 244 - ``oe-build-perf-test``: to test the performance of common build scenarios 245 246 - For changes in a recipe: 247 248 - ``ptest``: run package specific tests, if they exist 249 250 - ``testimage``: build an image, boot it and run testcases on it 251 252 - If applicable, ensure also the ``native`` and ``nativesdk`` variants builds 253 254 - For changes relating to the SDK: 255 256 - ``testsdk``: to build, install and run tests against a SDK 257 258 - ``testsdk_ext``: to build, install and run tests against an extended SDK 259 260Note that this list just gives suggestions and is not exhaustive. More details can 261be found here: :ref:`test-manual/intro:Yocto Project Tests --- Types of Testing Overview`. 262 263Creating Patches 264================ 265 266Here is the general procedure on how to create patches to be sent through email: 267 268#. *Describe the Changes in your Branch:* If you have more than one commit 269 in your branch, it's recommended to provide a cover letter describing 270 the series of patches you are about to send. 271 272 For this purpose, a good solution is to store the cover letter contents 273 in the branch itself:: 274 275 git branch --edit-description 276 277 This will open a text editor to fill in the description for your 278 changes. This description can be updated when necessary and will 279 be used by Git to create the cover letter together with the patches. 280 281 It is recommended to start this description with a title line which 282 will serve a the subject line for the cover letter. 283 284#. *Generate Patches for your Branch:* The ``git format-patch`` command will 285 generate patch files for each of the commits in your branch. You need 286 to pass the reference branch your branch starts from. 287 288 If you branch didn't need a description in the previous step:: 289 290 $ git format-patch <ref-branch> 291 292 If you filled a description for your branch, you will want to generate 293 a cover letter too:: 294 295 $ git format-patch --cover-letter --cover-from-description=auto <ref-branch> 296 297 After the command is run, the current directory contains numbered 298 ``.patch`` files for the commits in your branch. If you have a cover 299 letter, it will be in the ``0000-cover-letter.patch``. 300 301 .. note:: 302 303 The ``--cover-from-description=auto`` option makes ``git format-patch`` 304 use the first paragraph of the branch description as the cover 305 letter title. Another possibility, which is easier to remember, is to pass 306 only the ``--cover-letter`` option, but you will have to edit the 307 subject line manually every time you generate the patches. 308 309 See the `git format-patch manual page <https://git-scm.com/docs/git-format-patch>`__ 310 for details. 311 312#. *Review each of the Patch Files:* This final review of the patches 313 before sending them often allows to view your changes from a different 314 perspective and discover defects such as typos, spacing issues or lines 315 or even files that you didn't intend to modify. This review should 316 include the cover letter patch too. 317 318 If necessary, rework your commits as described in 319 ":ref:`contributor-guide/submit-changes:taking patch review into account`". 320 321Validating Patches with Patchtest 322================================= 323 324``patchtest`` is available in ``openembedded-core`` as a tool for making 325sure that your patches are well-formatted and contain important info for 326maintenance purposes, such as ``Signed-off-by`` and ``Upstream-Status`` 327tags. Note that no functional testing of the changes will be performed by ``patchtest``. 328Currently, it only supports testing patches for ``openembedded-core`` branches. 329To setup, perform the following:: 330 331 pip install -r meta/lib/patchtest/requirements.txt 332 source oe-init-build-env 333 bitbake-layers add-layer ../meta-selftest 334 335Once these steps are complete and you have generated your patch files, 336you can run ``patchtest`` like so:: 337 338 patchtest --patch <patch_name> 339 340Alternatively, if you want ``patchtest`` to iterate over and test 341multiple patches stored in a directory, you can use:: 342 343 patchtest --directory <directory_name> 344 345By default, ``patchtest`` uses its own modules' file paths to determine what 346repository and test suite to check patches against. If you wish to test 347patches against a repository other than ``openembedded-core`` and/or use 348a different set of tests, you can use the ``--repodir`` and ``--testdir`` 349flags:: 350 351 patchtest --patch <patch_name> --repodir <path/to/repo> --testdir <path/to/testdir> 352 353Finally, note that ``patchtest`` is designed to test patches in a standalone 354way, so if your patches are meant to apply on top of changes made by 355previous patches in a series, it is possible that ``patchtest`` will report 356false failures regarding the "merge on head" test. 357 358Using ``patchtest`` in this manner provides a final check for the overall 359quality of your changes before they are submitted for review by the 360maintainers. 361 362Sending the Patches via Email 363============================= 364 365Using Git to Send Patches 366------------------------- 367 368To submit patches through email, it is very important that you send them 369without any whitespace or HTML formatting that either you or your mailer 370introduces. The maintainer that receives your patches needs to be able 371to save and apply them directly from your emails, using the ``git am`` 372command. 373 374Using the ``git send-email`` command is the only error-proof way of sending 375your patches using email since there is no risk of compromising whitespace 376in the body of the message, which can occur when you use your own mail 377client. It will also properly include your patches as *inline attachments*, 378which is not easy to do with standard e-mail clients without breaking lines. 379If you used your regular e-mail client and shared your patches as regular 380attachments, reviewers wouldn't be able to quote specific sections of your 381changes and make comments about them. 382 383Setting up Git to Send Email 384---------------------------- 385 386The ``git send-email`` command can send email by using a local or remote 387Mail Transport Agent (MTA) such as ``msmtp``, ``sendmail``, or 388through a direct SMTP configuration in your Git ``~/.gitconfig`` file. 389 390Here are the settings for letting ``git send-email`` send e-mail through your 391regular STMP server, using a Google Mail account as an example:: 392 393 git config --global sendemail.smtpserver smtp.gmail.com 394 git config --global sendemail.smtpserverport 587 395 git config --global sendemail.smtpencryption tls 396 git config --global sendemail.smtpuser ada.lovelace@gmail.com 397 git config --global sendemail.smtppass = XXXXXXXX 398 399These settings will appear in the ``.gitconfig`` file in your home directory. 400 401If you neither can use a local MTA nor SMTP, make sure you use an email client 402that does not touch the message (turning spaces in tabs, wrapping lines, etc.). 403A good mail client to do so is Pine (or Alpine) or Mutt. For more 404information about suitable clients, see `Email clients info for Linux 405<https://www.kernel.org/doc/html/latest/process/email-clients.html>`__ 406in the Linux kernel sources. 407 408If you use such clients, just include the patch in the body of your email. 409 410Finding a Suitable Mailing List 411------------------------------- 412 413You should send patches to the appropriate mailing list so that they can be 414reviewed by the right contributors and merged by the appropriate maintainer. 415The specific mailing list you need to use depends on the location of the code 416you are changing. 417 418If people have concerns with any of the patches, they will usually voice 419their concern over the mailing list. If patches do not receive any negative 420reviews, the maintainer of the affected layer typically takes them, tests them, 421and then based on successful testing, merges them. 422 423In general, each component (e.g. layer) should have a ``README`` file 424that indicates where to send the changes and which process to follow. 425 426The "poky" repository, which is the Yocto Project's reference build 427environment, is a hybrid repository that contains several individual 428pieces (e.g. BitBake, Metadata, documentation, and so forth) built using 429the combo-layer tool. The upstream location used for submitting changes 430varies by component: 431 432- *Core Metadata:* Send your patches to the 433 :oe_lists:`openembedded-core </g/openembedded-core>` 434 mailing list. For example, a change to anything under the ``meta`` or 435 ``scripts`` directories should be sent to this mailing list. 436 437- *BitBake:* For changes to BitBake (i.e. anything under the 438 ``bitbake`` directory), send your patches to the 439 :oe_lists:`bitbake-devel </g/bitbake-devel>` 440 mailing list. 441 442- *meta-poky* and *meta-yocto-bsp* trees: These trees contain Metadata. Use the 443 :yocto_lists:`poky </g/poky>` mailing list. 444 445- *Documentation*: For changes to the Yocto Project documentation, use the 446 :yocto_lists:`docs </g/docs>` mailing list. 447 448For changes to other layers and tools hosted in the Yocto Project source 449repositories (i.e. :yocto_git:`git.yoctoproject.org <>`), use the 450:yocto_lists:`yocto-patches </g/yocto-patches/>` general mailing list. 451 452For changes to other layers hosted in the OpenEmbedded source 453repositories (i.e. :oe_git:`git.openembedded.org <>`), use 454the :oe_lists:`openembedded-devel </g/openembedded-devel>` 455mailing list, unless specified otherwise in the layer's ``README`` file. 456 457If you intend to submit a new recipe that neither fits into the core Metadata, 458nor into :oe_git:`meta-openembedded </meta-openembedded/>`, you should 459look for a suitable layer in https://layers.openembedded.org. If similar 460recipes can be expected, you may consider :ref:`dev-manual/layers:creating your own layer`. 461 462If in doubt, please ask on the :yocto_lists:`yocto </g/yocto/>` general mailing list 463or on the :oe_lists:`openembedded-devel </g/openembedded-devel>` mailing list. 464 465Subscribing to the Mailing List 466------------------------------- 467 468After identifying the right mailing list to use, you will have to subscribe to 469it if you haven't done it yet. 470 471If you attempt to send patches to a list you haven't subscribed to, your email 472will be returned as undelivered. 473 474However, if you don't want to be receive all the messages sent to a mailing list, 475you can set your subscription to "no email". You will still be a subscriber able 476to send messages, but you won't receive any e-mail. If people reply to your message, 477their e-mail clients will default to including your email address in the 478conversation anyway. 479 480Anyway, you'll also be able to access the new messages on mailing list archives, 481either through a web browser, or for the lists archived on https://lore.kernel.org, 482through an individual newsgroup feed or a git repository. 483 484Sending Patches via Email 485------------------------- 486 487At this stage, you are ready to send your patches via email. Here's the 488typical usage of ``git send-email``:: 489 490 git send-email --to <mailing-list-address> *.patch 491 492Then, review each subject line and list of recipients carefully, and then 493allow the command to send each message. 494 495You will see that ``git send-email`` will automatically copy the people listed 496in any commit tags such as ``Signed-off-by`` or ``Reported-by``. 497 498In case you are sending patches for :oe_git:`meta-openembedded </meta-openembedded/>` 499or any layer other than :oe_git:`openembedded-core </openembedded-core/>`, 500please add the appropriate prefix so that it is clear which layer the patch is intended 501to be applied to:: 502 503 git format-patch --subject-prefix="meta-oe][PATCH" ... 504 505.. note:: 506 507 It is actually possible to send patches without generating them 508 first. However, make sure you have reviewed your changes carefully 509 because ``git send-email`` will just show you the title lines of 510 each patch. 511 512 Here's a command you can use if you just have one patch in your 513 branch:: 514 515 git send-email --to <mailing-list-address> -1 516 517 If you have multiple patches and a cover letter, you can send 518 patches for all the commits between the reference branch 519 and the tip of your branch:: 520 521 git send-email --cover-letter --cover-from-description=auto --to <mailing-list-address> -M <ref-branch> 522 523See the `git send-email manual page <https://git-scm.com/docs/git-send-email>`__ 524for details. 525 526Troubleshooting Email Issues 527---------------------------- 528 529Fixing your From identity 530~~~~~~~~~~~~~~~~~~~~~~~~~ 531 532We have a frequent issue with contributors whose patches are received through 533a ``From`` field which doesn't match the ``Signed-off-by`` information. Here is 534a typical example for people sending from a domain name with :wikipedia:`DMARC`:: 535 536 From: "Linus Torvalds via lists.openembedded.org <linus.torvalds=kernel.org@lists.openembedded.org>" 537 538This ``From`` field is used by ``git am`` to recreate commits with the right 539author name. The following will ensure that your e-mails have an additional 540``From`` field at the beginning of the Email body, and therefore that 541maintainers accepting your patches don't have to fix commit author information 542manually:: 543 544 git config --global sendemail.from "linus.torvalds@kernel.org" 545 546The ``sendemail.from`` should match your ``user.email`` setting, 547which appears in the ``Signed-off-by`` line of your commits. 548 549Streamlining git send-email usage 550--------------------------------- 551 552If you want to save time and not be forced to remember the right options to use 553with ``git send-email``, you can use Git configuration settings. 554 555- To set the right mailing list address for a given repository:: 556 557 git config --local sendemail.to openembedded-devel@lists.openembedded.org 558 559- If the mailing list requires a subject prefix for the layer 560 (this only works when the repository only contains one layer):: 561 562 git config --local format.subjectprefix "meta-something][PATCH" 563 564Using Scripts to Push a Change Upstream and Request a Pull 565========================================================== 566 567For larger patch series it is preferable to send a pull request which not 568only includes the patch but also a pointer to a branch that can be pulled 569from. This involves making a local branch for your changes, pushing this 570branch to an accessible repository and then using the ``create-pull-request`` 571and ``send-pull-request`` scripts from openembedded-core to create and send a 572patch series with a link to the branch for review. 573 574Follow this procedure to push a change to an upstream "contrib" Git 575repository once the steps in 576":ref:`contributor-guide/submit-changes:preparing changes for submission`" 577have been followed: 578 579.. note:: 580 581 You can find general Git information on how to push a change upstream 582 in the 583 `Git Community Book <https://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows>`__. 584 585#. *Request Push Access to an "Upstream" Contrib Repository:* Send an email to 586 ``helpdesk@yoctoproject.org``: 587 588 - Attach your SSH public key which usually named ``id_rsa.pub.``. 589 If you don't have one generate it by running ``ssh-keygen -t rsa -b 4096 -C "your_email@example.com"``. 590 591 - List the repositories you're planning to contribute to. 592 593 - Include your preferred branch prefix for ``-contrib`` repositories. 594 595#. *Push Your Commits to the "Contrib" Upstream:* Push your 596 changes to that repository:: 597 598 $ git push upstream_remote_repo local_branch_name 599 600 For example, suppose you have permissions to push 601 into the upstream ``meta-intel-contrib`` repository and you are 602 working in a local branch named `your_name`\ ``/README``. The following 603 command pushes your local commits to the ``meta-intel-contrib`` 604 upstream repository and puts the commit in a branch named 605 `your_name`\ ``/README``:: 606 607 $ git push meta-intel-contrib your_name/README 608 609#. *Determine Who to Notify:* Determine the maintainer or the mailing 610 list that you need to notify for the change. 611 612 Before submitting any change, you need to be sure who the maintainer 613 is or what mailing list that you need to notify. Use either these 614 methods to find out: 615 616 - *Maintenance File:* Examine the ``maintainers.inc`` file, which is 617 located in the :term:`Source Directory` at 618 ``meta/conf/distro/include``, to see who is responsible for code. 619 620 - *Search by File:* Using :ref:`overview-manual/development-environment:git`, you can 621 enter the following command to bring up a short list of all 622 commits against a specific file:: 623 624 git shortlog -- filename 625 626 Just provide the name of the file for which you are interested. The 627 information returned is not ordered by history but does include a 628 list of everyone who has committed grouped by name. From the list, 629 you can see who is responsible for the bulk of the changes against 630 the file. 631 632 - *Find the Mailing List to Use:* See the 633 ":ref:`contributor-guide/submit-changes:finding a suitable mailing list`" 634 section above. 635 636#. *Make a Pull Request:* Notify the maintainer or the mailing list that 637 you have pushed a change by making a pull request. 638 639 The Yocto Project provides two scripts that conveniently let you 640 generate and send pull requests to the Yocto Project. These scripts 641 are ``create-pull-request`` and ``send-pull-request``. You can find 642 these scripts in the ``scripts`` directory within the 643 :term:`Source Directory` (e.g. 644 ``poky/scripts``). 645 646 Using these scripts correctly formats the requests without 647 introducing any whitespace or HTML formatting. The maintainer that 648 receives your patches either directly or through the mailing list 649 needs to be able to save and apply them directly from your emails. 650 Using these scripts is the preferred method for sending patches. 651 652 First, create the pull request. For example, the following command 653 runs the script, specifies the upstream repository in the contrib 654 directory into which you pushed the change, and provides a subject 655 line in the created patch files:: 656 657 $ poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README" 658 659 Running this script forms ``*.patch`` files in a folder named 660 ``pull-``\ `PID` in the current directory. One of the patch files is a 661 cover letter. 662 663 Before running the ``send-pull-request`` script, you must edit the 664 cover letter patch to insert information about your change. After 665 editing the cover letter, send the pull request. For example, the 666 following command runs the script and specifies the patch directory 667 and email address. In this example, the email address is a mailing 668 list:: 669 670 $ poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@lists.yoctoproject.org 671 672 You need to follow the prompts as the script is interactive. 673 674 .. note:: 675 676 For help on using these scripts, simply provide the ``-h`` 677 argument as follows:: 678 679 $ poky/scripts/create-pull-request -h 680 $ poky/scripts/send-pull-request -h 681 682Submitting Changes to Stable Release Branches 683============================================= 684 685The process for proposing changes to a Yocto Project stable branch differs 686from the steps described above. Changes to a stable branch must address 687identified bugs or CVEs and should be made carefully in order to avoid the 688risk of introducing new bugs or breaking backwards compatibility. Typically 689bug fixes must already be accepted into the master branch before they can be 690backported to a stable branch unless the bug in question does not affect the 691master branch or the fix on the master branch is unsuitable for backporting. 692 693The list of stable branches along with the status and maintainer for each 694branch can be obtained from the 695:yocto_wiki:`Releases wiki page </Releases>`. 696 697.. note:: 698 699 Changes will not typically be accepted for branches which are marked as 700 End-Of-Life (EOL). 701 702With this in mind, the steps to submit a change for a stable branch are as 703follows: 704 705#. *Identify the bug or CVE to be fixed:* This information should be 706 collected so that it can be included in your submission. 707 708 See :ref:`dev-manual/vulnerabilities:checking for vulnerabilities` 709 for details about CVE tracking. 710 711#. *Check if the fix is already present in the master branch:* This will 712 result in the most straightforward path into the stable branch for the 713 fix. 714 715 #. *If the fix is present in the master branch --- submit a backport request 716 by email:* You should send an email to the relevant stable branch 717 maintainer and the mailing list with details of the bug or CVE to be 718 fixed, the commit hash on the master branch that fixes the issue and 719 the stable branches which you would like this fix to be backported to. 720 721 #. *If the fix is not present in the master branch --- submit the fix to the 722 master branch first:* This will ensure that the fix passes through the 723 project's usual patch review and test processes before being accepted. 724 It will also ensure that bugs are not left unresolved in the master 725 branch itself. Once the fix is accepted in the master branch a backport 726 request can be submitted as above. 727 728 #. *If the fix is unsuitable for the master branch --- submit a patch 729 directly for the stable branch:* This method should be considered as a 730 last resort. It is typically necessary when the master branch is using 731 a newer version of the software which includes an upstream fix for the 732 issue or when the issue has been fixed on the master branch in a way 733 that introduces backwards incompatible changes. In this case follow the 734 steps in ":ref:`contributor-guide/submit-changes:preparing changes for submission`" 735 and in the following sections but modify the subject header of your patch 736 email to include the name of the stable branch which you are 737 targetting. This can be done using the ``--subject-prefix`` argument to 738 ``git format-patch``, for example to submit a patch to the 739 "&DISTRO_NAME_NO_CAP_MINUS_ONE;" branch use:: 740 741 git format-patch --subject-prefix='&DISTRO_NAME_NO_CAP_MINUS_ONE;][PATCH' ... 742 743Taking Patch Review into Account 744================================ 745 746You may get feedback on your submitted patches from other community members 747or from the automated patchtest service. If issues are identified in your 748patches then it is usually necessary to address these before the patches are 749accepted into the project. In this case you should your commits according 750to the feedback and submit an updated version to the relevant mailing list. 751 752In any case, never fix reported issues by fixing them in new commits 753on the tip of your branch. Always come up with a new series of commits 754without the reported issues. 755 756.. note:: 757 758 It is a good idea to send a copy to the reviewers who provided feedback 759 to the previous version of the patch. You can make sure this happens 760 by adding a ``CC`` tag to the commit description:: 761 762 CC: William Shakespeare <bill@yoctoproject.org> 763 764A single patch can be amended using ``git commit --amend``, and multiple 765patches can be easily reworked and reordered through an interactive Git rebase:: 766 767 git rebase -i <ref-branch> 768 769See `this tutorial <https://hackernoon.com/beginners-guide-to-interactive-rebasing-346a3f9c3a6d>`__ 770for practical guidance about using Git interactive rebasing. 771 772You should also modify the ``[PATCH]`` tag in the email subject line when 773sending the revised patch to mark the new iteration as ``[PATCH v2]``, 774``[PATCH v3]``, etc as appropriate. This can be done by passing the ``-v`` 775argument to ``git format-patch`` with a version number:: 776 777 git format-patch -v2 <ref-branch> 778 779Lastly please ensure that you also test your revised changes. In particular 780please don't just edit the patch file written out by ``git format-patch`` and 781resend it. 782 783Tracking the Status of Patches 784============================== 785 786The Yocto Project uses a `Patchwork instance <https://patchwork.yoctoproject.org/>`__ 787to track the status of patches submitted to the various mailing lists and to 788support automated patch testing. Each submitted patch is checked for common 789mistakes and deviations from the expected patch format and submitters are 790notified by ``patchtest`` if such mistakes are found. This process helps to 791reduce the burden of patch review on maintainers. 792 793.. note:: 794 795 This system is imperfect and changes can sometimes get lost in the flow. 796 Asking about the status of a patch or change is reasonable if the change 797 has been idle for a while with no feedback. 798 799If your patches have not had any feedback in a few days, they may have already 800been merged. You can run ``git pull`` branch to check this. Note that many if 801not most layer maintainers do not send out acknowledgement emails when they 802accept patches. Alternatively, if there is no response or merge after a few days 803the patch may have been missed or the appropriate reviewers may not currently be 804around. It is then perfectly fine to reply to it yourself with a reminder asking 805for feedback. 806 807.. note:: 808 809 Patch reviews for feature and recipe upgrade patches are likely be delayed 810 during a feature freeze because these types of patches aren't merged during 811 at that time --- you may have to wait until after the freeze is lifted. 812 813Maintainers also commonly use ``-next`` branches to test submissions prior to 814merging patches. Thus, you can get an idea of the status of a patch based on 815whether the patch has been merged into one of these branches. The commonly 816used testing branches for OpenEmbedded-Core are as follows: 817 818- *openembedded-core "master-next" branch:* This branch is part of the 819 :oe_git:`openembedded-core </openembedded-core/>` repository and contains 820 proposed changes to the core metadata. 821 822- *poky "master-next" branch:* This branch is part of the 823 :yocto_git:`poky </poky/>` repository and combines proposed 824 changes to BitBake, the core metadata and the poky distro. 825 826Similarly, stable branches maintained by the project may have corresponding 827``-next`` branches which collect proposed changes. For example, 828``&DISTRO_NAME_NO_CAP;-next`` and ``&DISTRO_NAME_NO_CAP_MINUS_ONE;-next`` 829branches in both the "openembdedded-core" and "poky" repositories. 830 831Other layers may have similar testing branches but there is no formal 832requirement or standard for these so please check the documentation for the 833layers you are contributing to. 834 835