[yocto-docs] [PATCH 0/5] Documentation fixes

[yocto-docs] [PATCH 0/5] Documentation fixes

[Paul Eggleton]

The following changes since commit d62747ca1d42cae703d1cd307dfe16bb9682b741:

  documentation/bsp-guide/bsp.xml: Yocto term paring (2012-06-29 06:58:01 -0700)

are available in the git repository at:

  git://git.yoctoproject.org/poky-contrib paule/doc-fixes-3
  http://git.yoctoproject.org/cgit.cgi/poky-contrib/log/?h=paule/doc-fixes-3

Paul Eggleton (5):
  poky-ref-manual: update mailing list info in ref manual
  dev-manual: tidy up "How to Submit a Change" section
  dev-manual: correct SMP_CONFIG
  shared state memory -> shared state cache
  dev-manual: menuconfig now works properly

 .../dev-manual/dev-manual-common-tasks.xml         |    2 +-
 .../dev-manual/dev-manual-kernel-appendix.xml      |   13 +--
 documentation/dev-manual/dev-manual-newbie.xml     |  119 ++++++++++----------
 documentation/poky-ref-manual/resources.xml        |   30 +++--
 .../poky-ref-manual/technical-details.xml          |    2 +-
 documentation/poky.ent                             |    1 +
 6 files changed, 82 insertions(+), 85 deletions(-)

-- 
1.7.9.5

[yocto-docs] [PATCH 1/5] poky-ref-manual: update mailing list info in ref manual

[Paul Eggleton]

We need to include the OpenEmbedded and BitBake mailing lists here as
they are an integral part of the community especially for patch
submission.

Note that this supersedes the information about mailing lists in the dev
manual (which should be replaced with a link to this section).

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/poky-ref-manual/resources.xml |   30 ++++++++++++++++-----------
 documentation/poky.ent                      |    1 +
 2 files changed, 19 insertions(+), 12 deletions(-)

diff --git a/documentation/poky-ref-manual/resources.xml b/documentation/poky-ref-manual/resources.xml
index 5dc6153..49fbac4 100644
--- a/documentation/poky-ref-manual/resources.xml
+++ b/documentation/poky-ref-manual/resources.xml
@@ -29,19 +29,25 @@
     <title>Mailing lists</title>
 
     <para>
-        To subscribe to the Yocto Project mailing lists, click on the following URLs and follow the instructions:
+        There are a number of mailing lists maintained by the Yocto Project as well as
+        related OpenEmbedded mailing lists for discussion, patch submission and announcements.
+        To subscribe to one of the following mailing lists, click on the appropriate URL
+        in the following list and follow the instructions:
         <itemizedlist>
-            <listitem><para><emphasis>
-                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink></emphasis>:
-                Use this list to receive offical Yocto Project announcements for developments and 
-                to learn about Yocto Project milestones.</para></listitem>
-            <listitem><para><emphasis><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink></emphasis>:
-                Use this list to monitor Yocto Project development discussions, ask questions, and 
-                get help.</para></listitem>
-            <listitem><para><emphasis><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink></emphasis>:
-                Use this list to monitor discussions about the Yocto Project build system Poky, 
-                ask questions, and get help.</para></listitem>
-        </itemizedlist>
+            <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> -
+                General Yocto Project discussion mailing list. </para></listitem>
+            <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'></ulink> -
+                Discussion mailing list about OpenEmbedded-Core (the core metadata).</para></listitem>
+            <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'></ulink> -
+                Discussion mailing list about OpenEmbedded.</para></listitem>
+            <listitem><para><ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'></ulink> -
+                Discussion mailing list about the BitBake build tool.</para></listitem>
+            <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> -
+                Discussion mailing list about Poky.</para></listitem>
+            <listitem><para><ulink url='&YOCTO_LISTS_URL;/listinfo/yocto-announce'></ulink> -
+                Mailing list to receive official Yocto Project release and milestone
+                announcements.</para></listitem>
+        </itemizedlist></para></listitem>
     </para>
 </section>
 
diff --git a/documentation/poky.ent b/documentation/poky.ent
index acbda7f..cf14798 100644
--- a/documentation/poky.ent
+++ b/documentation/poky.ent
@@ -13,6 +13,7 @@
 <!ENTITY YOCTO_GIT_URL "http://git.yoctoproject.org">
 <!ENTITY YOCTO_ADTREPO_URL "http://adtrepo.yoctoproject.org">
 <!ENTITY OE_HOME_URL "http://www.openembedded.org">
+<!ENTITY OE_LISTS_URL "http://lists.linuxtogo.org/cgi-bin/mailman">
 <!ENTITY OE_DOCS_URL "http://docs.openembedded.org">
 <!ENTITY OH_HOME_URL "http://o-hand.com">
 <!ENTITY BITBAKE_HOME_URL "http://developer.berlios.de/projects/bitbake/">
-- 
1.7.9.5

[yocto-docs] [PATCH 2/5] dev-manual: tidy up "How to Submit a Change" section

[Paul Eggleton]

* 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

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 documentation/dev-manual/dev-manual-newbie.xml |  119 ++++++++++++------------
 1 file changed, 59 insertions(+), 60 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 6a8d39c..4a39a59 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -855,54 +855,53 @@
             <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
         </orderedlist>
     </para>
- 
-    <note>
-        Bugs in the Yocto Project Bugzilla follow naming convention: 
-        <filename>[YOCTO #&lt;number&gt;]</filename>, where <filename>&lt;number&gt;</filename> is the 
-        assigned defect ID used in Bugzilla.  
-        So, for example, a valid way to refer to a defect would be <filename>[YOCTO #1011]</filename>.   
-        This convention becomes important if you are submitting patches against the Yocto Project 
-        code itself.
-    </note>
 </section>
 
 <section id='how-to-submit-a-change'>
     <title>How to Submit a Change</title>
 
     <para>
-        Contributions to the Yocto Project are very welcome. 
-        Because the Yocto Project is extremely configurable and flexible, we recognize that developers 
+        Contributions to the Yocto Project and OpenEmbedded are very welcome.
+        Because the system is extremely configurable and flexible, we recognize that developers
         will want to extend, configure or optimize it for their specific uses.
-        You should send patches to the appropriate Yocto Project mailing list to get them 
-        in front of the Yocto Project Maintainer.
-        For a list of the Yocto Project mailing lists, see the
+        You should send patches to the appropriate mailing list so that they
+        can be reviewed and merged by the appropriate maintainer.
+        For a list of the Yocto Project and related mailing lists, see the
         "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in 
         The Yocto Project Reference Manual.
     </para>
 
     <para>
-        The following is some guidance on which mailing list to use for what type of defect:
+        The following is some guidance on which mailing list to use for what type of change:
         <itemizedlist>
-            <listitem><para>For defects against the Yocto Project build system Poky, send 
-                your patch to the  
-                <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> mailing list. 
-                This mailing list corresponds to issues that are not specific to the Yocto Project but
-                are part of the OE-core.
-                For example, a defect against anything in the <filename>meta</filename> layer 
-                or the BitBake Manual could be sent to this mailing list.</para></listitem>
-            <listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project 
-                documentation use the 
-                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> mailing list.
-                This mailing list corresponds to Yocto-specific areas such as 
-                <filename>meta-yocto</filename>, <filename>meta-intel</filename>, 
-                <filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem>
+            <listitem><para>For changes to the core metadata, send your patch to the
+                <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
+                For example, a change to anything under the <filename>meta</filename> or
+                <filename>scripts</filename> directories
+                should be sent to this mailing list.</para></listitem>
+            <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
+                directory), send your patch to the
+                <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
+            <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
+                <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
+            <listitem><para>For changes to other layers hosted on yoctoproject.org (unless the
+                layer's documentation specifies otherwise), tools, and Yocto Project
+                documentation, use the
+                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
+            <listitem><para>For additional recipes that do not fit into the core metadata,
+                you should determine which layer the recipe should go into and submit the
+                change in the manner recommended by the documentation (e.g. README) supplied
+                with the layer. If in doubt, please ask on the
+                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
+                <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
+                mailing lists.</para></listitem>
         </itemizedlist>      
     </para>
 
     <para>  
         When you send a patch, be sure to include a "Signed-off-by:"
         line in the same style as required by the Linux kernel. 
-        Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1
+        Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
         as follows:
         <literallayout class='monospaced'>
      Developer's Certificate of Origin 1.1
@@ -931,52 +930,52 @@
          maintained indefinitely and may be redistributed consistent with
          this project or the open source license(s) involved.
         </literallayout>
-        A Poky contributions tree (<filename>poky-contrib</filename>, 
-        <filename>git://git.yoctoproject.org/poky-contrib.git</filename>)
-        exists for contributors to stage contributions.
-        If people desire such access, please ask on the mailing list. 
-        Usually, the Yocto Project team will grant access to anyone with a proven track 
-        record of good patches.
     </para>
 
     <para>
         In a collaborative environment, it is necessary to have some sort of standard 
         or method through which you submit changes.  
         Otherwise, things could get quite chaotic.
-        One general practice to follow is to make small, controlled changes to the 
-        Yocto Project.
-        Keeping changes small and isolated lets you best keep pace with future Yocto Project changes.
+        One general practice to follow is to make small, controlled changes.
+        Keeping changes small and isolated aids review, makes merging/rebasing easier
+        and keeps the change history clean when anyone needs to refer to it in future.
     </para>
 
     <para>
-        When you create a commit, you must follow certain standards established by the
-        Yocto Project development team. 
-        For each commit, you must provide a single-line summary of the change and you 
-        almost always provide a more detailed description of what you did (i.e. the body 
-        of the commit).
+        When you make a commit, you must follow certain standards established by the
+        OpenEmbedded and Yocto Project development teams.
+        For each commit, you must provide a single-line summary of the change and you
+        should almost always provide a more detailed description of what you did (i.e.
+        the body of the commit message).
         The only exceptions for not providing a detailed description would be if your 
         change is a simple, self-explanatory change that needs no description.
-        Here are the Yocto Project commit message guidelines:
+        Here are the guidelines for composing a commit message:
         <itemizedlist>
             <listitem><para>Provide a single-line, short summary of the change.
-                This summary is typically viewable by source control systems.
+                This summary is typically viewable in the "shortlist" of changes.
                 Thus, providing something short and descriptive that gives the reader 
                 a summary of the change is useful when viewing a list of many commits.
+                This should be prefixed by the recipe name (if changing a recipe), or
+                else the short form path to the file being changed.
                 </para></listitem>
             <listitem><para>For the body of the commit message, provide detailed information
                 that describes what you changed, why you made the change, and the approach
-                you used.  
+                you used. It may also be helpful if you mention how you tested the change.
                 Provide as much detail as you can in the body of the commit message.
                 </para></listitem>
             <listitem><para>If the change addresses a specific bug or issue that is 
-                associated with a bug-tracking ID, prefix your detailed description
-                with the bug or issue ID.  
-                For example, the Yocto Project tracks bugs using a bug-naming convention.
-                Any commits that address a bug must start with the bug ID in the description
-                as follows:
+                associated with a bug-tracking ID, include a reference to that ID in
+                your detailed description.
+                For example, the Yocto Project uses a specific convention for bug
+                references - any commit that addresses a specific bug should include the
+                bug ID in the description (typically at the end) as follows:
                 <literallayout class='monospaced'>
-     YOCTO #&lt;bug-id&gt;:  &lt;Detailed description of commit&gt;
+     &lt;detailed description of change&gt;
+
+     [YOCTO #&lt;bug-id&gt;]
                 </literallayout></para></listitem>
+                Where &lt;bug-id&gt; is replaced with the specific bug ID from the
+                Yocto Project Bugzilla instance.
         </itemizedlist>
     </para>
 
@@ -997,11 +996,11 @@
             The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
             <itemizedlist>
                 <listitem><para>Make your changes in your local Git repository.</para></listitem>
-                <listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
-                    command.</para></listitem>
+                <listitem><para>Stage your changes by using the <filename>git add</filename>
+                    command on each file you changed.</para></listitem>
                 <listitem><para>Commit the change by using the <filename>git commit</filename>
                     command and push it to the "contrib" repository.  
-                    Be sure to provide a commit message that follows the project’s commit standards
+                    Be sure to provide a commit message that follows the project’s commit message standards
                     as described earlier.</para></listitem>
                 <listitem><para>Notify the maintainer that you have pushed a change by making a pull 
                     request.
@@ -1012,10 +1011,10 @@
                     You can find these scripts in the <filename>scripts</filename> directory of the 
                     Yocto Project file structure.</para>
                     <para>For help on using these scripts, simply provide the 
-                    <filename>--help</filename> argument as follows:
+                    <filename>-h</filename> argument as follows:
                     <literallayout class='monospaced'>
-     $ ~/poky/scripts/create-pull-request --help
-     $ ~/poky/scripts/send-pull-request --help
+     $ ~/poky/scripts/create-pull-request -h
+     $ ~/poky/scripts/send-pull-request -h
                     </literallayout></para></listitem>
             </itemizedlist>
         </para>
@@ -1035,8 +1034,8 @@
             Here is a general procedure:
             <itemizedlist>
                 <listitem><para>Make your changes in your local Git repository.</para></listitem>
-                <listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
-                    command.</para></listitem>
+                <listitem><para>Stage your changes by using the <filename>git add</filename>
+                    command on each file you changed.</para></listitem>
                 <listitem><para>Commit the change by using the 
                     <filename>git commit --signoff</filename> command.
                     Using the <filename>--signoff</filename> option identifies you as the person 
-- 
1.7.9.5

[yocto-docs] [PATCH 3/5] dev-manual: correct SMP_CONFIG

[Paul Eggleton]

It's CONFIG_SMP here, and since the title of the section already
mentions it, just change the sentence to be more generic.

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 .../dev-manual/dev-manual-common-tasks.xml         |    2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/documentation/dev-manual/dev-manual-common-tasks.xml b/documentation/dev-manual/dev-manual-common-tasks.xml
index 067b5df..5622fea 100644
--- a/documentation/dev-manual/dev-manual-common-tasks.xml
+++ b/documentation/dev-manual/dev-manual-common-tasks.xml
@@ -1399,7 +1399,7 @@ so that there are some definite steps on how to do this.  I need more detail her
             </para>
 
             <para>
-                For an example that shows how to change the <filename>SMP_CONFIG</filename> parameter
+                For an example that shows how to change a specific kernel option
                 using <filename>menuconfig</filename>, see the 
                 "<link linkend='changing-the-config-smp-configuration-using-menuconfig'>Changing
                 the <filename>CONFIG_SMP</filename> Configuration Using <filename>menuconfig</filename></link>" 
-- 
1.7.9.5

[yocto-docs] [PATCH 4/5] shared state memory -> shared state cache

[Paul Eggleton]

"shared state cache" is the generally accepted term for this.

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 .../dev-manual/dev-manual-kernel-appendix.xml      |    2 +-
 .../poky-ref-manual/technical-details.xml          |    2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml
index 0f69ef1..b4c6328 100644
--- a/documentation/dev-manual/dev-manual-kernel-appendix.xml
+++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -696,7 +696,7 @@
                 The Yocto Project build environment recognizes this kernel as 
                 <filename>linux-yocto</filename>.
                 Thus, the following commands from the shell in which you previously sourced the 
-                environment initialization script cleans the shared state memory and the 
+                environment initialization script cleans the shared state cache and the 
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
                 directory and then builds and launches <filename>menuconfig</filename>:
                 <literallayout class='monospaced'>
diff --git a/documentation/poky-ref-manual/technical-details.xml b/documentation/poky-ref-manual/technical-details.xml
index a63943e..4cc1a7b 100644
--- a/documentation/poky-ref-manual/technical-details.xml
+++ b/documentation/poky-ref-manual/technical-details.xml
@@ -525,7 +525,7 @@
             <title>Invalidating Shared State</title>
 
             <para>
-                The shared state code uses checksums and shared state memory 
+                The shared state code uses checksums and shared state
                 cache to avoid unnecessarily rebuilding tasks.
                 As with all schemes, this one has some drawbacks.
                 It is possible that you could make implicit changes that are not factored 
-- 
1.7.9.5

[yocto-docs] [PATCH 5/5] dev-manual: menuconfig now works properly

[Paul Eggleton]

Bug 2256 is now fixed in master and the fix will be in the next release,
so update the documentation accordingly.

Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
---
 .../dev-manual/dev-manual-kernel-appendix.xml      |   11 +----------
 1 file changed, 1 insertion(+), 10 deletions(-)

diff --git a/documentation/dev-manual/dev-manual-kernel-appendix.xml b/documentation/dev-manual/dev-manual-kernel-appendix.xml
index b4c6328..1a1c8a7 100644
--- a/documentation/dev-manual/dev-manual-kernel-appendix.xml
+++ b/documentation/dev-manual/dev-manual-kernel-appendix.xml
@@ -700,16 +700,8 @@
                 <ulink url='&YOCTO_DOCS_REF_URL;#var-WORKDIR'><filename>WORKDIR</filename></ulink>
                 directory and then builds and launches <filename>menuconfig</filename>:
                 <literallayout class='monospaced'>
-     $ bitbake linux-yocto -c cleansstate
      $ bitbake linux-yocto -c menuconfig
                 </literallayout>
-                <note>
-                    Due to a bug in the release, it is necessary to clean the shared state memory
-                    in order for configurations made using <filename>menuconfig</filename> to take
-                    effect.
-                    For information on the bug, see
-                    <ulink url='https://bugzilla.yoctoproject.org/show_bug.cgi?id=2256'></ulink>
-                </note>
             </para>
                   
             <para>
@@ -773,9 +765,8 @@
 
             <para>
                 At this point, you are ready to recompile your kernel image with 
-                the new setting in effect using the BitBake commands below:
+                the new setting in effect using the BitBake command below:
                 <literallayout class='monospaced'>
-     $ bitbake linux-yocto -c compile -f
      $ bitbake linux-yocto
                 </literallayout>
             </para>
-- 
1.7.9.5

Re: [yocto-docs] [PATCH 1/5] poky-ref-manual: update mailing list info in ref manual

[Paul Eggleton]

On Monday 02 July 2012 10:54:20 Paul Eggleton wrote:
> +        </itemizedlist></para></listitem>
>      </para>

Whoops, that's a stray </para></listitem> in there. I've pushed a fixed version 
to the same contrib branch.

Cheers,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre

Re: [yocto-docs] [PATCH 2/5] dev-manual: tidy up "How to Submit a Change" section

[Darren Hart]

On 07/02/2012 02:54 AM, Paul Eggleton wrote:
> * 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

That fixes Bug 2671, consider adding the tag to the commit header.

[YOCTO #2671]

> * Clarify commit message guidelines
> * Touch up a few other bits and pieces
> 
> Signed-off-by: Paul Eggleton <paul.eggleton@linux.intel.com>
> ---
>  documentation/dev-manual/dev-manual-newbie.xml |  119 ++++++++++++------------
>  1 file changed, 59 insertions(+), 60 deletions(-)
> 
> diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
> index 6a8d39c..4a39a59 100644
> --- a/documentation/dev-manual/dev-manual-newbie.xml
> +++ b/documentation/dev-manual/dev-manual-newbie.xml
> @@ -855,54 +855,53 @@
>              <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
>          </orderedlist>
>      </para>
> - 
> -    <note>
> -        Bugs in the Yocto Project Bugzilla follow naming convention: 
> -        <filename>[YOCTO #&lt;number&gt;]</filename>, where <filename>&lt;number&gt;</filename> is the 
> -        assigned defect ID used in Bugzilla.  
> -        So, for example, a valid way to refer to a defect would be <filename>[YOCTO #1011]</filename>.   
> -        This convention becomes important if you are submitting patches against the Yocto Project 
> -        code itself.
> -    </note>
>  </section>
>  
>  <section id='how-to-submit-a-change'>
>      <title>How to Submit a Change</title>
>  
>      <para>
> -        Contributions to the Yocto Project are very welcome. 
> -        Because the Yocto Project is extremely configurable and flexible, we recognize that developers 
> +        Contributions to the Yocto Project and OpenEmbedded are very welcome.
> +        Because the system is extremely configurable and flexible, we recognize that developers
>          will want to extend, configure or optimize it for their specific uses.
> -        You should send patches to the appropriate Yocto Project mailing list to get them 
> -        in front of the Yocto Project Maintainer.
> -        For a list of the Yocto Project mailing lists, see the
> +        You should send patches to the appropriate mailing list so that they
> +        can be reviewed and merged by the appropriate maintainer.
> +        For a list of the Yocto Project and related mailing lists, see the
>          "<ulink url='&YOCTO_DOCS_REF_URL;#resources-mailinglist'>Mailing lists</ulink>" section in 
>          The Yocto Project Reference Manual.
>      </para>
>  
>      <para>
> -        The following is some guidance on which mailing list to use for what type of defect:
> +        The following is some guidance on which mailing list to use for what type of change:
>          <itemizedlist>
> -            <listitem><para>For defects against the Yocto Project build system Poky, send 
> -                your patch to the  
> -                <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'></ulink> mailing list. 
> -                This mailing list corresponds to issues that are not specific to the Yocto Project but
> -                are part of the OE-core.
> -                For example, a defect against anything in the <filename>meta</filename> layer 
> -                or the BitBake Manual could be sent to this mailing list.</para></listitem>
> -            <listitem><para>For defects against Yocto-specific layers, tools, and Yocto Project 
> -                documentation use the 
> -                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'></ulink> mailing list.
> -                This mailing list corresponds to Yocto-specific areas such as 
> -                <filename>meta-yocto</filename>, <filename>meta-intel</filename>, 
> -                <filename>linux-yocto</filename>, and <filename>documentation</filename>.</para></listitem>
> +            <listitem><para>For changes to the core metadata, send your patch to the
> +                <ulink url='&OE_LISTS_URL;/listinfo/openembedded-core'>openembedded-core</ulink> mailing list.
> +                For example, a change to anything under the <filename>meta</filename> or
> +                <filename>scripts</filename> directories
> +                should be sent to this mailing list.</para></listitem>
> +            <listitem><para>For changes to BitBake (anything under the <filename>bitbake</filename>
> +                directory), send your patch to the
> +                <ulink url='&OE_LISTS_URL;/listinfo/bitbake-devel'>bitbake-devel</ulink> mailing list.</para></listitem>
> +            <listitem><para>For changes to <filename>meta-yocto</filename>, send your patch to the
> +                <ulink url='&YOCTO_LISTS_URL;/listinfo/poky'>poky</ulink> mailing list.</para></listitem>
> +            <listitem><para>For changes to other layers hosted on yoctoproject.org (unless the
> +                layer's documentation specifies otherwise), tools, and Yocto Project
> +                documentation, use the
> +                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> mailing list.</para></listitem>
> +            <listitem><para>For additional recipes that do not fit into the core metadata,
> +                you should determine which layer the recipe should go into and submit the
> +                change in the manner recommended by the documentation (e.g. README) supplied
> +                with the layer. If in doubt, please ask on the
> +                <ulink url='&YOCTO_LISTS_URL;/listinfo/yocto'>yocto</ulink> or
> +                <ulink url='&OE_LISTS_URL;/listinfo/openembedded-devel'>openembedded-devel</ulink>
> +                mailing lists.</para></listitem>
>          </itemizedlist>      
>      </para>
>  
>      <para>  
>          When you send a patch, be sure to include a "Signed-off-by:"
>          line in the same style as required by the Linux kernel. 
> -        Adding this line signifies the developer has agreed to the Developer's Certificate of Origin 1.1
> +        Adding this line signifies that you, the submitter, have agreed to the Developer's Certificate of Origin 1.1
>          as follows:
>          <literallayout class='monospaced'>
>       Developer's Certificate of Origin 1.1
> @@ -931,52 +930,52 @@
>           maintained indefinitely and may be redistributed consistent with
>           this project or the open source license(s) involved.
>          </literallayout>
> -        A Poky contributions tree (<filename>poky-contrib</filename>, 
> -        <filename>git://git.yoctoproject.org/poky-contrib.git</filename>)
> -        exists for contributors to stage contributions.
> -        If people desire such access, please ask on the mailing list. 
> -        Usually, the Yocto Project team will grant access to anyone with a proven track 
> -        record of good patches.
>      </para>
>  
>      <para>
>          In a collaborative environment, it is necessary to have some sort of standard 
>          or method through which you submit changes.  
>          Otherwise, things could get quite chaotic.
> -        One general practice to follow is to make small, controlled changes to the 
> -        Yocto Project.
> -        Keeping changes small and isolated lets you best keep pace with future Yocto Project changes.
> +        One general practice to follow is to make small, controlled changes.
> +        Keeping changes small and isolated aids review, makes merging/rebasing easier
> +        and keeps the change history clean when anyone needs to refer to it in future.
>      </para>
>  
>      <para>
> -        When you create a commit, you must follow certain standards established by the
> -        Yocto Project development team. 
> -        For each commit, you must provide a single-line summary of the change and you 
> -        almost always provide a more detailed description of what you did (i.e. the body 
> -        of the commit).
> +        When you make a commit, you must follow certain standards established by the
> +        OpenEmbedded and Yocto Project development teams.
> +        For each commit, you must provide a single-line summary of the change and you
> +        should almost always provide a more detailed description of what you did (i.e.
> +        the body of the commit message).
>          The only exceptions for not providing a detailed description would be if your 
>          change is a simple, self-explanatory change that needs no description.
> -        Here are the Yocto Project commit message guidelines:
> +        Here are the guidelines for composing a commit message:
>          <itemizedlist>
>              <listitem><para>Provide a single-line, short summary of the change.
> -                This summary is typically viewable by source control systems.
> +                This summary is typically viewable in the "shortlist" of changes.
>                  Thus, providing something short and descriptive that gives the reader 
>                  a summary of the change is useful when viewing a list of many commits.
> +                This should be prefixed by the recipe name (if changing a recipe), or
> +                else the short form path to the file being changed.
>                  </para></listitem>
>              <listitem><para>For the body of the commit message, provide detailed information
>                  that describes what you changed, why you made the change, and the approach
> -                you used.  
> +                you used. It may also be helpful if you mention how you tested the change.
>                  Provide as much detail as you can in the body of the commit message.
>                  </para></listitem>
>              <listitem><para>If the change addresses a specific bug or issue that is 
> -                associated with a bug-tracking ID, prefix your detailed description
> -                with the bug or issue ID.  
> -                For example, the Yocto Project tracks bugs using a bug-naming convention.
> -                Any commits that address a bug must start with the bug ID in the description
> -                as follows:
> +                associated with a bug-tracking ID, include a reference to that ID in
> +                your detailed description.
> +                For example, the Yocto Project uses a specific convention for bug
> +                references - any commit that addresses a specific bug should include the
> +                bug ID in the description (typically at the end) as follows:
>                  <literallayout class='monospaced'>
> -     YOCTO #&lt;bug-id&gt;:  &lt;Detailed description of commit&gt;
> +     &lt;detailed description of change&gt;
> +
> +     [YOCTO #&lt;bug-id&gt;]
>                  </literallayout></para></listitem>
> +                Where &lt;bug-id&gt; is replaced with the specific bug ID from the
> +                Yocto Project Bugzilla instance.
>          </itemizedlist>
>      </para>
>  
> @@ -997,11 +996,11 @@
>              The basic flow for pushing a change to an upstream "contrib" Git repository is as follows:
>              <itemizedlist>
>                  <listitem><para>Make your changes in your local Git repository.</para></listitem>
> -                <listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
> -                    command.</para></listitem>
> +                <listitem><para>Stage your changes by using the <filename>git add</filename>
> +                    command on each file you changed.</para></listitem>
>                  <listitem><para>Commit the change by using the <filename>git commit</filename>
>                      command and push it to the "contrib" repository.  
> -                    Be sure to provide a commit message that follows the project’s commit standards
> +                    Be sure to provide a commit message that follows the project’s commit message standards
>                      as described earlier.</para></listitem>
>                  <listitem><para>Notify the maintainer that you have pushed a change by making a pull 
>                      request.
> @@ -1012,10 +1011,10 @@
>                      You can find these scripts in the <filename>scripts</filename> directory of the 
>                      Yocto Project file structure.</para>
>                      <para>For help on using these scripts, simply provide the 
> -                    <filename>--help</filename> argument as follows:
> +                    <filename>-h</filename> argument as follows:
>                      <literallayout class='monospaced'>
> -     $ ~/poky/scripts/create-pull-request --help
> -     $ ~/poky/scripts/send-pull-request --help
> +     $ ~/poky/scripts/create-pull-request -h
> +     $ ~/poky/scripts/send-pull-request -h
>                      </literallayout></para></listitem>
>              </itemizedlist>
>          </para>
> @@ -1035,8 +1034,8 @@
>              Here is a general procedure:
>              <itemizedlist>
>                  <listitem><para>Make your changes in your local Git repository.</para></listitem>
> -                <listitem><para>Stage your commit (or change) by using the <filename>git add</filename>
> -                    command.</para></listitem>
> +                <listitem><para>Stage your changes by using the <filename>git add</filename>
> +                    command on each file you changed.</para></listitem>
>                  <listitem><para>Commit the change by using the 
>                      <filename>git commit --signoff</filename> command.
>                      Using the <filename>--signoff</filename> option identifies you as the person 
> 

-- 
Darren Hart
Intel Open Source Technology Center
Yocto Project - Linux Kernel

Re: [yocto-docs] [PATCH 2/5] dev-manual: tidy up "How to Submit a Change" section

[Paul Eggleton]

On Monday 02 July 2012 08:55:33 Darren Hart wrote:
> On 07/02/2012 02:54 AM, Paul Eggleton wrote:
> > * 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
> 
> That fixes Bug 2671, consider adding the tag to the commit header.

Ah yes, I forgot there was a bug open for this. I've updated the branch to 
include the bug reference.

Thanks,
Paul

-- 

Paul Eggleton
Intel Open Source Technology Centre