dev-manual, ref-manual: Reorganized Bugzilla information

Fixes [YOCTO #11630]

Reorganized the way the information about entering bugs using
Bugzilla is arranged in the documentation set.  The dev-manual now
has a section that is purely procedural and steps the user through
the process of logging a new bug in the Bugzilla system.  The
ref-manual has a conceptual section that introduces the YP
implementation of Bugzilla by simply telling the user what it is
and what what its purpose is.

(From yocto-docs rev: 4bfba345010be7bc2866b819b9754bb06f93c91f)

Signed-off-by: Scott Rifenbark <srifenbark@gmail.com>
Signed-off-by: Richard Purdie <richard.purdie@linuxfoundation.org>

3 files changed, 114 insertions, 56 deletions

diff --git a/documentation/dev-manual/dev-manual-newbie.xml b/documentation/dev-manual/dev-manual-newbie.xml
index 4b039544b9..00b8c44801 100644
--- a/documentation/dev-manual/dev-manual-newbie.xml
+++ b/documentation/dev-manual/dev-manual-newbie.xml
@@ -1323,63 +1323,88 @@
     </para>
 </section>
 
-<section id='tracking-bugs'>
-    <title>Tracking Bugs</title>
+<section id='submitting-a-defect-against-the-yocto-project'>
+    <title>Submitting a Defect Against the Yocto Project</title>
 
     <para>
-        The Yocto Project uses its own implementation of
-        <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track bugs.
-        Implementations of Bugzilla work well for group development because they track bugs and code
-        changes, can be used to communicate changes and problems with developers, can be used to
-        submit and review patches, and can be used to manage quality assurance.
-        The home page for the Yocto Project implementation of Bugzilla is
-        <ulink url='&YOCTO_BUGZILLA_URL;'>&YOCTO_BUGZILLA_URL;</ulink>.
+        Use the Yocto Project implementation of
+        <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink>
+        to submit a defect (bug) against the Yocto Project.
+        For additional information on this implementation of Bugzilla see the
+        "<ulink url='&YOCTO_DOCS_REF_URL;#resources-bugtracker'>Yocto Project Bugzilla</ulink>"
+        section in the Yocto Project Reference Manual.
+        For more detail on any of the following steps, see the Yocto Project
+        <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>.
     </para>
 
     <para>
-        Sometimes it is helpful to submit, investigate, or track a bug against the Yocto Project itself
-        such as when discovering an issue with some component of the build system that acts contrary
-        to the documentation or your expectations.
-        Following is the general procedure for submitting a new bug using the Yocto Project
-        Bugzilla.
-        You can find more information on defect management, bug tracking, and feature request
-        processes all accomplished through the Yocto Project Bugzilla on the
-        <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>.
+        Use the following general steps to submit a bug"
+
         <orderedlist>
-            <listitem><para>Always use the Yocto Project implementation of Bugzilla to submit
-                a bug.</para></listitem>
-            <listitem><para>When submitting a new bug, be sure to choose the appropriate
-                Classification, Product, and Component for which the issue was found.
-                Defects for the Yocto Project fall into one of seven classifications:
-                Yocto Project Components, Infrastructure, Build System &amp; Metadata,
-                Documentation, QA/Testing, Runtime and Hardware.
-                Each of these Classifications break down into multiple Products and, in some
-                cases, multiple Components.</para></listitem>
-            <listitem><para>Use the bug form to choose the correct Hardware and Architecture
-                for which the bug applies.</para></listitem>
-            <listitem><para>Indicate the Yocto Project version you were using when the issue
-                occurred.</para></listitem>
-            <listitem><para>Be sure to indicate the Severity of the bug.
-                Severity communicates how the bug impacted your work.</para></listitem>
-            <listitem><para>Select the appropriate "Documentation change" item
-                for the bug.
-                Fixing a bug may or may not affect the Yocto Project
-                documentation.</para></listitem>
-            <listitem><para>Provide a brief summary of the issue.
-                Try to limit your summary to just a line or two and be sure to capture the
-                essence of the issue.</para></listitem>
-            <listitem><para>Provide a detailed description of the issue.
-                You should provide as much detail as you can about the context, behavior, output,
-                and so forth that surrounds the issue.
+            <listitem><para>
+                Open the Yocto Project implementation of
+                <ulink url='&YOCTO_BUGZILLA_URL;'>Bugzilla</ulink>.
+                </para></listitem>
+            <listitem><para>
+                Click "File a Bug" to enter a new bug.
+                </para></listitem>
+            <listitem><para>
+                Choose the appropriate "Classification", "Product", and
+                "Component" for which the bug was found.
+                Bugs for the Yocto Project fall into one of several
+                classifications, which in turn break down into several
+                products and components.
+                For example, for a bug against the
+                <filename>meta-intel</filename> layer, you would choose
+                "Build System, Metadata &amp; Runtime", "BSPs", and
+                "bsps-meta-intel", respectively.
+                </para></listitem>
+            <listitem><para>
+                Choose the "Version" of the Yocto Project for which you found
+                the bug (e.g. &DISTRO;).
+                </para></listitem>
+            <listitem><para>
+                Determine and select the "Severity" of the bug.
+                The severity indicates how the bug impacted your work.
+                </para></listitem>
+            <listitem><para>
+                Choose the "Hardware" that the bug impacts.
+                </para></listitem>
+            <listitem><para>
+                Choose the "Architecture" that the bug impacts.
+                </para></listitem>
+            <listitem><para>
+                Choose a "Documentation change" item for the bug.
+                Fixing a bug might or might not affect the Yocto Project
+                documentation.
+                If you are unsure of the impact to the documentation, select
+                "Don't Know".
+                </para></listitem>
+            <listitem><para>
+                Provide a brief "Summary" of the bug.
+                Try to limit your summary to just a line or two and be sure
+                to capture the essence of the bug.
+                </para></listitem>
+            <listitem><para>
+                Provide a detailed "Description" of the bug.
+                You should provide as much detail as you can about the context,
+                behavior, output, and so forth that surrounds the bug.
                 You can even attach supporting files for output from logs by
-                using the "Add an attachment" button.</para></listitem>
-            <listitem><para>Be sure to copy the appropriate people in the
-                "CC List" for the bug.
-                See the "<link linkend='how-to-submit-a-change'>How to Submit a Change</link>"
-                section for information about finding out who is responsible
-                for code.</para></listitem>
-            <listitem><para>Submit the bug by clicking the "Submit Bug" button.</para></listitem>
+                using the "Add an attachment" button.
+                </para></listitem>
+            <listitem><para>
+                Click the "Submit Bug" button submit the bug.
+                A new Bugzilla number is assigned to the bug and the defect
+                is logged in the bug tracking system.
+                </para></listitem>
         </orderedlist>
+        Once you file a bug, the bug is processed by the Yocto Project Bug
+        Triage Team and further details concerning the bug are assigned
+        (e.g. priority and owner).
+        You are the "Submitter" of the bug and any further categorization,
+        progress, or comments on the bug result in Bugzilla sending you an
+        automated email concerning the particular change or progress to the
+        bug.
     </para>
 </section>
 
@@ -1551,7 +1576,8 @@
                     </literallayout>
                     Just provide the name of the file for which you are interested.
                     The information returned is not ordered by history but does
-                    include a list of all committers grouped by name.
+                    include a list of everyone who has committed grouped by
+                    name.
                     From the list, you can see who is responsible for the bulk of
                     the changes against the file.
                     </para></listitem>
diff --git a/documentation/ref-manual/resources.xml b/documentation/ref-manual/resources.xml
index 8299f9f3ca..0cd0e5a254 100644
--- a/documentation/ref-manual/resources.xml
+++ b/documentation/ref-manual/resources.xml
@@ -17,11 +17,41 @@
 </section>
 
 <section id='resources-bugtracker'>
-    <title>Tracking Bugs</title>
+    <title>Yocto Project Bugzilla</title>
 
     <para>
-        If you find problems with the Yocto Project, you should report them using the
-        Bugzilla application at <ulink url='&YOCTO_BUGZILLA_URL;'></ulink>.
+        The Yocto Project uses its own implementation of
+        <ulink url='http://www.bugzilla.org/about/'>Bugzilla</ulink> to track
+        defects (bugs).
+        Implementations of Bugzilla work well for group development because
+        they track bugs and code changes, can be used to communicate changes
+        and problems with developers, can be used to submit and review patches,
+        and can be used to manage quality assurance.
+    </para>
+
+    <para>
+        Sometimes it is helpful to submit, investigate, or track a bug against
+        the Yocto Project itself (e.g. when discovering an issue with some
+        component of the build system that acts contrary to the documentation
+        or your expectations).
+    </para>
+
+    <para>
+        A general procedure and guidelines exist for when you use Bugzilla to
+        submit a bug.
+        For information on how to use Bugzilla to submit a bug against the
+        Yocto Project, see the following:
+        <itemizedlist>
+            <listitem><para>
+                The
+                "<ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
+                section in the Yocto Project Development Manual.
+                </para></listitem>
+            <listitem><para>
+                The Yocto Project
+                <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>Bugzilla wiki page</ulink>
+                </para></listitem>
+        </itemizedlist>
     </para>
 </section>
 
diff --git a/documentation/ref-manual/usingpoky.xml b/documentation/ref-manual/usingpoky.xml
index d08031617b..4e97e3ec02 100644
--- a/documentation/ref-manual/usingpoky.xml
+++ b/documentation/ref-manual/usingpoky.xml
@@ -1031,9 +1031,11 @@
                     the Yocto Project implementation of
                     <ulink url='https://bugzilla.yoctoproject.org/'>Bugzilla</ulink>.
                     For general information on how to submit a bug against
-                    the Yocto Project, see the
-                    "<ulink url='&YOCTO_DOCS_DEV_URL;#tracking-bugs'>Tracking Bugs</ulink>"
-                    section in the Yocto Project Development Manual.
+                    the Yocto Project, see the Yocto Project Bugzilla
+                    <ulink url='&YOCTO_WIKI_URL;/wiki/Bugzilla_Configuration_and_Bug_Tracking'>wiki page</ulink>"
+                    or the
+                    <ulink url='&YOCTO_DOCS_DEV_URL;#submitting-a-defect-against-the-yocto-project'>Submitting a Defect Against the Yocto Project</ulink>"
+                    section, which is in the Yocto Project Development Manual.
                     <note>
                         The manuals might not be the right place to document
                         variables that are purely internal and have a limited