summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
Diffstat
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml576
1 files changed, 299 insertions, 277 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 179a62d95a..1bb82b711d 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -444,189 +444,180 @@
444 444
445 <para> 445 <para>
446 Contributions to the Yocto Project and OpenEmbedded are very welcome. 446 Contributions to the Yocto Project and OpenEmbedded are very welcome.
447 Because the system is extremely configurable and flexible, we recognize that developers 447 Because the system is extremely configurable and flexible, we recognize
448 will want to extend, configure or optimize it for their specific uses. 448 that developers will want to extend, configure or optimize it for
449 their specific uses.
450 </para>
451
452 <para>
453 The Yocto Project uses a mailing list and a patch-based workflow
454 that is similar to the Linux kernel but contains important
455 differences.
456 In general, a mailing list exists through which you can submit
457 patches.
449 You should send patches to the appropriate mailing list so that they 458 You should send patches to the appropriate mailing list so that they
450 can be reviewed and merged by the appropriate maintainer. 459 can be reviewed and merged by the appropriate maintainer.
460 The specific mailing list you need to use depends on the
461 location of the code you are changing.
462 Each component (e.g. layer) should have a
463 <filename>README</filename> file that indicates where to send
464 the changes and which process to follow.
451 </para> 465 </para>
452 466
453 <section id='submit-change-overview'> 467 <para>
454 <title>Overview</title> 468 You can send the patch to the mailing list using whichever approach
469 you feel comfortable with to generate the patch.
470 Once sent, the patch is usually reviewed by the community at large.
471 If somebody has concerns with the patch, they will usually voice
472 their concern over the mailing list.
473 If a patch does not receive any negative reviews, the maintainer of
474 the affected layer typically takes the patch, tests it, and then
475 based on successful testing, merges the patch.
476 </para>
455 477
456 <para> 478 <para id='figuring-out-the-mailing-list-to-use'>
457 The Yocto Project uses a mailing list and patch-based workflow 479 The "poky" repository, which is the Yocto Project's reference build
458 that is similar to the Linux kernel but contains important 480 environment, is a hybrid repository that contains several
459 differences. 481 individual pieces (e.g. BitBake, OpenEmbedded-Core, meta-yocto,
460 In general, a mailing list exists through which you can submit 482 documentation, and so forth) built using the combo-layer tool.
461 patches. 483 The upstream location used for submitting changes varies by
462 The specific mailing list you need to use depends on the 484 component:
463 location of the code you are changing. 485 <itemizedlist>
464 Each component (e.g. layer) should have a 486 <listitem><para>
465 <filename>README</filename> file that indicates where to send 487 <emphasis>Core Metadata:</emphasis>
466 the changes and which process to follow. 488 Send your patch to the
467 </para> 489 <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
490 mailing list. For example, a change to anything under
491 the <filename>meta</filename> or
492 <filename>scripts</filename> directories should be sent
493 to this mailing list.
494 </para></listitem>
495 <listitem><para>
496 <emphasis>BitBake:</emphasis>
497 For changes to BitBake (i.e. anything under the
498 <filename>bitbake</filename> directory), send your patch
499 to the
500 <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
501 mailing list.
502 </para></listitem>
503 <listitem><para>
504 <emphasis>"meta-yocto-bsp" and "meta-poky" trees:</emphasis>
505 These trees are
506 part of the "meta-yocto" repository in the Yocto Project
507 source repositories.
508 Use the
509 <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
510 mailing list.
511 </para></listitem>
512 </itemizedlist>
513 </para>
468 514
469 <para> 515 <para>
470 You can send the patch to the mailing list using whichever approach 516 For changes to other layers hosted in the Yocto Project source
471 you feel comfortable with to generate the patch. 517 repositories (i.e. <filename>yoctoproject.org</filename>), tools,
472 Once sent, the patch is usually reviewed by the community at large. 518 and the Yocto Project documentation, use the
473 If somebody has concerns with the patch, they will usually voice 519 <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
474 their concern over the mailing list. 520 general mailing list.
475 If a patch does not receive any negative reviews, the maintainer of 521 <note>
476 the affected layer typically takes the patch, tests it, and then 522 Sometimes a layer's documentation specifies to use a
477 based on successful testing, merges the patch. 523 particular mailing list.
478 </para> 524 If so, use that list.
525 </note>
526 For additional recipes that do not fit into the core Metadata, you
527 should determine which layer the recipe should go into and submit
528 the change in the manner recommended by the documentation (e.g.
529 the <filename>README</filename> file) supplied with the layer.
530 If in doubt, please ask on the Yocto general mailing list or on
531 the openembedded-devel mailing list.
532 </para>
479 533
480 <para> 534 <para>
481 Specific to OpenEmbedded-Core, two commonly used testing trees 535 You can also push a change upstream and request a maintainer to
482 exist: 536 pull the change into the component's upstream repository.
483 <itemizedlist> 537 You do this by pushing to a contribution repository that is upstream.
484 <listitem><para> 538 See the
485 <emphasis>"ross/mut" branch:</emphasis> 539 "<ulink url='&YOCTO_DOCS_REF_URL;#workflows'>Workflows</ulink>"
486 The "mut" (master-under-test) tree 540 section in the Yocto Project Reference Manual for additional
487 exists in the <filename>poky-contrib</filename> repository 541 concepts on working in the Yocto Project development environment.
488 in the 542 </para>
489 <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
490 </para></listitem>
491 <listitem><para>
492 <emphasis>"master-next" branch:</emphasis>
493 This branch is part of the main
494 "poky" repository in the Yocto Project source repositories.
495 </para></listitem>
496 </itemizedlist>
497 Maintainers use these branches to test submissions prior to merging
498 patches.
499 Thus, you can get an idea of the status of a patch based on
500 whether the patch has been merged into one of these branches.
501 </para>
502 543
503 <para> 544 <para>
504 This system is imperfect and patches can sometimes get lost in the 545 Two commonly used testing repositories exist for
546 OpenEmbedded-Core:
547 <itemizedlist>
548 <listitem><para>
549 <emphasis>"ross/mut" branch:</emphasis>
550 The "mut" (master-under-test) tree
551 exists in the <filename>poky-contrib</filename> repository
552 in the
553 <ulink url='&YOCTO_GIT_URL;'>Yocto Project source repositories</ulink>.
554 </para></listitem>
555 <listitem><para>
556 <emphasis>"master-next" branch:</emphasis>
557 This branch is part of the main
558 "poky" repository in the Yocto Project source repositories.
559 </para></listitem>
560 </itemizedlist>
561 Maintainers use these branches to test submissions prior to merging
562 patches.
563 Thus, you can get an idea of the status of a patch based on
564 whether the patch has been merged into one of these branches.
565 <note>
566 This system is imperfect and changes can sometimes get lost in the
505 flow. 567 flow.
506 Asking about the status of a patch is reasonable if the patch 568 Asking about the status of a patch or change is reasonable if the
507 has been idle for a while with no feedback. 569 change has been idle for a while with no feedback.
508 The Yocto Project does have plans to use 570 The Yocto Project does have plans to use
509 <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink> 571 <ulink url='https://en.wikipedia.org/wiki/Patchwork_(software)'>Patchwork</ulink>
510 to track the status of patches and also to automatically preview 572 to track the status of patches and also to automatically preview
511 patches. 573 patches.
512 </para> 574 </note>
513 575 </para>
514 <para>
515 The following sections provide general instructions for both
516 pushing changes upstream and for submitting changes as patches.
517 </para>
518 </section>
519
520 <section id='submit-change-submissions-to-poky'>
521 <title>Submissions to Poky</title>
522 576
523 <para> 577 <para>
524 The "poky" repository, which is the Yocto Project's reference build 578 The following sections provide procedures for submitting a change.
525 environment, is a hybrid repository that contains several 579 </para>
526 individual pieces (e.g. BitBake, OpenEmbedded-Core, meta-yocto,
527 documentation, and so forth) built using the combo-layer tool.
528 The upstream location used for submitting changes varies by
529 component:
530 <itemizedlist>
531 <listitem><para>
532 <emphasis>Core Metadata:</emphasis>
533 Send your patch to the
534 <ulink url='http://lists.openembedded.org/mailman/listinfo/openembedded-core'>openembedded-core</ulink>
535 mailing list. For example, a change to anything under
536 the <filename>meta</filename> or
537 <filename>scripts</filename> directories should be sent
538 to this mailing list.
539 </para></listitem>
540 <listitem><para>
541 <emphasis>BitBake:</emphasis>
542 For changes to BitBake (i.e. anything under the
543 <filename>bitbake</filename> directory), send your patch
544 to the
545 <ulink url='http://lists.openembedded.org/mailman/listinfo/bitbake-devel'>bitbake-devel</ulink>
546 mailing list.
547 </para></listitem>
548 <listitem><para>
549 <emphasis>"meta-yocto-bsp" and "meta-poky" trees:</emphasis>
550 These trees are
551 part of the "meta-yocto" repository in the Yocto Project
552 source repositories.
553 Use the
554 <ulink url='https://lists.yoctoproject.org/listinfo/poky'>poky</ulink>
555 mailing list.
556 </para></listitem>
557 </itemizedlist>
558 </para>
559 </section>
560 580
561 <section id='submit-change-submissions-to-other-layers'> 581 <section id='pushing-a-change-upstream'>
562 <title>Submissions to Other Layers</title> 582 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
563 583
564 <para> 584 <para>
565 For changes to other layers hosted in the Yocto Project source 585 Follow this procedure to push a change to an upstream "contrib"
566 repositories (i.e. <filename>yoctoproject.org</filename>), tools, 586 Git repository:
567 and the Yocto Project documentation, use the
568 <ulink url='https://lists.yoctoproject.org/listinfo/yocto'>Yocto Project</ulink>
569 general mailing list.
570 <note> 587 <note>
571 Sometimes a layer's documentation specifies to use a 588 You can find general Git information on how to push a change
572 particular mailing list. 589 upstream in the
573 If so, use that list. 590 <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
574 </note> 591 </note>
575 For additional recipes that do not fit into the core Metadata, you 592 <orderedlist>
576 should determine which layer the recipe should go into and submit
577 the change in the manner recommended by the documentation (e.g.
578 the <filename>README</filename> file) supplied with the layer.
579 If in doubt, please ask on the Yocto general mailing list or on
580 the openembedded-devel mailing list.
581 </para>
582 </section>
583
584 <section id='submit-change-patch-submission-details'>
585 <title>Patch Submission Details</title>
586
587 <para>
588 When submitting any change, you can check who you should be
589 notifying.
590 Use either of these methods to find out:
591 <itemizedlist>
592 <listitem><para> 593 <listitem><para>
593 <emphasis>Maintenance File:</emphasis> 594 <emphasis>Make Your Changes Locally:</emphasis>
594 Examine the <filename>maintainers.inc</filename> file, which is 595 Make your changes in your local Git repository.
595 located in the 596 You should make small, controlled, isolated changes.
596 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink> 597 Keeping changes small and isolated aids review,
597 at <filename>meta-poky/conf/distro/include</filename>, to 598 makes merging/rebasing easier and keeps the change
598 see who is responsible for code. 599 history clean should anyone need to refer to it in
600 future.
599 </para></listitem> 601 </para></listitem>
600 <listitem><para> 602 <listitem><para>
601 <emphasis>Search by File:</emphasis> 603 <emphasis>Stage Your Changes:</emphasis>
602 Using <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>, you can enter the 604 Stage your changes by using the <filename>git add</filename>
603 following command to bring up a short list of all commits 605 command on each file you changed.
604 against a specific file:
605 <literallayout class='monospaced'>
606 git shortlog -- <replaceable>filename</replaceable>
607 </literallayout>
608 Just provide the name of the file for which you are interested.
609 The information returned is not ordered by history but does
610 include a list of everyone who has committed grouped by
611 name.
612 From the list, you can see who is responsible for the bulk of
613 the changes against the file.
614 </para></listitem> 606 </para></listitem>
615 </itemizedlist> 607 <listitem><para id='making-sure-you-have-correct-commit-information'>
616 </para> 608 <emphasis>Commit Your Changes:</emphasis>
617 609 Commit the change by using the
618 <para> 610 <filename>git commit</filename> command.
619 For a list of the Yocto Project and related mailing lists, see the 611 Make sure your commit information follows standards by
620 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" 612 following these accepted conventions:
621 section in the Yocto Project Reference Manual. 613 <itemizedlist>
622 </para> 614 <listitem><para>
623 615 Be sure to include a "Signed-off-by:" line in the
624 <para> 616 same style as required by the Linux kernel.
625 When you send a patch, be sure to include a "Signed-off-by:" 617 Adding this line signifies that you, the submitter,
626 line in the same style as required by the Linux kernel. 618 have agreed to the Developer's Certificate of
627 Adding this line signifies that you, the submitter, have agreed 619 Origin 1.1 as follows:
628 to the Developer's Certificate of Origin 1.1 as follows: 620 <literallayout class='monospaced'>
629 <literallayout class='monospaced'>
630 Developer's Certificate of Origin 1.1 621 Developer's Certificate of Origin 1.1
631 622
632 By making a contribution to this project, I certify that: 623 By making a contribution to this project, I certify that:
@@ -652,121 +643,133 @@
652 personal information I submit with it, including my sign-off) is 643 personal information I submit with it, including my sign-off) is
653 maintained indefinitely and may be redistributed consistent with 644 maintained indefinitely and may be redistributed consistent with
654 this project or the open source license(s) involved. 645 this project or the open source license(s) involved.
655 </literallayout> 646 </literallayout>
656 </para> 647 </para></listitem>
657 648 <listitem><para>
658 <para> 649 Provide a single-line summary of the change.
659 In a collaborative environment, it is necessary to have some sort 650 and,
660 of standard or method through which you submit changes. 651 if more explanation is needed, provide more
661 Otherwise, things could get quite chaotic. 652 detail in the body of the commit.
662 One general practice to follow is to make small, controlled changes. 653 This summary is typically viewable in the
663 Keeping changes small and isolated aids review, makes 654 "shortlist" of changes.
664 merging/rebasing easier and keeps the change history clean should 655 Thus, providing something short and descriptive
665 anyone need to refer to it in future. 656 that gives the reader a summary of the change is
666 </para> 657 useful when viewing a list of many commits.
667 658 You should prefix this short description with the
668 <para> 659 recipe name (if changing a recipe), or else with
669 When you make a commit, you must follow certain standards 660 the short form path to the file being changed.
670 established by the OpenEmbedded and Yocto Project development teams. 661 </para></listitem>
671 For each commit, you must provide a single-line summary of the 662 <listitem><para>
672 change and you should almost always provide a more detailed 663 For the body of the commit message, provide
673 description of what you did (i.e. the body of the commit message). 664 detailed information that describes what you
674 The only exceptions for not providing a detailed description would 665 changed, why you made the change, and the approach
675 be if your change is a simple, self-explanatory change that needs 666 you used.
676 no further description beyond the summary. 667 It might also be helpful if you mention how you
677 Here are the guidelines for composing a commit message: 668 tested the change.
678 <itemizedlist> 669 Provide as much detail as you can in the body of
679 <listitem><para> 670 the commit message.
680 Provide a single-line, short summary of the change. 671 <note>
681 This summary is typically viewable in the "shortlist" of 672 You do not need to provide a more detailed
682 changes. 673 explanation of a change if the change is
683 Thus, providing something short and descriptive that 674 minor to the point of the single line
684 gives the reader a summary of the change is useful when 675 summary providing all the information.
685 viewing a list of many commits. 676 </note>
686 You should prefix this short description with the recipe 677 </para></listitem>
687 name (if changing a recipe), or else with the short form 678 <listitem><para>
688 path to the file being changed. 679 If the change addresses a specific bug or issue
689 </para></listitem> 680 that is associated with a bug-tracking ID,
690 <listitem><para> 681 include a reference to that ID in your detailed
691 For the body of the commit message, provide detailed 682 description.
692 information that describes what you changed, why you made 683 For example, the Yocto Project uses a specific
693 the change, and the approach you used. 684 convention for bug references - any commit that
694 It might also be helpful if you mention how you tested 685 addresses a specific bug should use the following
695 the change. 686 form for the detailed description.
696 Provide as much detail as you can in the body of the 687 Be sure to use the actual bug-tracking ID from
697 commit message. 688 Bugzilla for
698 </para></listitem> 689 <replaceable>bug-id</replaceable>:
699 <listitem><para> 690 <literallayout class='monospaced'>
700 If the change addresses a specific bug or issue that is
701 associated with a bug-tracking ID, include a reference
702 to that ID in your detailed description.
703 For example, the Yocto Project uses a specific convention
704 for bug references - any commit that addresses a specific
705 bug should use the following form for the detailed
706 description.
707 Be sure to use the actual bug-tracking ID from
708 Bugzilla for
709 <replaceable>bug-id</replaceable>:
710 <literallayout class='monospaced'>
711 Fixes [YOCTO #<replaceable>bug-id</replaceable>] 691 Fixes [YOCTO #<replaceable>bug-id</replaceable>]
712 692
713 <replaceable>detailed description of change</replaceable> 693 <replaceable>detailed description of change</replaceable>
714 </literallayout> 694 </literallayout>
715 </para></listitem> 695 </para></listitem>
716 </itemizedlist> 696 </itemizedlist>
717 </para>
718
719 <para>
720 You can find more guidance on creating well-formed commit messages
721 at this OpenEmbedded wiki page:
722 <ulink url='&OE_HOME_URL;/wiki/Commit_Patch_Message_Guidelines'></ulink>.
723 </para>
724 </section>
725
726 <section id='pushing-a-change-upstream'>
727 <title>Using Scripts to Push a Change Upstream and Request a Pull</title>
728
729 <para>
730 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
731 <itemizedlist>
732 <listitem><para>Make your changes in your local Git repository.</para></listitem>
733 <listitem><para>Stage your changes by using the <filename>git add</filename>
734 command on each file you changed.</para></listitem>
735 <listitem><para>
736 Commit the change by using the
737 <filename>git commit</filename> command.
738 Be sure to provide a commit message that follows the
739 project’s commit message standards as described earlier.
740 </para></listitem> 697 </para></listitem>
741 <listitem><para> 698 <listitem><para>
699 <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
742 Push the change to the upstream "contrib" repository by 700 Push the change to the upstream "contrib" repository by
743 using the <filename>git push</filename> command. 701 using the <filename>git push</filename> command.
744 </para></listitem> 702 </para></listitem>
745 <listitem><para>Notify the maintainer that you have pushed a change by making a pull 703 <listitem><para id='push-determine-who-to-notify'>
746 request. 704 <emphasis>Determine Who to Notify:</emphasis>
747 The Yocto Project provides two scripts that conveniently let you generate and send 705 Determine the maintainer that you need to notify for
748 pull requests to the Yocto Project. 706 the change.</para>
749 These scripts are <filename>create-pull-request</filename> and 707
750 <filename>send-pull-request</filename>. 708 <para>Before submitting any change, you need to be sure
751 You can find these scripts in the <filename>scripts</filename> directory 709 who the maintainer is that you need to notify.
752 within the <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.</para> 710 Use either of these methods to find out:
753 <para>Using these scripts correctly formats the requests without introducing any 711 <itemizedlist>
754 whitespace or HTML formatting. 712 <listitem><para>
755 The maintainer that receives your patches needs to be able to save and apply them 713 <emphasis>Maintenance File:</emphasis>
756 directly from your emails. 714 Examine the <filename>maintainers.inc</filename>
757 Using these scripts is the preferred method for sending patches.</para> 715 file, which is located in the
716 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
717 at
718 <filename>meta-poky/conf/distro/include</filename>,
719 to see who is responsible for code.
720 </para></listitem>
721 <listitem><para>
722 <emphasis>Search by File:</emphasis>
723 Using <ulink url='&YOCTO_DOCS_REF_URL;#git'>Git</ulink>,
724 you can enter the following command to bring up a
725 short list of all commits against a specific file:
726 <literallayout class='monospaced'>
727 git shortlog -- <replaceable>filename</replaceable>
728 </literallayout>
729 Just provide the name of the file for which you
730 are interested.
731 The information returned is not ordered by history
732 but does include a list of everyone who has
733 committed grouped by name.
734 From the list, you can see who is responsible for
735 the bulk of the changes against the file.
736 </para></listitem>
737 </itemizedlist>
738 For a list of the Yocto Project and related mailing lists,
739 see the
740 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
741 section in the Yocto Project Reference Manual.
742 </para></listitem>
743 <listitem><para>
744 <emphasis>Make a Pull Request:</emphasis>
745 Notify the maintainer that you have pushed a change by
746 making a pull request.</para>
747
748 <para>The Yocto Project provides two scripts that
749 conveniently let you generate and send pull requests to the
750 Yocto Project.
751 These scripts are <filename>create-pull-request</filename>
752 and <filename>send-pull-request</filename>.
753 You can find these scripts in the
754 <filename>scripts</filename> directory within the
755 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>.
756 </para>
757
758 <para>Using these scripts correctly formats the requests
759 without introducing any whitespace or HTML formatting.
760 The maintainer that receives your patches needs to be
761 able to save and apply them directly from your emails.
762 Using these scripts is the preferred method for sending
763 patches.</para>
764
758 <para>For help on using these scripts, simply provide the 765 <para>For help on using these scripts, simply provide the
759 <filename>-h</filename> argument as follows: 766 <filename>-h</filename> argument as follows:
760 <literallayout class='monospaced'> 767 <literallayout class='monospaced'>
761 $ poky/scripts/create-pull-request -h 768 $ poky/scripts/create-pull-request -h
762 $ poky/scripts/send-pull-request -h 769 $ poky/scripts/send-pull-request -h
763 </literallayout></para></listitem> 770 </literallayout>
764 </itemizedlist> 771 </para></listitem>
765 </para> 772 </orderedlist>
766
767 <para>
768 You can find general Git information on how to push a change upstream in the
769 <ulink url='http://git-scm.com/book/en/v2/Distributed-Git-Distributed-Workflows'>Git Community Book</ulink>.
770 </para> 773 </para>
771 </section> 774 </section>
772 775
@@ -774,49 +777,63 @@
774 <title>Using Email to Submit a Patch</title> 777 <title>Using Email to Submit a Patch</title>
775 778
776 <para> 779 <para>
777 You can submit patches without using the <filename>create-pull-request</filename> and 780 You can submit patches without using the
778 <filename>send-pull-request</filename> scripts described in the previous section. 781 <filename>create-pull-request</filename> and
782 <filename>send-pull-request</filename> scripts described in the
783 previous section.
779 However, keep in mind, the preferred method is to use the scripts. 784 However, keep in mind, the preferred method is to use the scripts.
780 </para> 785 </para>
781 786
782 <para> 787 <para>
783 Depending on the components changed, you need to submit the email 788 Depending on the components changed, you need to submit the email
784 to a specific mailing list. 789 to a specific mailing list.
785 For some guidance on which mailing list to use, see the list in the 790 For some guidance on which mailing list to use, see the
786 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 791 <link linkend='figuring-out-the-mailing-list-to-use'>beginning</link>
787 section. 792 of this section.
788 For a description of the available mailing lists, see the 793 For a description of all the available mailing lists, see the
789 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>" 794 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing Lists</ulink>"
790 section in the Yocto Project Reference Manual. 795 section in the Yocto Project Reference Manual.
791 </para> 796 </para>
792 797
793 <para> 798 <para>
794 Here is the general procedure on how to submit a patch through email without using the 799 Here is the general procedure on how to submit a patch through
795 scripts: 800 email without using the scripts:
796 <orderedlist> 801 <orderedlist>
797 <listitem><para> 802 <listitem><para>
803 <emphasis>Make Your Changes Locally:</emphasis>
798 Make your changes in your local Git repository. 804 Make your changes in your local Git repository.
805 You should make small, controlled, isolated changes.
806 Keeping changes small and isolated aids review,
807 makes merging/rebasing easier and keeps the change
808 history clean should anyone need to refer to it in
809 future.
799 </para></listitem> 810 </para></listitem>
800 <listitem><para> 811 <listitem><para>
801 Stage your changes by using the 812 <emphasis>Stage Your Changes:</emphasis>
802 <filename>git add</filename> command on each file you 813 Stage your changes by using the <filename>git add</filename>
803 changed. 814 command on each file you changed.
804 </para></listitem> 815 </para></listitem>
805 <listitem><para> 816 <listitem><para>
817 <emphasis>Commit Your Changes:</emphasis>
806 Commit the change by using the 818 Commit the change by using the
807 <filename>git commit --signoff</filename> command. 819 <filename>git commit --signoff</filename> command.
808 Using the <filename>--signoff</filename> option identifies 820 Using the <filename>--signoff</filename> option identifies
809 you as the person making the change and also satisfies 821 you as the person making the change and also satisfies
810 the Developer's Certificate of Origin (DCO) shown earlier. 822 the Developer's Certificate of Origin (DCO) shown earlier.
811 </para> 823 </para>
824
812 <para>When you form a commit, you must follow certain 825 <para>When you form a commit, you must follow certain
813 standards established by the Yocto Project development 826 standards established by the Yocto Project development
814 team. 827 team.
815 See the earlier section 828 See
816 "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>" 829 <link linkend='making-sure-you-have-correct-commit-information'>Step 3</link>
817 for Yocto Project commit message standards. 830 in the previous section for information on how to
831 provide commit information that meets Yocto Project
832 commit message standards.
818 </para></listitem> 833 </para></listitem>
819 <listitem><para>Format the commit into an email message. 834 <listitem><para>
835 <emphasis>Format the Commit:</emphasis>
836 Format the commit into an email message.
820 To format commits, use the 837 To format commits, use the
821 <filename>git format-patch</filename> command. 838 <filename>git format-patch</filename> command.
822 When you provide the command, you must include a revision 839 When you provide the command, you must include a revision
@@ -831,9 +848,11 @@
831 <literallayout class='monospaced'> 848 <literallayout class='monospaced'>
832 $ git format-patch HEAD~ 849 $ git format-patch HEAD~
833 </literallayout></para> 850 </literallayout></para>
851
834 <para>After the command is run, the current directory 852 <para>After the command is run, the current directory
835 contains a numbered <filename>.patch</filename> file for 853 contains a numbered <filename>.patch</filename> file for
836 the commit.</para> 854 the commit.</para>
855
837 <para>If you provide several commits as part of the 856 <para>If you provide several commits as part of the
838 command, the <filename>git format-patch</filename> command 857 command, the <filename>git format-patch</filename> command
839 produces a series of numbered files in the current 858 produces a series of numbered files in the current
@@ -857,6 +876,7 @@
857 </note> 876 </note>
858 </para></listitem> 877 </para></listitem>
859 <listitem><para> 878 <listitem><para>
879 <emphasis>Import the Files Into Your Mail Client:</emphasis>
860 Import the files into your mail client by using the 880 Import the files into your mail client by using the
861 <filename>git send-email</filename> command. 881 <filename>git send-email</filename> command.
862 <note> 882 <note>
@@ -866,6 +886,7 @@
866 For Ubuntu, Debian, and Fedora the package is 886 For Ubuntu, Debian, and Fedora the package is
867 <filename>git-email</filename>. 887 <filename>git-email</filename>.
868 </note></para> 888 </note></para>
889
869 <para>The <filename>git send-email</filename> command 890 <para>The <filename>git send-email</filename> command
870 sends email by using a local or remote Mail Transport Agent 891 sends email by using a local or remote Mail Transport Agent
871 (MTA) such as <filename>msmtp</filename>, 892 (MTA) such as <filename>msmtp</filename>,
@@ -882,6 +903,7 @@
882 applicable by the maintainer is to do a dry run and send 903 applicable by the maintainer is to do a dry run and send
883 them to yourself and then save and apply them as the 904 them to yourself and then save and apply them as the
884 maintainer would.</para> 905 maintainer would.</para>
906
885 <para>The <filename>git send-email</filename> command is 907 <para>The <filename>git send-email</filename> command is
886 the preferred method for sending your patches since there 908 the preferred method for sending your patches since there
887 is no risk of compromising whitespace in the body of the 909 is no risk of compromising whitespace in the body of the
generated by cgit v1.2.3-54-g00ecf (git 2.39.0) at 2024-11-14 17:02:26 +0000