summaryrefslogtreecommitdiffstats
path: root/documentation/dev-manual/dev-manual-newbie.xml
diff options
context:
space:
mode:
authorScott Rifenbark <scott.m.rifenbark@intel.com>2011-09-14 08:33:00 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2011-09-25 17:57:17 +0100
commit96d43c2410e75ca24fa78d14d338b4035d89230e (patch)
treebfeffd58506335575439408933d65d7af9d67a29 /documentation/dev-manual/dev-manual-newbie.xml
parentcde2aa61cfab1247bcabdb8e93fb182f9dd4e61d (diff)
downloadpoky-96d43c2410e75ca24fa78d14d338b4035d89230e.tar.gz
documentation/dev-manual/dev-manual-newbie.xml: re-write change submit
The section on submitting a change was very sparse and incomplete. I have significantly upgraded this section to provide more details. (From yocto-docs rev: af43bb1e4902c45afb5ac4b0f099877acd7a81a2) Signed-off-by: Scott Rifenbark <scott.m.rifenbark@intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
Diffstat (limited to 'documentation/dev-manual/dev-manual-newbie.xml')
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml164
1 files changed, 113 insertions, 51 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index acb4731282..0bc0be2164 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -509,18 +509,18 @@
509 509
510 <para> 510 <para>
511 Here are some things to remember when dealing with bugs against the Yocto Project: 511 Here are some things to remember when dealing with bugs against the Yocto Project:
512 <itemizedlist> 512 <itemizedlist>
513 <listitem><para>The Yocto Project follows a naming bug-naming convention: 513 <listitem><para>The Yocto Project follows a naming bug-naming convention:
514 <filename>[YOCTO #&lt;number&gt;]</filename>, where <filename>&lt;number&gt;</filename> is the 514 <filename>[YOCTO #&lt;number&gt;]</filename>, where <filename>&lt;number&gt;</filename> is the
515 assigned defect ID used in Bugzilla. 515 assigned defect ID used in Bugzilla.
516 So, for example, a valid way to refer to a defect when creating a commit comment 516 So, for example, a valid way to refer to a defect when creating a commit comment
517 would be <filename>[YOCTO 1011]</filename>. 517 would be <filename>[YOCTO #1011]</filename>.
518 This convention becomes important if you are submitting patches against the Yocto Project 518 This convention becomes important if you are submitting patches against the Yocto Project
519 code itself. 519 code itself.
520 See the following section for more information.</para></listitem> 520 See the following section for more information.</para></listitem>
521 <listitem><para>Defects for Yocto Project fall into one of four classifications: Yocto Projects, 521 <listitem><para>Defects for Yocto Project fall into one of four classifications: Yocto Projects,
522 Infrastructure, Poky, and Yocto Metadata Layers.</para></listitem> 522 Infrastructure, Poky, and Yocto Metadata Layers.</para></listitem>
523 </itemizedlist> 523 </itemizedlist>
524 </para> 524 </para>
525</section> 525</section>
526 526
@@ -529,9 +529,9 @@
529 529
530 <para> 530 <para>
531 Contributions to the Yocto Project are very welcome. 531 Contributions to the Yocto Project are very welcome.
532 You should send patches to the Yocto Project mailing list to get it in front of the 532 You should send patches to the Yocto Project mailing list to get them in front of the
533 Yocto Project Maintainer. 533 Yocto Project Maintainer.
534 When you send your patch, be sure to include a "signed-off-by:" 534 When you send a patch, be sure to include a "signed-off-by:"
535 line in the same style as required by the Linux kernel. 535 line in the same style as required by the Linux kernel.
536 Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1 536 Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1
537 as follows: 537 as follows:
@@ -577,31 +577,67 @@
577 </para> 577 </para>
578 578
579 <para> 579 <para>
580 When you submit a change or patch to the Yocto Project, you must follow certain procedures. 580 When you form a commit you must follow certain standards established by the
581 In particular, the headers in patches and the commit messages must follow a certain standard. 581 Yocto Project development team.
582 The general process is the same as described earlier in this chapter. 582 For each commit, do the following:
583 For complete details on how to create proper commit messages and patch headers see 583 <itemizedlist>
584 [WRITER NOTE: I need the link to Mark's wiki page here that describes the process.] 584 <listitem><para>Provide a single-line, short summary of the change.
585 This summary is typically viewable by source control systems.
586 Thus, providing something short and descriptive that gives the reader
587 a summary of the change is useful when viewing a list of many commits.
588 </para></listitem>
589 <listitem><para>If the change addresses a specific bug or issue that is
590 associated with a bug-tracking ID, prefix the single-line commit summary
591 with the bug or issue ID.
592 For example, the Yocto Project tracks bugs using a bug-naming convention.
593 Any commits that address a bug must use a commit summary line in the
594 following form:
595 <literallayout class='monospaced'>
596 YOCTO #&lt;bug-id&gt;: &lt;Brief 40-character or less summary of the change&gt;
597 </literallayout></para></listitem>
598 <listitem><para>For the body of the commit message, provide detailed information
599 that describes what you changed, why you made the change, and the approach
600 you used.
601 Provide as much detail as you want in the body of the commit message.
602 </para></listitem>
603 </itemizedlist>
585 </para> 604 </para>
586 605
587 <para> 606 <para>
588 Following are general instructions for both pushing changes upstream and for submitting changes as patches. 607 Following are general instructions for both pushing changes upstream and for submitting changes as patches.
589 </para> 608 </para>
590 609
591 <section id='pushing-a-change-upstream'> 610 <section id='pushing-a-change-upstream'>
592 <title>Pushing a Change Upstream</title> 611 <title>Pushing a Change Upstream and Requesting a Pull</title>
593 612
594 <para> 613 <para>
595 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: 614 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
596 <itemizedlist> 615 <itemizedlist>
597 <listitem><para>Make your changes in your local Git repository.</para></listitem> 616 <listitem><para>Make your changes in your local Git repository.</para></listitem>
598 <listitem><para>Stage your commit (or change) by using the <filename>git add</filename> 617 <listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
599 command.</para></listitem> 618 command.</para></listitem>
600 <listitem><para>Commit the change by using the <filename>git commit</filename> 619 <listitem><para>Commit the change by using the <filename>git commit</filename>
601 command and push it to the upstream "contrib" repository. 620 command and push it to the upstream "contrib" repository.
602 Be sure to provide a commit message that follows the project’s commit standards.</para></listitem> 621 Be sure to provide a commit message that follows the project’s commit standards
603 <listitem><para>Notify the maintainer that you have pushed a change.</para></listitem> 622 as described earlier.</para></listitem>
604 </itemizedlist> 623 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
624 request.
625 The Yocto Project provides two scripts that conveniently let you generate and send
626 pull requests to the Yocto Project.
627 These scripts are <filename>create-pull-request</filename> and
628 <filename>send-pull-request</filename>.
629 You can find these scripts in the <filename>scripts</filename> directory of the
630 Yocto Project file structure.</para>
631 <para>For help on using these scripts, simply provide the
632 <filename>--help</filename> argument as follows:
633 <literallayout class='monospaced'>
634 $ ~/poky/scripts/create-pull-request --help
635 $ ~/poky/scripts/send-pull-request --help
636 </literallayout></para></listitem>
637 </itemizedlist>
638 </para>
639
640 <para>
605 You can find general Git information on how to push a change upstream 641 You can find general Git information on how to push a change upstream
606 <ulink url='http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#Developing-With-git'> 642 <ulink url='http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#Developing-With-git'>
607 here</ulink>. 643 here</ulink>.
@@ -609,30 +645,56 @@
609 </section> 645 </section>
610 646
611 <section id='submitting-a-patch'> 647 <section id='submitting-a-patch'>
612 <title>Submitting a Patch</title> 648 <title>Submitting a Patch Through Email</title>
613 649
614 <para> 650 <para>
615 If you have a just a few changes you can commit them and then submit them as an email to the maintainer. 651 If you have a just a few changes, you can commit them and then submit them as an
652 email to the maintainer.
616 Here is a general procedure: 653 Here is a general procedure:
617 <itemizedlist> 654 <itemizedlist>
618 <listitem><para>Make your changes in your local Git repository.</para></listitem> 655 <listitem><para>Make your changes in your local Git repository.</para></listitem>
619 <listitem><para>Stage your commit (or change) by using the <filename>git add</filename> 656 <listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
620 command.</para></listitem> 657 command.</para></listitem>
621 <listitem><para>Commit the change by using the <filename>git commit</filename> command. 658 <listitem><para>Commit the change by using the
622 Be sure to provide a commit message that follows the project’s commit standards.</para></listitem> 659 <filename>git commit --signoff</filename> command.
623 <listitem><para>Format the commit by using the <filename>git format-patch</filename> 660 Using the <filename>--signoff</filename> option identifies you as the person
624 command. 661 making the change.</para>
625 This step produces a numbered series of files in the current directory – one for 662 <para>When you form a commit you must follow certain standards established by the
626 each commit.</para></listitem> 663 Yocto Project development team.
627 <listitem><para>Import the files into your mail client by using the 664 See the
628 <filename>git-send-email</filename> command.</para></listitem> 665 <link linkend='how-to-submit-a-change'>How to Submit a Change</link> section
629 <listitem><para>Send the email by hand to the maintainer.</para></listitem> 666 earlier for Yocto Project commit message standards.</para></listitem>
630 </itemizedlist> 667 <listitem><para>Format the commit into an email messsage.
631 Be aware that there could be protocols and standards that you need to follow for your particular 668 To format commits, use the <filename>git format-patch</filename> command.
632 project. 669 When you provide the command, you must include a revision list or a number of patches
633 You can find general Git information for submitting a patch 670 as part of the command.
634 <ulink url='http://www.kernel.org/pub/software/scm/git/docs/user-manual.html#sharing-development'> 671 For example, these two commands each take the most recent single commit and
635 here</ulink>. 672 format it as an email message in the current directory:
673 <literallayout class='monospaced'>
674 $ git format-patch -1
675 $ git format-patch HEAD~
676 </literallayout></para>
677 <para>After the command is run, the current directory contains a
678 numbered <filename>.patch</filename> file for the commit.</para>
679 <para>If you provide several commits as part of the command, it produces a numbered
680 series of files in the current directory – one for each commit.
681 For information on the <filename>git format-patch</filename> command use the
682 <filename>man git-format-patch</filename> command.</para></listitem>
683 <listitem><para>Import the files into your mail client by using the
684 <filename>git send-email</filename> command.
685 <note>In order to use <filename>git send-email</filename>, you must have the
686 the proper Git packages installed.
687 For Ubuntu and Fedora the package is <filename>git-email</filename>.</note></para>
688 <para>The <filename>git send-email</filename> command sends email by using a local
689 or remote Mail Transport Agent (MTA) such as
690 <filename>msmtp</filename>, <filename>sendmail</filename>, or through a direct
691 <filename>smtp</filename> configuration in your Git <filename>config</filename>
692 file.</para>
693 <para>The <filename>git send-email</filename> command has several options that let you
694 specify recipients and perform further editing of the email message.
695 For information on how to use the <filename>git send-email</filename> command,
696 use the <filename>man git-send-email</filename> command.</para></listitem>
697 </itemizedlist>
636 </para> 698 </para>
637 </section> 699 </section>
638</section> 700</section>