Bug 397665: "Assigning Group Controls to Products" doesn't explain editcomponents, canconfirm, editbugs

Patch by Sam Folk-Williams <sam.folkwilliams@gmail.com>; r=me, r=lpsolit

1 files changed, 148 insertions, 82 deletions

diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index e07c2ec41..a0c7a7c8b 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -673,43 +673,165 @@
     <para>
     <glossterm linkend="gloss-product" baseform="product">
     Products</glossterm>
-
     tend to represent real-world
     shipping products. E.g. if your company makes computer games, 
-    you should have one product per game, perhaps a "Common" product for 
-    units of technology used in multiple games, and maybe a few special
-     products (Website, Administration...)</para>
+    you should have one product per game, perhaps a 
+    <quote>Common</quote> product for units of technology used 
+    in multiple games, and maybe a few special products 
+    (Website, Administration...)
+    </para>
 
-    <para>Many of Bugzilla's settings are configurable on a per-product
-    basis. The number of "votes" available to users is set per-product, 
-    as is the number of votes
-    required to move a bug automatically from the UNCONFIRMED status to the
-    NEW status.</para>
+    <para>
+    Many of Bugzilla's settings are configurable on a per-product
+    basis. The number of <quote>votes</quote> available to 
+    users is set per-product, as is the number of votes
+    required to move a bug automatically from the UNCONFIRMED 
+    status to the NEW status.
+    </para>
 
-    <para>To create a new product:</para>
+    <para>
+    To create a new product:
+    </para>
 
     <orderedlist>
       <listitem>
-        <para>Select "products" from the footer</para>
+        <para> 
+        Select <quote>Adminstration</quote> from the footer and then
+        choose <quote>Products</quote> from the main administration page.
+        </para>
 
       </listitem>
 
       <listitem>
-        <para>Select the "Add" link in the bottom right</para>
+        <para>
+        Select the <quote>Add</quote> link in the bottom right.
+        </para>
       </listitem>
 
       <listitem>
-        <para>Enter the name of the product and a description. The
-        Description field may contain HTML.</para>
+        <para>
+        Enter the name of the product and a description. The
+        Description field may contain HTML.
+        </para>
       </listitem>
     </orderedlist>
 
-    <para>Don't worry about the "Closed for bug entry", "Maximum Votes
-    per person", "Maximum votes a person can put on a single bug",
-    "Number of votes a bug in this Product needs to automatically get out
-    of the UNCONFIRMED state", and "Version" options yet. We'll cover
-    those in a few moments.
-    </para>
+
+<section>
+      <title>Assigning Group Controls to Products</title>
+      <para> 
+      On the <quote>Product Edit</quote> page, 
+      there is a link called 
+      <quote>Edit Group Access Controls</quote>. 
+      The settings on this page control the relationship 
+      of the groups to the product being edited.
+      </para> 
+      <para>
+      Groups may be applicable, default, and 
+      mandatory for each product. Groups can also control access 
+      to bugs for a given product, or be used to make bugs 
+      for a product totally read-only unless the group 
+      restrictions are met.
+      </para>
+      <para>
+      If any group has <emphasis>Entry</emphasis> selected, then the 
+      product will restrict bug entry to only those users 
+      who are members of all the groups with 
+      <emphasis>Entry</emphasis> selected.
+      </para>
+      <para>
+      If any group has <emphasis>Canedit</emphasis> selected, 
+      then the product will be read-only for any users 
+      who are not members of all of the groups with
+      <emphasis>Canedit</emphasis> selected. ONLY users who 
+      are members of all the <emphasis>Canedit</emphasis> groups 
+      will be able to edit. This is an 
+      additional restriction that further limits 
+      what can be edited by a user.
+      </para>
+      <para>
+      The following settings let you 
+      choose privileges on a <emphasis>per-product basis</emphasis>.
+      This is a convenient way to give privileges to 
+      some users for some products only, without having 
+      to give them global privileges which would affect 
+      all products.
+      </para>
+      <para>
+      Any group having <emphasis>editcomponents</emphasis> 
+      selected  allows users who are in this group to edit all 
+      aspects of this product, including components, milestones 
+      and versions.
+      </para>
+      <para>
+      Any group having <emphasis>canconfirm</emphasis> selected 
+      allows users who are in this group to confirm bugs 
+      in this product.
+      </para>
+      <para>
+      Any group having <emphasis>editbugs</emphasis> selected allows 
+      users who are in this group to edit all fields of 
+      bugs in this product.
+      </para>
+      <para>
+      The <emphasis>MemberControl</emphasis> and 
+      <emphasis>OtherControl</emphasis> fields indicate which 
+      bugs will be placed in this group according 
+      to the following definitions.
+      </para>
+      <para>
+      For each group, it is possible to specify if 
+      membership in that group is:
+      </para>
+      <orderedlist>
+        <listitem>
+          <para>
+          Required for bug entry. 
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+          Not applicable to this product(NA),
+          a possible restriction for a member of the 
+          group to place on a bug in this product(Shown),
+          a default restriction for a member of the 
+          group to place on a bug in this product(Default),
+          or a mandatory restriction to be placed on bugs 
+          in this product(Mandatory).
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+          Not applicable by non-members to this product(NA),
+          a possible restriction for a non-member of the 
+          group to place on a bug in this product(Shown),
+          a default restriction for a non-member of the 
+          group to place on a bug in this product(Default),
+          or a mandatory restriction to be placed on bugs 
+          in this product when entered by a non-member(Mandatory).
+          </para>
+        </listitem>
+        <listitem>
+          <para>
+          Required in order to make <emphasis>any</emphasis> change
+          to bugs in this product <emphasis>including comments.</emphasis>
+          </para>
+        </listitem>
+      </orderedlist>
+      <para>These controls are often described in this order, so a 
+      product that requires a user to be a member of group "foo" 
+      to enter a bug and then requires that the bug stay restricted
+      to group "foo" at all times and that only members of group "foo"
+      can edit the bug even if they otherwise could see the bug would 
+      have its controls summarized by...</para>
+      <programlisting> 
+foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
+      </programlisting>
+      
+    </section>
+
+
+
   </section>
 
   <section id="components">
@@ -1645,70 +1767,14 @@
         </listitem>
       </orderedlist>
     </section>
-    
     <section>
-      <title>Assigning Group Controls to Products</title>
-      <para>
-      On the product edit page, there is a page to edit the 
-      <quote>Group Controls</quote> 
-      for a product. This  allows you to 
-      configure how a group relates to the product. 
-      Groups may be applicable, default, 
-      and mandatory as well as used to control entry 
-      or used to make bugs in the product
-      totally read-only unless the group restrictions are met. 
-      </para>
-      
-      <para>
-      For each group, it is possible to specify if membership in that
-      group is...
-      </para>
-      <orderedlist>
-        <listitem>
-          <para>
-          required for bug entry, 
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-          Not applicable to this product(NA),
-          a possible restriction for a member of the 
-          group to place on a bug in this product(Shown),
-          a default restriction for a member of the 
-          group to place on a bug in this product(Default),
-          or a mandatory restriction to be placed on bugs 
-          in this product(Mandatory).
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-          Not applicable by non-members to this product(NA),
-          a possible restriction for a non-member of the 
-          group to place on a bug in this product(Shown),
-          a default restriction for a non-member of the 
-          group to place on a bug in this product(Default),
-          or a mandatory restriction to be placed on bugs 
-          in this product when entered by a non-member(Mandatory).
-          </para>
-        </listitem>
-        <listitem>
-          <para>
-          required in order to make <emphasis>any</emphasis> change
-          to bugs in this product <emphasis>including comments.</emphasis>
-          </para>
-        </listitem>
-      </orderedlist>
-      <para>These controls are often described in this order, so a 
-      product that requires a user to be a member of group "foo" 
-      to enter a bug and then requires that the bug stay restricted
-      to group "foo" at all times and that only members of group "foo"
-      can edit the bug even if they otherwise could see the bug would 
-      have its controls summarized by...</para>
-      <programlisting> 
-foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
-      </programlisting>
-      
+     <title>Assigning Group Controls to Products</title>
+     <para>
+     For information on assigning group controls to
+     products, see <xref linkend="products" />.
+     </para>
     </section>
+    
     <section>
     <title>Common Applications of Group Controls</title>
       <section>