summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorScott Rifenbark <srifenbark@gmail.com>2017-06-21 11:18:23 -0700
committerRichard Purdie <richard.purdie@linuxfoundation.org>2017-06-22 09:16:45 +0100
commit1b36eebc23e0bedc4931f509f949420f4daf67e7 (patch)
tree361f6244ca85397904073f22fca33e4778ff1e94
parent33b507e9953a41b8025d676f2dc01e52d5cc4dd9 (diff)
downloadpoky-1b36eebc23e0bedc4931f509f949420f4daf67e7.tar.gz
dev-manual: Updates to the section on submitting changes to YP
I added detail to the procedure about pushing a change to a contrib directory and then requesting a pull using the scripts. More detailed with examples. Also, clarified some wording in the section about submitting a patch through email. (From yocto-docs rev: 76a358ba588b0f36d14aef0a68efe30c4e16746a) 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.xml93
1 files changed, 72 insertions, 21 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 803807df21..6dfec666be 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -710,17 +710,33 @@
710 </para></listitem> 710 </para></listitem>
711 <listitem><para> 711 <listitem><para>
712 <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis> 712 <emphasis>Push Your Commits to a "Contrib" Upstream:</emphasis>
713 Push the change to the upstream "contrib" repository by 713 If you have arranged for permissions to push to an
714 using the <filename>git push</filename> command. 714 upstream contrib repository, push the change to that
715 repository:
716 <literallayout class='monospaced'>
717 $ git push <replaceable>upstream_remote_repo</replaceable> <replaceable>local_branch_name</replaceable>
718 </literallayout>
719 For example, suppose you have permissions to push into the
720 upstream <filename>meta-intel-contrib</filename>
721 repository and you are working in a local branch named
722 <replaceable>your_name</replaceable><filename>/README</filename>.
723 The following command pushes your local commits to the
724 <filename>meta-intel-contrib</filename> upstream
725 repository and puts the commit in a branch named
726 <replaceable>your_name</replaceable><filename>/README</filename>:
727 <literallayout class='monospaced'>
728 $ git push meta-intel-contrib <replaceable>your_name</replaceable>/README
729 </literallayout>
715 </para></listitem> 730 </para></listitem>
716 <listitem><para id='push-determine-who-to-notify'> 731 <listitem><para id='push-determine-who-to-notify'>
717 <emphasis>Determine Who to Notify:</emphasis> 732 <emphasis>Determine Who to Notify:</emphasis>
718 Determine the maintainer that you need to notify for 733 Determine the maintainer or the mailing list
719 the change.</para> 734 that you need to notify for the change.</para>
720 735
721 <para>Before submitting any change, you need to be sure 736 <para>Before submitting any change, you need to be sure
722 who the maintainer is that you need to notify. 737 who the maintainer is or what mailing list that you need
723 Use either of these methods to find out: 738 to notify.
739 Use either these methods to find out:
724 <itemizedlist> 740 <itemizedlist>
725 <listitem><para> 741 <listitem><para>
726 <emphasis>Maintenance File:</emphasis> 742 <emphasis>Maintenance File:</emphasis>
@@ -747,16 +763,19 @@
747 From the list, you can see who is responsible for 763 From the list, you can see who is responsible for
748 the bulk of the changes against the file. 764 the bulk of the changes against the file.
749 </para></listitem> 765 </para></listitem>
766 <listitem><para>
767 <emphasis>Examine the List of Mailing Lists:</emphasis>
768 For a list of the Yocto Project and related mailing
769 lists, see the
770 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
771 section in the Yocto Project Reference Manual.
772 </para></listitem>
750 </itemizedlist> 773 </itemizedlist>
751 For a list of the Yocto Project and related mailing lists,
752 see the
753 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>"
754 section in the Yocto Project Reference Manual.
755 </para></listitem> 774 </para></listitem>
756 <listitem><para> 775 <listitem><para>
757 <emphasis>Make a Pull Request:</emphasis> 776 <emphasis>Make a Pull Request:</emphasis>
758 Notify the maintainer that you have pushed a change by 777 Notify the maintainer or the mailing list that you have
759 making a pull request.</para> 778 pushed a change by making a pull request.</para>
760 779
761 <para>The Yocto Project provides two scripts that 780 <para>The Yocto Project provides two scripts that
762 conveniently let you generate and send pull requests to the 781 conveniently let you generate and send pull requests to the
@@ -765,22 +784,53 @@
765 and <filename>send-pull-request</filename>. 784 and <filename>send-pull-request</filename>.
766 You can find these scripts in the 785 You can find these scripts in the
767 <filename>scripts</filename> directory within the 786 <filename>scripts</filename> directory within the
768 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>. 787 <ulink url='&YOCTO_DOCS_REF_URL;#source-directory'>Source Directory</ulink>
788 (e.g. <filename>~/poky/scripts</filename>).
769 </para> 789 </para>
770 790
771 <para>Using these scripts correctly formats the requests 791 <para>Using these scripts correctly formats the requests
772 without introducing any whitespace or HTML formatting. 792 without introducing any whitespace or HTML formatting.
773 The maintainer that receives your patches needs to be 793 The maintainer that receives your patches either directly
774 able to save and apply them directly from your emails. 794 or through the mailing list needs to be able to save and
795 apply them directly from your emails.
775 Using these scripts is the preferred method for sending 796 Using these scripts is the preferred method for sending
776 patches.</para> 797 patches.</para>
777 798
778 <para>For help on using these scripts, simply provide the 799 <para>First, create the pull request.
779 <filename>-h</filename> argument as follows: 800 For example, the following command runs the script,
801 specifies the upstream repository in the contrib directory
802 into which you pushed the change, and provides a subject
803 line in the created patch files:
780 <literallayout class='monospaced'> 804 <literallayout class='monospaced'>
805 $ ~/poky/scripts/create-pull-request -u meta-intel-contrib -s "Updated Manual Section Reference in README"
806 </literallayout>
807 Running this script forms
808 <filename>*.patch</filename> files in a folder named
809 <filename>pull-</filename><replaceable>PID</replaceable>
810 in the current directory.
811 One of the patch files is a cover letter.</para>
812
813 <para>Before running the
814 <filename>send-pull-request</filename> script, you must
815 edit the cover letter patch to insert information about
816 your change.
817 After editing the cover letter, send the pull request.
818 For example, the following command runs the script and
819 specifies the patch directory and email address.
820 In this example, the email address is a mailing list:
821 <literallayout class='monospaced'>
822 $ ~/poky/scripts/send-pull-request -p ~/meta-intel/pull-10565 -t meta-intel@yoctoproject.org
823 </literallayout>
824 You need to follow the prompts as the script is
825 interactive.
826 <note>
827 For help on using these scripts, simply provide the
828 <filename>-h</filename> argument as follows:
829 <literallayout class='monospaced'>
781 $ poky/scripts/create-pull-request -h 830 $ poky/scripts/create-pull-request -h
782 $ poky/scripts/send-pull-request -h 831 $ poky/scripts/send-pull-request -h
783 </literallayout> 832 </literallayout>
833 </note>
784 </para></listitem> 834 </para></listitem>
785 </orderedlist> 835 </orderedlist>
786 </para> 836 </para>
@@ -918,9 +968,10 @@
918 maintainer would.</para> 968 maintainer would.</para>
919 969
920 <para>The <filename>git send-email</filename> command is 970 <para>The <filename>git send-email</filename> command is
921 the preferred method for sending your patches since there 971 the preferred method for sending your patches using
922 is no risk of compromising whitespace in the body of the 972 email since there is no risk of compromising whitespace
923 message, which can occur when you use your own mail client. 973 in the body of the message, which can occur when you use
974 your own mail client.
924 The command also has several options that let you 975 The command also has several options that let you
925 specify recipients and perform further editing of the 976 specify recipients and perform further editing of the
926 email message. 977 email message.