diff options
| author | Scott Rifenbark <srifenbark@gmail.com> | 2017-06-19 16:40:13 -0700 |
|---|---|---|
| committer | Richard Purdie <richard.purdie@linuxfoundation.org> | 2017-06-22 09:16:44 +0100 |
| commit | e928b5251cdc7baba8a78380041b8156c106f9fc (patch) | |
| tree | b7bce0e134fc0bd1db7a184547b281940df729ac | |
| parent | 652d8cb5835d1caff7282ecca45074c76779fd96 (diff) | |
| download | poky-e928b5251cdc7baba8a78380041b8156c106f9fc.tar.gz | |
dev-manual: Updated "How to submit a change" section.
Fixes [YOCTO #11630]
The section on how to submit a change was pretty much a procedure
section. I did some rewriting to make it more that way.
(From yocto-docs rev: d7edce9268ee5cae96c09c79fe34d5d2dbb701e0)
Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
| -rw-r--r-- | documentation/dev-manual/dev-manual-newbie.xml | 576 |
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 |