summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorPaul Eggleton <paul.eggleton@linux.intel.com>2012-07-02 10:20:20 +0100
committerRichard Purdie <richard.purdie@linuxfoundation.org>2012-07-04 14:48:15 +0100
commit257e61a2cb85cb849f18e9d2f314cab467be3c80 (patch)
treecd61bccfa71c5ab94f5c4ce62724d836049685f8
parentdd5f6ae551bd074926771091326c4152af8cbc4b (diff)
downloadpoky-257e61a2cb85cb849f18e9d2f314cab467be3c80.tar.gz
dev-manual: tidy up "How to Submit a Change" section
* Change some of the language and patch submission directions to correctly represent how we work together with OpenEmbedded (this changed with the introduction of OE-Core a few releases ago). * Correct --help option to -h for pull request scripts * Clarify commit message guidelines * Touch up a few other bits and pieces Fixes [YOCTO #2671]. (From yocto-docs rev: 3170ce5e0757951afee13207c117316e33449b39) Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com> Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>
-rw-r--r--documentation/dev-manual/dev-manual-newbie.xml119
1 files changed, 59 insertions, 60 deletions
diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 94f3471f13..a67a173810 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -874,54 +874,53 @@
874 <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem> 874 <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
875 </orderedlist> 875 </orderedlist>
876 </para> 876 </para>
877
878 <note>
879 Bugs in the Yocto Project Bugzilla follow naming convention:
880 <filename>[YOCTO #&lt;number&gt;]</filename>, where <filename>&lt;number&gt;</filename> is the
881 assigned defect ID used in Bugzilla.
882 So, for example, a valid way to refer to a defect would be <filename>[YOCTO #1011]</filename>.
883 This convention becomes important if you are submitting patches against the Yocto Project
884 code itself.
885 </note>
886</section> 877</section>
887 878
888<section id='how-to-submit-a-change'> 879<section id='how-to-submit-a-change'>
889 <title>How to Submit a Change</title> 880 <title>How to Submit a Change</title>
890 881
891 <para> 882 <para>
892 Contributions to the Yocto Project are very welcome. 883 Contributions to the Yocto Project and OpenEmbedded are very welcome.
893 Because the Yocto Project is extremely configurable and flexible, we recognize that developers 884 Because the system is extremely configurable and flexible, we recognize that developers
894 will want to extend, configure or optimize it for their specific uses. 885 will want to extend, configure or optimize it for their specific uses.
895 You should send patches to the appropriate Yocto Project mailing list to get them 886 You should send patches to the appropriate mailing list so that they
896 in front of the Yocto Project Maintainer. 887 can be reviewed and merged by the appropriate maintainer.
897 For a list of the Yocto Project mailing lists, see the 888 For a list of the Yocto Project and related mailing lists, see the
898 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in 889 "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in
899 The Yocto Project Reference Manual. 890 The Yocto Project Reference Manual.
900 </para> 891 </para>
901 892
902 <para> 893 <para>
903 The following is some guidance on which mailing list to use for what type of defect: 894 The following is some guidance on which mailing list to use for what type of change:
904 <itemizedlist> 895 <itemizedlist>
905 <listitem><para>For defects against the Yocto Project build system Poky, send 896 <listitem><para>For changes to the core metadata, send your patch to the
906 your patch to the 897 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
907 <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> mailing list. 898 For example, a change to anything under the <filename>meta</filename> or
908 This mailing list corresponds to issues that are not specific to the Yocto Project but 899 <filename>scripts</filename> directories
909 are part of the OE-core. 900 should be sent to this mailing list.</para></listitem>
910 For example, a defect against anything in the <filename>meta</filename> layer 901 <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
911 or the BitBake Manual could be sent to this mailing list.</para></listitem> 902 directory), send your patch to the
912 <listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project 903 <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
913 documentation use the 904 <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
914 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> mailing list. 905 <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
915 This mailing list corresponds to Yocto-specific areas such as 906 <listitem><para>For changes to other layers hosted on yoctoproject.org (unless the
916 <filename>meta-yocto</filename>, <filename>meta-intel</filename>, 907 layer's documentation specifies otherwise), tools, and Yocto Project
917 <filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem> 908 documentation, use the
909 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
910 <listitem><para>For additional recipes that do not fit into the core metadata,
911 you should determine which layer the recipe should go into and submit the
912 change in the manner recommended by the documentation (e.g. README) supplied
913 with the layer. If in doubt, please ask on the
914 <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
915 <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
916 mailing lists.</para></listitem>
918 </itemizedlist> 917 </itemizedlist>
919 </para> 918 </para>
920 919
921 <para> 920 <para>
922 When you send a patch, be sure to include a "Signed-off-by:" 921 When you send a patch, be sure to include a "Signed-off-by:"
923 line in the same style as required by the Linux kernel. 922 line in the same style as required by the Linux kernel.
924 Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1 923 Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
925 as follows: 924 as follows:
926 <literallayout class='monospaced'> 925 <literallayout class='monospaced'>
927 Developer's Certificate of Origin 1.1 926 Developer's Certificate of Origin 1.1
@@ -950,52 +949,52 @@
950 maintained indefinitely and may be redistributed consistent with 949 maintained indefinitely and may be redistributed consistent with
951 this project or the open source license(s) involved. 950 this project or the open source license(s) involved.
952 </literallayout> 951 </literallayout>
953 A Poky contributions tree (<filename>poky-contrib</filename>,
954 <filename>git://git.yoctoproject.org/poky-contrib.git</filename>)
955 exists for contributors to stage contributions.
956 If people desire such access, please ask on the mailing list.
957 Usually, the Yocto Project team will grant access to anyone with a proven track
958 record of good patches.
959 </para> 952 </para>
960 953
961 <para> 954 <para>
962 In a collaborative environment, it is necessary to have some sort of standard 955 In a collaborative environment, it is necessary to have some sort of standard
963 or method through which you submit changes. 956 or method through which you submit changes.
964 Otherwise, things could get quite chaotic. 957 Otherwise, things could get quite chaotic.
965 One general practice to follow is to make small, controlled changes to the 958 One general practice to follow is to make small, controlled changes.
966 Yocto Project. 959 Keeping changes small and isolated aids review, makes merging/rebasing easier
967 Keeping changes small and isolated lets you best keep pace with future Yocto Project changes. 960 and keeps the change history clean when anyone needs to refer to it in future.
968 </para> 961 </para>
969 962
970 <para> 963 <para>
971 When you create a commit, you must follow certain standards established by the 964 When you make a commit, you must follow certain standards established by the
972 Yocto Project development team. 965 OpenEmbedded and Yocto Project development teams.
973 For each commit, you must provide a single-line summary of the change and you 966 For each commit, you must provide a single-line summary of the change and you
974 almost always provide a more detailed description of what you did (i.e. the body 967 should almost always provide a more detailed description of what you did (i.e.
975 of the commit). 968 the body of the commit message).
976 The only exceptions for not providing a detailed description would be if your 969 The only exceptions for not providing a detailed description would be if your
977 change is a simple, self-explanatory change that needs no description. 970 change is a simple, self-explanatory change that needs no description.
978 Here are the Yocto Project commit message guidelines: 971 Here are the guidelines for composing a commit message:
979 <itemizedlist> 972 <itemizedlist>
980 <listitem><para>Provide a single-line, short summary of the change. 973 <listitem><para>Provide a single-line, short summary of the change.
981 This summary is typically viewable by source control systems. 974 This summary is typically viewable in the "shortlist" of changes.
982 Thus, providing something short and descriptive that gives the reader 975 Thus, providing something short and descriptive that gives the reader
983 a summary of the change is useful when viewing a list of many commits. 976 a summary of the change is useful when viewing a list of many commits.
977 This should be prefixed by the recipe name (if changing a recipe), or
978 else the short form path to the file being changed.
984 </para></listitem> 979 </para></listitem>
985 <listitem><para>For the body of the commit message, provide detailed information 980 <listitem><para>For the body of the commit message, provide detailed information
986 that describes what you changed, why you made the change, and the approach 981 that describes what you changed, why you made the change, and the approach
987 you used. 982 you used. It may also be helpful if you mention how you tested the change.
988 Provide as much detail as you can in the body of the commit message. 983 Provide as much detail as you can in the body of the commit message.
989 </para></listitem> 984 </para></listitem>
990 <listitem><para>If the change addresses a specific bug or issue that is 985 <listitem><para>If the change addresses a specific bug or issue that is
991 associated with a bug-tracking ID, prefix your detailed description 986 associated with a bug-tracking ID, include a reference to that ID in
992 with the bug or issue ID. 987 your detailed description.
993 For example, the Yocto Project tracks bugs using a bug-naming convention. 988 For example, the Yocto Project uses a specific convention for bug
994 Any commits that address a bug must start with the bug ID in the description 989 references - any commit that addresses a specific bug should include the
995 as follows: 990 bug ID in the description (typically at the end) as follows:
996 <literallayout class='monospaced'> 991 <literallayout class='monospaced'>
997 YOCTO #&lt;bug-id&gt;: &lt;Detailed description of commit&gt; 992 &lt;detailed description of change&gt;
993
994 [YOCTO #&lt;bug-id&gt;]
998 </literallayout></para></listitem> 995 </literallayout></para></listitem>
996 Where &lt;bug-id&gt; is replaced with the specific bug ID from the
997 Yocto Project Bugzilla instance.
999 </itemizedlist> 998 </itemizedlist>
1000 </para> 999 </para>
1001 1000
@@ -1016,11 +1015,11 @@
1016 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows: 1015 The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
1017 <itemizedlist> 1016 <itemizedlist>
1018 <listitem><para>Make your changes in your local Git repository.</para></listitem> 1017 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1019 <listitem><para>Stage your commit (or change) by using the <filename>git add</filename> 1018 <listitem><para>Stage your changes by using the <filename>git add</filename>
1020 command.</para></listitem> 1019 command on each file you changed.</para></listitem>
1021 <listitem><para>Commit the change by using the <filename>git commit</filename> 1020 <listitem><para>Commit the change by using the <filename>git commit</filename>
1022 command and push it to the "contrib" repository. 1021 command and push it to the "contrib" repository.
1023 Be sure to provide a commit message that follows the project’s commit standards 1022 Be sure to provide a commit message that follows the project’s commit message standards
1024 as described earlier.</para></listitem> 1023 as described earlier.</para></listitem>
1025 <listitem><para>Notify the maintainer that you have pushed a change by making a pull 1024 <listitem><para>Notify the maintainer that you have pushed a change by making a pull
1026 request. 1025 request.
@@ -1031,10 +1030,10 @@
1031 You can find these scripts in the <filename>scripts</filename> directory of the 1030 You can find these scripts in the <filename>scripts</filename> directory of the
1032 Yocto Project file structure.</para> 1031 Yocto Project file structure.</para>
1033 <para>For help on using these scripts, simply provide the 1032 <para>For help on using these scripts, simply provide the
1034 <filename>--help</filename> argument as follows: 1033 <filename>-h</filename> argument as follows:
1035 <literallayout class='monospaced'> 1034 <literallayout class='monospaced'>
1036 $ ~/poky/scripts/create-pull-request --help 1035 $ ~/poky/scripts/create-pull-request -h
1037 $ ~/poky/scripts/send-pull-request --help 1036 $ ~/poky/scripts/send-pull-request -h
1038 </literallayout></para></listitem> 1037 </literallayout></para></listitem>
1039 </itemizedlist> 1038 </itemizedlist>
1040 </para> 1039 </para>
@@ -1054,8 +1053,8 @@
1054 Here is a general procedure: 1053 Here is a general procedure:
1055 <itemizedlist> 1054 <itemizedlist>
1056 <listitem><para>Make your changes in your local Git repository.</para></listitem> 1055 <listitem><para>Make your changes in your local Git repository.</para></listitem>
1057 <listitem><para>Stage your commit (or change) by using the <filename>git add</filename> 1056 <listitem><para>Stage your changes by using the <filename>git add</filename>
1058 command.</para></listitem> 1057 command on each file you changed.</para></listitem>
1059 <listitem><para>Commit the change by using the 1058 <listitem><para>Commit the change by using the
1060 <filename>git commit --signoff</filename> command. 1059 <filename>git commit --signoff</filename> command.
1061 Using the <filename>--signoff</filename> option identifies you as the person 1060 Using the <filename>--signoff</filename> option identifies you as the person