From: lpsolit%gmail.com <>
Date: Wed, 22 Nov 2006 04:45:50 +0000 (+0000)
Subject: Documentation for bug 180879: flags changes can be restricted to a grant and request... 
X-Git-Tag: bugzilla-2.20.4~15
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=530db5be56f5fe04bf1af406c85efbb1f1de76c4;p=thirdparty%2Fbugzilla.git

Documentation for bug 180879: flags changes can be restricted to a grant and request groups - Patch by me, r=myk
---

diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index 1fa3359aa0..5d991baece 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -844,15 +844,15 @@
    <section id="flag-askto">
      <title>Using flag requests</title>
      <para>
-       If a flag has been defined as 'requestable', 
-       users are allowed to set the flag's status to <quote>?</quote>.
-       This status indicates that someone (aka <quote>the requester</quote> is asking
-       for someone else to set the flag to either <quote>+</quote> or <quote>-</quote>.
+       If a flag has been defined as 'requestable', and a user has enough privileges
+       to request it (see below), the user can set the flag's status to <quote>?</quote>.
+       This status indicates that someone (a.k.a. <quote>the requester</quote>) is asking
+       someone else to set the flag to either <quote>+</quote> or <quote>-</quote>.
      </para>
      <para>
        If a flag has been defined as 'specifically requestable', 
        a text box will appear next to the flag into which the requester may
-       enter a Bugzilla username. That named person (aka <quote>the requestee</quote>)
+       enter a Bugzilla username. That named person (a.k.a. <quote>the requestee</quote>)
        will receive an email notifying them of the request, and pointing them
        to the bug/attachment in question.
      </para>
@@ -890,8 +890,7 @@
        </para>
 
        <para>
-         For a Bugzilla user, attachment flags show up in two 
-         places:
+         For a Bugzilla user, attachment flags show up in three places:
          <orderedlist>
            <listitem>
              <para>
@@ -910,6 +909,14 @@
               screen is where you set flags to ?, -, +, or unset them.
              </para>
            </listitem>
+           <listitem>
+             <para>
+               Requests are listed in the <quote>Request Queue</quote>, which
+               is accessible from the <quote>My Requests</quote> link (if you are
+               logged in) or <quote>Requests</quote> link (if you are logged out)
+               visible in the footer of all pages.
+             </para>
+           </listitem>
          </orderedlist>
        </para>
 
@@ -920,14 +927,13 @@
 
        <para>
          Bug flags are used to set a status on the bug itself. You can 
-         see Bug Flags in the <quote>Show Bug</quote> screen 
-         (<filename>editbug.cgi</filename>).
+         see Bug Flags in the <quote>Show Bug</quote> and <quote>Requests</quote>
+         screens, as described above.
        </para>
        <para>
-         Only users with the ability to edit the bug may 
-         set flags on bugs. This includes the assignee, reporter, and 
-         any user with the <computeroutput>editbugs</computeroutput> 
-         permission.
+         Only users with enough privileges (see below) may set flags on bugs.
+         This doesn't necessarily include the assignee, reporter, or users with the
+         <computeroutput>editbugs</computeroutput> permission.
        </para>
      </section>
 
@@ -962,17 +968,18 @@
           <para>
             This is the name of the flag. This will be displayed 
             to Bugzilla users who are looking at or setting the flag. 
-            The name may consist of any valid Unicode character. 
+            The name may contain any valid Unicode characters except commas
+            and spaces.
           </para>
         </section>
 
         <section id="flags-create-field-description">
           <title>Description</title>
           <para>
-            This describes the flag in more detail. At present, this doesn't
-            show up anywhere helpful; ideally, it would be nice to have
-            it show up as a tooltip. This field 
-            can be as long as you like, and can contain any character you want.
+            The description describes the flag in more detail. It is visible
+            in a tooltip when hovering over a flag either in the <quote>Show Bug</quote>
+            or <quote>Edit Attachment</quote> pages. This field can be as
+            long as you like, and can contain any character you want.
           </para>
         </section>
 
@@ -1018,9 +1025,9 @@
 
           <para>
             You may select a Product without selecting a specific Component,
-            but it is illegal to select a Component without a Product, or to select a
-            Component that does not belong to the named Product. Doing so as of
-            this writing (2.18rc3) will raise an error... even if all your products
+            but you can't select a Component without a Product, or to select a
+            Component that does not belong to the named Product. If you do so,
+            Bugzilla will display an error message, even if all your products
             have a component by that name.
           </para>
 
@@ -1076,16 +1083,6 @@
           </para>
         </section>
 
-        <section id="flags-create-field-cclist">
-          <title>CC List</title>
-
-          <para>
-            If you want certain users to be notified every time this flag is 
-            set to ?, -, +, or unset, add them here. This is a comma-separated 
-            list of email addresses that need not be restricted to Bugzilla usernames..
-          </para>
-        </section>
-
         <section id="flags-create-field-specific">
           <title>Specifically Requestable</title>
           <para>
@@ -1109,6 +1106,38 @@
           </para>
         </section>
 
+	<section id="flags-create-field-cclist">
+          <title>CC List</title>
+
+          <para>
+            If you want certain users to be notified every time this flag is 
+            set to ?, -, +, or unset, add them here. This is a comma-separated 
+            list of email addresses that need not be restricted to Bugzilla usernames.
+          </para>
+        </section>
+
+        <section id="flags-create-grant-group">
+          <title>Grant Group</title>
+          <para>
+            When this field is set to some given group, only users in the group
+            can set the flag to <quote>+</quote> and <quote>-</quote>. This
+            field does not affect who can request or cancel the flag. For that,
+            see the <quote>Request Group</quote> field below. If this field
+            is left blank, all users can set or delete this flag. This field is
+            useful for restricting which users can approve or reject requests.
+          </para>
+        </section>
+
+        <section id="flags-create-request-group">
+          <title>Request Group</title>
+          <para>
+            When this field is set to some given group, only users in the group
+            can request or cancel this flag. Note that this field has no effect
+            if the <quote>grant group</quote> field is empty. You can set the
+            value of this field to a different group, but both fields have to be
+            set to a group for this field to have an effect.
+          </para>
+        </section>
       </section> <!-- flags-create -->
 
       <section id="flags-delete">