Bug 168804 - Document CheckCanChangeField so sites can modify it for local needs. Patch by gerv; r=bbaetz, joel.

1 files changed, 795 insertions, 595 deletions

diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml
index 12c72dd84..a82a659bf 100644
--- a/docs/en/xml/administration.xml
+++ b/docs/en/xml/administration.xml
@@ -38,24 +38,27 @@
 
       <step>
         <para>
-        <command>makeproductgroups</command>:
-        This dictates whether or not to automatically create groups
-        when new products are created.
-        </para>
+        <command>usebuggroups</command>:
+        This dictates whether or not to implement group-based security for
+        Bugzilla. If set, Bugzilla bugs can have an associated 'group',
+        defining which users are allowed to see and edit the
+        bug.</para>
+
+        <para>Set "usebuggroups" to "on" 
+        <emphasis>only</emphasis>
+        if you may wish to restrict access to particular bugs to certain
+        groups of users. I suggest leaving
+        this parameter <emphasis>off</emphasis>
+        while initially testing your Bugzilla.</para>
       </step>
 
       <step>
         <para>
-        <command>useentrygroupdefault</command>:
-        Bugzilla products can have a group associated with them, so that
-        certain users can only see bugs in certain products. When this 
-        parameter is set to <quote>on</quote>, this 
-        causes the initial group controls on newly created products 
-        to place all newly-created bugs in the group 
-        having the same name as the product immediately.
-        After a product is initially created, the group controls
-        can be further adjusted without interference by 
-        this mechanism.</para>
+        <command>usebuggroupsentry</command>:
+        Bugzilla Products can have a group associated with them, so that
+        certain users can only see bugs in certain products. When this parameter
+        is set to <quote>on</quote>, this places all newly-created bugs in the
+        group for their product immediately.</para>
       </step>
 
       <step>
@@ -66,14 +69,8 @@
         write locking. What this means is that if someone needs to make a
         change to a bug, they will lock the entire table until the operation
         is complete. Locking for write also blocks reads until the write is
-        complete. Note that more recent versions of mysql support row level
-        locking using different table types. These types are slower than the
-        standard type, and Bugzilla does not yet take advantage of features
-        such as transactions which would justify this speed decrease. The
-        Bugzilla team are, however, happy to hear about any experiences with
-        row level locking and Bugzilla.</para>
-
-        <para>The <quote>shadowdb</quote>
+        complete. The 
+        <quote>shadowdb</quote>
         parameter was designed to get around this limitation. While only a
         single user is allowed to write to a table at a time, reads can
         continue unimpeded on a read-only shadow copy of the database.
@@ -82,16 +79,29 @@
         high-traffic Bugzilla databases.</para>
         
         <para>
-        As a guide, on reasonably old hardware, mozilla.org began needing 
+        As a guide, mozilla.org began needing 
         <quote>shadowdb</quote>
         when they reached around 40,000 Bugzilla users with several hundred
         Bugzilla bug changes and comments per day.</para>
 
         <para>The value of the parameter defines the name of the 
-        shadow bug database. You will need to set the host and port settings
-        from the params page, and set up replication in your database server
-        so that updates reach this readonly mirror. Consult your database
-        documentation for more detail.</para>
+        shadow bug database. 
+        Set "shadowdb" to e.g. "bug_shadowdb" if you will be running a
+        *very* large installation of Bugzilla. 
+        <note>
+          <para>Enabling "shadowdb" can adversely affect the stability of
+          your installation of Bugzilla. You should regularly check that your
+          database is in sync. It is often advisable to force a shadow
+          database sync nightly via 
+          <quote>cron</quote>.
+          </para>
+        </note>
+        </para>
+        
+        <para>If you use the "shadowdb" option, it is only natural that you
+        should turn the "queryagainstshadowdb" option on as well. Otherwise
+        you are replicating data into a shadow database for no reason!</para>
+
       </step>
 
       <step>
@@ -119,19 +129,6 @@
         blurb about how to use Bugzilla at your site.</para>
       </step>
 
-
-      <step>
-        <para>
-	<command>movebugs</command>:
-
-	This option is an undocumented feature to allow moving bugs
-	between separate Bugzilla installations.  You will need to understand
-	the source code in order to use this feature.  Please consult
-	<filename>movebugs.pl</filename> in your Bugzilla source tree for
-	further documentation, such as it is.
-	</para>
-      </step>
-
       <step>
         <para>
         <command>useqacontact</command>:
@@ -215,11 +212,33 @@
       you for this username and password.</para>
 
       <tip>
-        <para>If you wish to add more administrative users, add them to 
-        the "admin" group and, optionally, add edit the tweakparams, editusers,
-        creategroups, editcomponents, and editkeywords groups to add the
-        entire admin group to those groups.
+        <para>If you wish to add more administrative users, you must use the
+        MySQL interface. Run "mysql" from the command line, and use these
+        commands: 
+        <simplelist>
+          <member>
+            <prompt>mysql&gt;</prompt>
+            <command>use bugs;</command>
+          </member>
+
+          <member>
+            <prompt>mysql&gt;</prompt>
+
+            <command>
+              update profiles set groupset=0x7ffffffffffffff where login_name =
+              "(user's login name)";
+            </command>
+          </member>
+        </simplelist>
         </para>
+
+        <para>Yes, that is 
+        <emphasis>fourteen</emphasis>
+
+        <quote>f</quote>
+
+        's. A whole lot of f-ing going on if you want to create a new
+        administator.</para>
       </tip>
     </section>
 
@@ -321,7 +340,7 @@
             they attempt to perform these actions, and should explain
             why the account was disabled.
             <warning>
-              <para>Don't disable all the administrator accounts!</para>
+              <para>Don't disable the administrator account!</para>
             </warning>
 
             <note>
@@ -418,167 +437,178 @@
     </section>
   </section>
 
-  <section id="products">
-    <title>Products</title>
+  <section id="programadmin">
+    <title>Product, Component, Milestone, and Version Administration</title>
 
-    <para>
-    <glossterm linkend="gloss-product" baseform="product">
-    Products</glossterm>
+    <section id="products">
+      <title>Products</title>
 
-    are the broadest category in Bugzilla, and 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>
+      <para>
+      <glossterm linkend="gloss-product" baseform="product">
+      Products</glossterm>
 
-    <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>
+      are the broadest category in Bugzilla, and 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>
 
-    <para>To create a new product:</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>
 
-    <orderedlist>
-      <listitem>
-        <para>Select "products" from the footer</para>
+      <para>To create a new product:</para>
 
-      </listitem>
+      <orderedlist>
+        <listitem>
+          <para>Select "products" from the footer</para>
 
-      <listitem>
-        <para>Select the "Add" link in the bottom right</para>
-      </listitem>
+        </listitem>
 
-      <listitem>
-        <para>Enter the name of the product and a description. The
-        Description field may contain HTML.</para>
-      </listitem>
-    </orderedlist>
+        <listitem>
+          <para>Select the "Add" link in the bottom right</para>
+        </listitem>
 
-    <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 UNCOMFIRMED state", and "Version" options yet. We'll cover
-    those in a few moments.
-    </para>
-  </section>
+        <listitem>
+          <para>Enter the name of the product and a description. The
+          Description field may contain HTML.</para>
+        </listitem>
+      </orderedlist>
 
-  <section id="components">
-    <title>Components</title>
+      <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 UNCOMFIRMED state", and "Version" options yet. We'll cover
+      those in a few moments.
+      </para>
+    </section>
 
-    <para>Components are subsections of a Product. E.g. the computer game 
-    you are designing may have a "UI"
-    component, an "API" component, a "Sound System" component, and a
-    "Plugins" component, each overseen by a different programmer. It
-    often makes sense to divide Components in Bugzilla according to the
-    natural divisions of responsibility within your Product or
-    company.</para>
+    <section id="components">
+      <title>Components</title>
 
-    <para>
-    Each component has a owner and (if you turned it on in the parameters),
-    a QA Contact. The owner should be the primary person who fixes bugs in
-    that component. The QA Contact should be the person who will ensure
-    these bugs are completely fixed. The Owner, QA Contact, and Reporter
-    will get email when new bugs are created in this Component and when
-    these bugs change. Default Owner and Default QA Contact fields only
-    dictate the 
-    <emphasis>default assignments</emphasis>; 
-    these can be changed on bug submission, or at any later point in
-    a bug's life.</para>
-
-    <para>To create a new Component:</para>
+      <para>Components are subsections of a Product. E.g. the computer game 
+      you are designing may have a "UI"
+      component, an "API" component, a "Sound System" component, and a
+      "Plugins" component, each overseen by a different programmer. It
+      often makes sense to divide Components in Bugzilla according to the
+      natural divisions of responsibility within your Product or
+      company.</para>
+      
+      <para>
+      Each component has a owner and (if you turned it on in the parameters),
+      a QA Contact. The owner should be the primary person who fixes bugs in
+      that component. The QA Contact should be the person who will ensure
+      these bugs are completely fixed. The Owner, QA Contact, and Reporter
+      will get email when new bugs are created in this Component and when
+      these bugs change. Default Owner and Default QA Contact fields only
+      dictate the 
+      <emphasis>default assignments</emphasis>; 
+      these can be changed on bug submission, or at any later point in
+      a bug's life.</para>
+
+      <para>To create a new Component:</para>
 
-    <orderedlist>
-      <listitem>
-        <para>Select the "Edit components" link from the "Edit product"
-        page</para>
-      </listitem>
+      <orderedlist>
+        <listitem>
+          <para>Select the "Edit components" link from the "Edit product"
+          page</para>
+        </listitem>
 
-      <listitem>
-        <para>Select the "Add" link in the bottom right.</para>
-      </listitem>
+        <listitem>
+          <para>Select the "Add" link in the bottom right.</para>
+        </listitem>
 
-      <listitem>
-        <para>Fill out the "Component" field, a short "Description", 
-        the "Initial Owner" and "Initial QA Contact" (if enabled.) 
-        The Component and Description fields may contain HTML; 
-        the "Initial Owner" field must be a login name
-        already existing in the database. 
-        </para>
-      </listitem>
-    </orderedlist>
-  </section>
+        <listitem>
+          <para>Fill out the "Component" field, a short "Description", 
+          the "Initial Owner" and "Initial QA Contact" (if enabled.) 
+          The Component and Description fields may contain HTML; 
+          the "Initial Owner" field must be a login name
+          already existing in the database. 
+          </para>
+        </listitem>
+      </orderedlist>
+    </section>
 
-  <section id="versions">
-    <title>Versions</title>
+    <section id="versions">
+      <title>Versions</title>
 
-    <para>Versions are the revisions of the product, such as "Flinders
-    3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select
-    field; the usual practice is to select the earliest version known to have
-    the bug.
-    </para>
+      <para>Versions are the revisions of the product, such as "Flinders
+      3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select
+      field; the usual practice is to select the most recent version with
+      the bug.
+      </para>
 
-    <para>To create and edit Versions:</para>
+      <para>To create and edit Versions:</para>
 
-    <orderedlist>
-      <listitem>
-        <para>From the "Edit product" screen, select "Edit Versions"</para>
-      </listitem>
+      <orderedlist>
+        <listitem>
+          <para>From the "Edit product" screen, select "Edit Versions"</para>
+        </listitem>
 
-      <listitem>
-        <para>You will notice that the product already has the default
-        version "undefined". Click the "Add" link in the bottom right.</para>
-      </listitem>
+        <listitem>
+          <para>You will notice that the product already has the default
+          version "undefined". Click the "Add" link in the bottom right.</para>
+        </listitem>
 
-      <listitem>
-        <para>Enter the name of the Version. This field takes text only. 
-        Then click the "Add" button.</para>
-      </listitem>
+        <listitem>
+          <para>Enter the name of the Version. This field takes text only. 
+          Then click the "Add" button.</para>
+        </listitem>
 
-    </orderedlist>
-  </section>
+      </orderedlist>
+    </section>
 
-  <section id="milestones">
-    <title>Milestones</title>
+    <section id="milestones">
+      <title>Milestones</title>
 
-    <para>Milestones are "targets" that you plan to get a bug fixed by. For
-    example, you have a bug that you plan to fix for your 3.0 release, it
-    would be assigned the milestone of 3.0.</para>
+      <para>Milestones are "targets" that you plan to get a bug fixed by. For
+      example, you have a bug that you plan to fix for your 3.0 release, it
+      would be assigned the milestone of 3.0.</para>
 
-    <note>
-      <para>Milestone options will only appear for a Product if you turned
-      on the "usetargetmilestone" Param in the "Edit Parameters" screen.
-      </para>
-    </note>
+      <note>
+        <para>Milestone options will only appear for a Product if you turned
+        on the "usetargetmilestone" Param in the "Edit Parameters" screen.
+        </para>
+      </note>
 
-    <para>To create new Milestones, set Default Milestones, and set
-    Milestone URL:</para>
+      <para>To create new Milestones, set Default Milestones, and set
+      Milestone URL:</para>
 
-    <orderedlist>
-      <listitem>
-        <para>Select "Edit milestones" from the "Edit product" page.</para>
-      </listitem>
+      <orderedlist>
+        <listitem>
+          <para>Select "Edit milestones" from the "Edit product" page.</para>
+        </listitem>
 
-      <listitem>
-        <para>Select "Add" in the bottom right corner.
-        text</para>
-      </listitem>
+        <listitem>
+          <para>Select "Add" in the bottom right corner.
+          text</para>
+        </listitem>
 
-      <listitem>
-        <para>Enter the name of the Milestone in the "Milestone" field. You
-        can optionally set the "sortkey", which is a positive or negative
-        number (-255 to 255) that defines where in the list this particular
-        milestone appears. This is because milestones often do not 
-        occur in alphanumeric order For example, "Future" might be
-        after "Release 1.2". Select "Add".</para>
-      </listitem>
+        <listitem>
+          <para>Enter the name of the Milestone in the "Milestone" field. You
+          can optionally set the "sortkey", which is a positive or negative
+          number (-255 to 255) that defines where in the list this particular
+          milestone appears. This is because milestones often do not 
+          occur in alphanumeric order For example, "Future" might be
+          after "Release 1.2". Select "Add".</para>
+        </listitem>
 
-      <listitem>
-        <para>From the Edit product screen, you can enter the URL of a 
-        page which gives information about your milestones and what
-        they mean. </para>
-      </listitem>
-    </orderedlist>
+        <listitem>
+          <para>From the Edit product screen, you can enter the URL of a 
+          page which gives information about your milestones and what
+          they mean. </para>
+
+        <tip>
+          <para>If you want your milestone document to be restricted so
+          that it can only be viewed by people in a particular Bugzilla
+          group, the best way is to attach the document to a bug in that
+          group, and make the URL the URL of that attachment.</para>
+        </tip>
+        </listitem>
+      </orderedlist>
+    </section>
   </section>
   
   <section id="voting">
@@ -607,7 +637,7 @@
 
       <listitem>
         <para><emphasis>Maximum Votes a person can put on a single
-         bug</emphasis>: 
+         bug"</emphasis>: 
          It should probably be some number lower than the
         "Maximum votes per person". Don't set this field to "0" if
         "Maximum votes per person" is non-zero; that doesn't make
@@ -629,484 +659,654 @@
     </orderedlist>
   </section>
 
-  <section id="quips">
-    <title>Quips</title>
+  <section id="groups">
+    <title>Groups and Group Security</title>
 
-    <para>
-      Quips are small text messages that can be configured to appear
-      next to search results. A Bugzilla installation can have its own specific
-      quips. Whenever a quip needs to be displayed, a random selection
-      is made from the pool of already existing quips.
+    <para>Groups allow the administrator
+    to isolate bugs or products that should only be seen by certain people.
+    There are two types of group - Generic Groups, and Product-Based Groups.
     </para>
-  
+    
     <para>
-      Quips are controlled by the <emphasis>enablequips</emphasis> parameter.
-      It has several possible values: on, approved, frozen or off.
-      In order to enable quips approval you need to set this parameter
-      to "approved". In this way, users are free to submit quips for
-      addition but an administrator must explicitly approve them before
-      they are actually used.
+    Product-Based Groups are matched with products, and allow you to restrict
+    access to bugs on a per-product basis. They are enabled using the 
+    usebuggroups Param. Turning on the usebuggroupsentry
+    Param will mean bugs automatically get added to their product group when 
+    filed.   
     </para>
-
+    
     <para>
-      In order to see the user interface for the quips, it is enough to click
-      on a quip when it is displayed together with the search results. Or
-      it can be seen directly in the browser by visiting the quips.cgi URL
-      (prefixed with the usual web location of the Bugzilla installation).
-      Once the quip interface is displayed, it is enough to click the
-      "view and edit the whole quip list" in order to see the administration
-      page. A page with all the quips available in the database will
-      be displayed.
+    Generic Groups have no special relationship to products; 
+    you create them, and put bugs in them
+    as required. One example of the use of Generic Groups 
+    is Mozilla's "Security" group,
+    into which security-sensitive bugs are placed until fixed. Only the
+    Mozilla Security Team are members of this group.
     </para>
+    
+    <para>To create Generic Groups:</para>
 
-    <para>
-      Next to each tip there is a checkbox, under the
-      "Approved" column. Quips who have this checkbox checked are
-      already approved and will appear next to the search results.
-      The ones that have it unchecked are still preserved in the
-      database but they will not appear on search results pages.
-      User submitted quips have initially the checkbox unchecked.
-    </para>
-  
-    <para>
-      Also, there is a delete link next to each quip,
-      which can be used in order to permanently delete a quip.
-    </para>
-  </section>
+    <orderedlist>
+      <listitem>
+        <para>Select the "groups"
+        link in the footer.</para>
+      </listitem>
 
-  <section id="groups">
-    <title>Groups and Group Security</title>
+      <listitem>
+        <para>Take a moment to understand the instructions on the "Edit
+        Groups" screen, then select the "Add Group" link.</para>
+      </listitem>
 
-    <para>Groups allow the administrator
-    to isolate bugs or products that should only be seen by certain people.
-    The association between products and groups is controlled from
-    the product edit page under <quote>Edit Group Controls.</quote>
-    </para>
+      <listitem>
+        <para>Fill out the "New Name", "New Description", and 
+        "New User RegExp" fields. "New User RegExp" allows you to automatically
+         place all users who fulfill the Regular Expression into the new group. 
+         When you have finished, click "Add".</para>
+      </listitem>
+    </orderedlist>
+
+    <para>To use Product-Based Groups:</para>
+
+    <orderedlist>
+      <listitem>
+        <para>Turn on "usebuggroups" and "usebuggroupsentry" in the "Edit
+        Parameters" screen.</para>
+
+        <warning>
+          <para>XXX is this still true?
+          "usebuggroupsentry" has the capacity to prevent the
+          administrative user from directly altering bugs because of
+          conflicting group permissions. If you plan on using
+          "usebuggroupsentry", you should plan on restricting
+          administrative account usage to administrative duties only. In
+          other words, manage bugs with an unpriveleged user account, and
+          manage users, groups, Products, etc. with the administrative
+          account.</para>
+        </warning>
+      </listitem>
+
+      <listitem>
+        <para>In future, when you create a Product, a matching group will be
+        automatically created. If you need to add a Product Group to
+        a Product which was created before you turned on usebuggroups,
+        then simply create a new group, as outlined above, with the
+        same name as the Product.</para>
+      </listitem>
+    </orderedlist>
+
+    <warning>
+      <para>Bugzilla currently has a limit of 64 groups per installation. If
+      you have more than about 50 products, you should consider
+      running multiple Bugzillas. Ask in the newsgroup for other
+      suggestions for working around this restriction.</para>
+    </warning>
 
-    <para>
-    If the makeproductgroups param is on, a new group will be automatically
-    created for every new product. It is primarily available for backward
-    compatibility with older sites. 
-    </para>
     <para>
       Note that group permissions are such that you need to be a member
       of <emphasis>all</emphasis> the groups a bug is in, for whatever
-      reason, to see that bug. Similarly, you must be a member 
-      of <emphasis>all</emphasis> of the entry groups for a product 
-      to add bugs to a product and you must be a member 
-      of <emphasis>all</emphasis> of the canedit groups for a product
-      in order to make <emphasis>any</emphasis> change to bugs in that
-      product.
+      reason, to see that bug.
     </para>    
-    <section>
-      <title>Creating Groups</title>
-      <para>To create Groups:</para>
-  
-      <orderedlist>
-        <listitem>
-          <para>Select the <quote>groups</quote>
-          link in the footer.</para>
-        </listitem>
-  
-        <listitem>
-          <para>Take a moment to understand the instructions on the <quote>Edit
-          Groups</quote> screen, then select the <quote>Add Group</quote> link.</para>
-        </listitem>
-  
-        <listitem>
-          <para>Fill out the <quote>Group</quote>, <quote>Description</quote>, 
-           and <quote>User RegExp</quote> fields. 
-           <quote>User RegExp</quote> allows you to automatically
-           place all users who fulfill the Regular Expression into the new group. 
-           When you have finished, click <quote>Add</quote>.</para>
-           <para>Users whose email addresses match the regular expression
-           will automatically be members of the group as long as their 
-           email addresses continue to match the regular expression.</para>
-           <note>
-             <para>This is a change from 2.16 where the regular expression
-             resulted in a user acquiring permanent membership in a group.
-             To remove a user from a group the user was in due to a regular
-             expression in version 2.16 or earlier, the user must be explicitly
-             removed from the group.</para>
-           </note>
-           <warning>
-             <para>If specifying a domain in the regexp, make sure you end
-             the regexp with a $. Otherwise, when granting access to 
-             "@mycompany\.com", you will allow access to 
-             'badperson@mycompany.com.cracker.net'. You need to use 
-             '@mycompany\.com$' as the regexp.</para>
-           </warning>
-        </listitem>
-        <listitem>
-          <para>If you plan to use this group to directly control
-          access to bugs, check the "use for bugs" box. Groups
-          not used for bugs are still useful because other groups
-          can include the group as a whole.</para>
-        </listitem>
-        <listitem>
-          <para>After you add your new group, edit the new group.  On the
-          edit page, you can specify other groups that should be included
-          in this group and which groups should be permitted to add and delete
-          users from this group.</para>
-        </listitem>
-      </orderedlist>
-  
-    </section>
-    <section>
-      <title>Assigning Users to Groups</title>
-      <para>Users can become a member of a group in several ways.</para>
-      <orderedlist>
-        <listitem>
-          <para>The user can be explicitly placed in the group by editing
-          the user's own profile</para>
-        </listitem>
-        <listitem>
-          <para>The group can include another group of which the user is
-          a member.</para>
-        </listitem>
-        <listitem>
-          <para>The user's email address can match a regular expression
-          that the group specifies to automatically grant membership to
-          the group.</para>
-        </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 resticted
-      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>
-    <title>Common Applications of Group Controls</title>
-      <section>
-      <title>General User Access With Security Group</title>
-      <para>To permit any user to file bugs in each product (A, B, C...) 
-      and to permit any user to submit those bugs into a security
-      group....</para>
-      <programlisting> 
-Product A...
-security: SHOWN/SHOWN
-Product B...
-security: SHOWN/SHOWN
-Product C...
-security: SHOWN/SHOWN
-      </programlisting>
-      </section>
-      <section>
-      <title>General User Access With A Security Product</title>
-      <para>To permit any user to file bugs in a Security product
-      while keeping those bugs from becoming visible to anyone
-      outside the securityworkers group unless a member of the
-      securityworkers group removes that restriction....</para>
-      <programlisting> 
-Product Security...
-securityworkers: DEFAULT/MANDATORY
-      </programlisting>
-      </section>
-      <section>
-      <title>Product Isolation With Common Group</title>
-      <para>To permit users of product A to access the bugs for
-      product A, users of product B to access product B, and support
-      staff to access both, 3 groups are needed</para>
-      <orderedlist>
-        <listitem>
-          <para>Support: Contains members of the support staff.</para>
-        </listitem>
-        <listitem>
-          <para>AccessA: Contains users of product A and the Support group.</para>
-        </listitem>
-        <listitem>
-          <para>AccessB: Contains users of product B and the Support group.</para>
-        </listitem>
-      </orderedlist>
-      <para>Once these 3 groups are defined, the products group controls
-      can be set to..</para>
-      <programlisting>
-Product A...
-AccessA: ENTRY, MANDATORY/MANDATORY
-Product B...
-AccessB: ENTRY, MANDATORY/MANDATORY
-      </programlisting>
-      <para>Optionally, the support group could be permitted to make
-      bugs inaccessible to the users and could be permitted to publish
-      bugs relevant to all users in a common product that is read-only
-      to anyone outside the support group. That configuration could
-      be...</para>
-      <programlisting>
-Product A...
-AccessA: ENTRY, MANDATORY/MANDATORY
-Support: SHOWN/NA
-Product B...
-AccessB: ENTRY, MANDATORY/MANDATORY
-Support: SHOWN/NA
-Product Common...
-Support: ENTRY, DEFAULT/MANDATORY, CANEDIT
-      </programlisting>
-      </section>
-    </section>
   </section>
 
-  <section id="upgrading">
-    <title>Upgrading to New Releases</title>
+
+  <section id="security">
+    <title>Bugzilla Security</title>
 
     <warning>
-      <para>Upgrading is a one-way process. You should backup your database
-      and current Bugzilla directory before attempting the upgrade. If you wish
-      to revert to the old Bugzilla version for any reason, you will have to
-      restore from these backups.
-      </para>
+      <para>Poorly-configured MySQL and Bugzilla installations have
+      given attackers full access to systems in the past. Please take these
+      guidelines seriously, even for Bugzilla machines hidden away behind
+      your firewall. 80% of all computer trespassers are insiders, not
+      anonymous crackers.</para>
     </warning>
 
-    <para>Upgrading Bugzilla is something we all want to do from time to time,
-    be it to get new features or pick up the latest security fix. How easy
-    it is to update depends on a few factors.
-    </para>
+    <note>
+      <para>These instructions must, of necessity, be somewhat vague since
+      Bugzilla runs on so many different platforms. If you have refinements
+      of these directions for specific platforms, please submit them to 
+      <ulink url="mailto://mozilla-webtools@mozilla.org">
+      mozilla-webtools@mozilla.org</ulink>
+      </para>
+    </note>
 
-    <itemizedlist>
+    <para>To secure your installation:
+     
+    <orderedlist>
       <listitem>
-        <para>If the new version is a revision or a new point release</para>
+        <para>Ensure you are running at least MysQL version 3.22.32 or newer.
+        Earlier versions had notable security holes and (from a security
+        point of view) poor default configuration choices.</para>
       </listitem>
+
       <listitem>
-        <para>How many, if any, local changes have been made</para>
-      </listitem>
-    </itemizedlist>
+        <para>
+        <emphasis>There is no substitute for understanding the tools on your
+        system!</emphasis>
 
-    <para>There are also three different methods to upgrade your installation.
-    </para>
+        Read 
+        <ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html">
+        The MySQL Privilege System</ulink>
+        until you can recite it from memory!</para>
+      </listitem>
 
-    <orderedlist>
       <listitem>
-        <para>Using CVS (<xref linkend="upgrade-cvs"/>)</para>
+        <para>Lock down /etc/inetd.conf. Heck, disable inet entirely on this
+        box. It should only listen to port 25 for Sendmail and port 80 for
+        Apache.</para>
       </listitem>
+
       <listitem>
-        <para>Downloading a new tarball (<xref linkend="upgrade-tarball"/>)</para>
+        <para>Do not run Apache as 
+        <quote>nobody</quote>
+
+        . This will require very lax permissions in your Bugzilla
+        directories. Run it, instead, as a user with a name, set via your
+        httpd.conf file. 
+        <note>
+          <para>
+          <quote>nobody</quote>
+
+          is a real user on UNIX systems. Having a process run as user id 
+          <quote>nobody</quote>
+
+          is absolutely no protection against system crackers versus using
+          any other user account. As a general security measure, I recommend
+          you create unique user ID's for each daemon running on your system
+          and, if possible, use "chroot" to jail that process away from the
+          rest of your system.</para>
+        </note>
+        </para>
       </listitem>
+
       <listitem>
-        <para>Applying the relevant patches (<xref linkend="upgrade-patches"/>)</para>
-      </listitem>
-    </orderedlist>
+        <para>Ensure you have adequate access controls for the
+        $BUGZILLA_HOME/data/ directory, as well as the
+        $BUGZILLA_HOME/localconfig file.
+        The localconfig file stores your "bugs" database account password. 
+        In addition, some
+        files under $BUGZILLA_HOME/data/ store sensitive information.
+        </para>
 
-    <para>Which options are available to you may depend on how large a jump
-    you are making and/or your network configuration.
-    </para>
+        <para>Bugzilla provides default .htaccess files to protect the most
+        common Apache installations. However, you should verify these are
+        adequate according to the site-wide security policy of your web
+        server, and ensure that the .htaccess files are allowed to
+        "override" default permissions set in your Apache configuration
+        files. Covering Apache security is beyond the scope of this Guide;
+        please consult the Apache documentation for details.</para>
+
+        <para>If you are using a web server that does not support the
+        .htaccess control method, 
+        <emphasis>you are at risk!</emphasis>
+
+        After installing, check to see if you can view the file
+        "localconfig" in your web browser (e.g.: 
+        <ulink url="http://bugzilla.mozilla.org/localconfig">
+        http://bugzilla.mozilla.org/localconfig</ulink>
+
+        ). If you can read the contents of this file, your web server has
+        not secured your bugzilla directory properly and you must fix this
+        problem before deploying Bugzilla. If, however, it gives you a
+        "Forbidden" error, then it probably respects the .htaccess
+        conventions and you are good to go.</para>
+
+        <para>When you run checksetup.pl, the script will attempt to modify
+        various permissions on files which Bugzilla uses. If you do not have
+        a webservergroup set in the localconfig file, then Bugzilla will have
+        to make certain files world readable and/or writable. 
+        <emphasis>THIS IS INSECURE!</emphasis>
+
+        . This means that anyone who can get access to your system can do
+        whatever they want to your Bugzilla installation.</para>
 
-    <para>Revisions are normally released to fix security vulnerabilities
-    and are distinguished by an increase in the third number. For example,
-    when 2.16.6 was released, it was a revision to 2.16.5.
-    </para>
+        <note>
+          <para>This also means that if your webserver runs all cgi scripts
+          as the same user/group, anyone on the system who can run cgi
+          scripts will be able to take control of your Bugzilla
+          installation.</para>
+        </note>
 
-    <para>Point releases are normally released when the Bugzilla team feels
-    that there has been a significant amount of progress made between the
-    last point release and the current time. These are often proceeded by a
-    stabilization period and release candidates, however the use of 
-    development versions or release candidates is beyond the scope of this
-    document. Point releases can be distinguished by an increase in the
-    second number, or minor version. For example, 2.18.0 is a newer point
-    release than 2.16.5.
-    </para>
+        <para>On Apache, you can use .htaccess files to protect access to
+        these directories, as outlined in 
+        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=57161">Bug
+        57161</ulink>
 
-    <para>The examples in this section are written as if you were updating
-    to version 2.18.1.  The procedures are the same regardless if you are
-    updating to a new point release or a new revision.  However, the chance
-    of running into trouble increases when upgrading to a new point release,
-    escpecially if you've made local changes.
-    </para>
+        for the localconfig file, and 
+        <ulink url="http://bugzilla.mozilla.org/show_bug.cgi?id=65572">Bug
+        65572</ulink>
+
+        for adequate protection in your data/ directory.</para>
+
+        <para>Note the instructions which follow are Apache-specific. If you
+        use IIS, Netscape, or other non-Apache web servers, please consult
+        your system documentation for how to secure these files from being
+        transmitted to curious users.</para>
+
+        <para>Place the following text into a file named ".htaccess",
+        readable by your web server, in your $BUGZILLA_HOME/data directory. 
+        <literallayout>&lt;Files comments&gt; allow from all &lt;/Files&gt;
+        deny from all</literallayout>
+        </para>
+
+        <para>Place the following text into a file named ".htaccess",
+        readable by your web server, in your $BUGZILLA_HOME/ directory. 
+        <literallayout>&lt;Files localconfig&gt; deny from all &lt;/Files&gt;
+        allow from all</literallayout>
+        </para>
 
-    <para>These examples also assume that your Bugzilla installation is at
-    <filename>/var/www/html/bugzilla</filename>. If that is not the case,
-    simply substitute the proper paths where appropriate.
+      </listitem>
+    </orderedlist>
     </para>
+  </section>
 
-    <example id="upgrade-cvs">
-      <title>Upgrading using CVS</title>
+  <section id="cust-templates">
+    <title>Template Customisation</title>
+    
+    <para>
+      One of the large changes for 2.16 was the templatisation of the
+      entire user-facing UI, using the 
+      <ulink url="http://www.template-toolkit.org">Template Toolkit</ulink>.
+      Administrators can now configure the look and feel of Bugzilla without
+      having to edit Perl files or face the nightmare of massive merge
+      conflicts when they upgrade to a newer version in the future.
+    </para>
+    
+    <para>
+      Templatisation also makes localised versions of Bugzilla possible, 
+      for the first time. In the future, a Bugzilla installation may
+      have templates installed for multiple localisations, and select
+      which ones to use based on the user's browser language setting.      
+    </para>
+    
+    <section>
+      <title>What to Edit</title>
+      <para>
+        There are two different ways of editing of Bugzilla's templates,
+        and which you use depends mainly on how you upgrade Bugzilla. The
+        template directory structure is that there's a top level directory,
+        <filename>template</filename>, which contains a directory for
+        each installed localisation. The default English templates are
+        therefore in <filename>en</filename>. Underneath that, there
+        is the <filename>default</filename> directory and optionally the 
+        <filename>custom</filename> directory. The <filename>default</filename>
+        directory contains all the templates shipped with Bugzilla, whereas
+        the <filename>custom</filename> directory does not exist at first and
+        must be created if you want to use it.
+      </para>
 
-      <para>Every release of Bugzilla, whether it is a revision or a point
-      release, is tagged in CVS.  Also, every tarball we have distributed
-      since version 2.12 has been primed for using CVS. This does, however,
-      require that you are able to access cvs-mirror.mozilla.org on port
-      2401.
+      <para>
+        The first method of making customisations is to directly edit the
+        templates in <filename>template/en/default</filename>. This is
+        probably the best method for small changes if you are going to use
+        the CVS method of upgrading, because if you then execute a
+        <command>cvs update</command>, any template fixes will get
+        automagically merged into your modified versions.
+      </para>
 
-        <tip>
-          <para>If you can do this, updating using CVS is probably the most
-          painless method, especially if you have a lot of local changes.
-          </para>
-        </tip>
+      <para>
+        If you use this method, your installation will break if CVS conflicts
+        occur.
       </para>
 
-      <programlisting>
-bash$ <command>cd /var/www/html/bugzilla</command>
-bash$ <command>cvs login</command>
-Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot
-CVS password: <command>anonymous</command>
-bash$ <command>cvs -q update -r BUGZILLA-2_18_1 -dP</command>
-P checksetup.pl
-P collectstats.pl
-P globals.pl
-P docs/rel_notes.txt
-P template/en/default/list/quips.html.tmpl
-      </programlisting>
+      <para>
+        The other method is to copy the templates into a mirrored directory
+        structure under <filename>template/en/custom</filename>.  The templates
+        in this directory automatically override those in default.  
+        This is the technique you
+        need to use if you use the overwriting method of upgrade, because
+        otherwise your changes will be lost.  This method is also better if
+        you are using the CVS method of upgrading and are going to make major
+        changes, because it is guaranteed that the contents of this directory
+        will not be touched during an upgrade, and you can then decide whether
+        to continue using your own templates, or make the effort to merge your
+        changes into the new versions by hand.
+      </para>
 
       <para>
-        <caution>
-          <para>If a line in the output from <command>cvs update</command>
-          begins with a <computeroutput>C</computeroutput> that represents a
-          file with local changes that CVS was unable to properly merge. You
-          need to resolve these conflicts manually before Bugzilla (or at
-          least the portion using that file) will be usable.
-          </para>
-        </caution>
+        If you use this method, your installation may break if incompatible
+        changes are made to the template interface.  If such changes are made
+        they will be documented in the release notes, provided you are using a
+        stable release of Bugzilla.  If you use using unstable code, you will
+        need to deal with this one yourself, although if possible the changes
+        will be mentioned before they occur in the deprecations section of the
+        previous stable release's release notes.
+      </para>
 
-        <note>
-          <para>You also need to run <command>./checksetup.pl</command>
-          before your Bugzilla upgrade will be complete.
-          </para>
-        </note>
+      <note>
+        <para>
+          Don't directly edit the compiled templates in 
+          <filename class="directory">data/template/*</filename> - your
+          changes will be lost when Template Toolkit recompiles them.
+        </para>
+      </note>
+    </section>
+    
+    <section>
+      <title>How To Edit Templates</title>
+      
+     <para>
+        The syntax of the Template Toolkit language is beyond the scope of
+        this guide. It's reasonably easy to pick up by looking at the current 
+        templates; or, you can read the manual, available on the
+        <ulink url="http://www.template-toolkit.org">Template Toolkit home
+        page</ulink>. However, you should particularly remember (for security
+        reasons) to always HTML filter things which come from the database or
+        user input, to prevent cross-site scripting attacks.
+      </para>
+      
+      <para>
+        However, one thing you should take particular care about is the need
+        to properly HTML filter data that has been passed into the template.
+        This means that if the data can possibly contain special HTML characters
+        such as &lt;, and the data was not intended to be HTML, they need to be
+        converted to entity form, ie &amp;lt;.  You use the 'html' filter in the
+        Template Toolkit to do this.  If you fail to do this, you may open up
+        your installation to cross-site scripting attacks.
       </para>
-    </example>
 
-    <example id="upgrade-tarball">
-      <title>Upgrading using the tarball</title>
+      <para>
+        Also note that Bugzilla adds a few filters of its own, that are not
+        in standard Template Toolkit.  In particular, the 'url_quote' filter
+        can convert characters that are illegal or have special meaning in URLs,
+        such as &amp;, to the encoded form, ie %26.  This actually encodes most
+        characters (but not the common ones such as letters and numbers and so
+        on), including the HTML-special characters, so there's never a need to
+        HTML filter afterwards.
+      </para>
+ 
+      <para>
+        Editing templates is a good way of doing a "poor man's custom fields".
+        For example, if you don't use the Status Whiteboard, but want to have
+        a free-form text entry box for "Build Identifier", then you can just
+        edit the templates to change the field labels. It's still be called
+        status_whiteboard internally, but your users don't need to know that.
+      </para>
+      
+      <note>
+        <para>
+          If you are making template changes that you intend on submitting back
+          for inclusion in standard Bugzilla, you should read the relevant
+          sections of the 
+          <ulink url="http://www.bugzilla.org/developerguide.html">Developers'
+          Guide</ulink>.
+        </para>
+      </note>
+    </section>
+            
+    
+    <section>
+      <title>Template Formats</title>
+      
+      <para>
+        Some CGIs have the ability to use more than one template. For
+        example, buglist.cgi can output bug lists as RDF or two
+        different forms of HTML (complex and simple). (Try this out
+        by appending <filename>&amp;format=simple</filename> to a buglist.cgi
+        URL on your Bugzilla installation.) This
+        mechanism, called template 'formats', is extensible.
+      </para>
+      
+      <para>
+        To see if a CGI supports multiple output formats, grep the
+        CGI for "ValidateOutputFormat". If it's not present, adding
+        multiple format support isn't too hard - see how it's done in
+        other CGIs.
+      </para>
+      
+      <para>
+        To make a new format template for a CGI which supports this, 
+        open a current template for
+        that CGI and take note of the INTERFACE comment (if present.) This 
+        comment defines what variables are passed into this template. If 
+        there isn't one, I'm afraid you'll have to read the template and
+        the code to find out what information you get. 
+      </para>     
+  
+      <para>
+        Write your template in whatever markup or text style is appropriate.
+      </para>
+      
+      <para>
+        You now need to decide what content type you want your template
+        served as. Open up the <filename>localconfig</filename> file and find the 
+        <filename>$contenttypes</filename>
+        variable. If your content type is not there, add it. Remember
+        the three- or four-letter tag assigned to you content type. 
+        This tag will be part of the template filename.
+      </para>
+      
+      <para>
+        Save the template as <filename>&lt;stubname&gt;-&lt;formatname&gt;.&lt;contenttypetag&gt;.tmpl</filename>. 
+        Try out the template by calling the CGI as 
+        <filename>&lt;cginame&gt;.cgi?format=&lt;formatname&gt;</filename> .
+      </para>       
+    </section>
+    
+    
+    <section>
+      <title>Particular Templates</title>
+      
+      <para>
+        There are a few templates you may be particularly interested in
+        customising for your installation.
+      </para>
+      
+      <para>
+        <command>index.html.tmpl</command>:
+        This is the Bugzilla front page.
+      </para>      
 
-      <para>If you are unable or unwilling to use CVS, another option that's
-      always available is to download the latest tarball. This is the most
-      difficult option to use, especially if you have local changes.
+      <para>
+        <command>global/header.html.tmpl</command>:
+        This defines the header that goes on all Bugzilla pages.
+        The header includes the banner, which is what appears to users
+        and is probably what you want to edit instead.  However the
+        header also includes the HTML HEAD section, so you could for
+        example add a stylesheet or META tag by editing the header.
       </para>
 
-      <programlisting>
-bash$ <command>cd /var/www/html</command>
-bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.1.tar.gz</command>
-<emphasis>Output omitted</emphasis>
-bash$ <command>tar xzvf bugzilla-2.18.1.tar.gz</command>
-bugzilla-2.18.1/
-bugzilla-2.18.1/.cvsignore
-bugzilla-2.18.1/1x1.gif
-<emphasis>Output truncated</emphasis>
-bash$ <command>cd bugzilla-2.18.1</command>
-bash$ <command>cp ../bugzilla/localconfig* .</command>
-bash$ <command>cp -r ../bugzilla/data .</command>
-bash$ <command>cd ..</command>
-bash$ <command>mv bugzilla bugzilla.old</command>
-bash$ <command>mv bugzilla-2.18.1 bugzilla</command>
-bash$ <command>cd bugzilla</command>
-bash$ <command>./checksetup.pl</command>
-<emphasis>Output omitted</emphasis>
-      </programlisting>
+      <para>
+        <command>global/banner.html.tmpl</command>:
+        This contains the "banner", the part of the header that appears
+        at the top of all Bugzilla pages.  The default banner is reasonably
+        barren, so you'll probably want to customise this to give your
+        installation a distinctive look and feel.  It is recommended you
+        preserve the Bugzilla version number in some form so the version 
+        you are running can be determined, and users know what docs to read.
+      </para>
 
       <para>
-        <warning>
-          <para>The <command>cp</command> commands both end with periods which
-          is a very important detail, it tells the shell that the destination
-          directory is the current working directory. Also, the period at the
-          beginning of the <command>./checksetup.pl</command> is important and
-          can not be omitted.
-          </para>
-        </warning>
+        <command>global/footer.html.tmpl</command>:
+        This defines the footer that goes on all Bugzilla pages.  Editing
+        this is another way to quickly get a distinctive look and feel for
+        your Bugzilla installation.
+      </para>
 
-        <note>
-          <para>You will now have to reapply any changes you have made to your
-          local installation manually.
-          </para>
-        </note>
+      <para>
+        <command>bug/create/user-message.html.tmpl</command>:
+        This is a message that appears near the top of the bug reporting page.
+        By modifying this, you can tell your users how they should report
+        bugs.
+      </para>
+        
+      <para>
+        <command>bug/create/create.html.tmpl</command> and
+        <command>bug/create/comment.txt.tmpl</command>:
+        You may wish to get bug submitters to give certain bits of structured
+        information, each in a separate input widget, for which there is not a
+        field in the database. The bug entry system has been designed in an
+        extensible fashion to enable you to define arbitrary fields and widgets,
+        and have their values appear formatted in the initial
+        Description, rather than in database fields. An example of this
+        is the mozilla.org 
+        <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided 
+        bug submission form</ulink>.
       </para>
-    </example>
-
-    <example id="upgrade-patches">
-      <title>Upgrading using patches</title>
-
-      <para>The Bugzilla team will normally make a patch file available for
-      revisions to go from the most recent revision to the new one. You could
-      also read the release notes and grab the patches attached to the
-      mentioned bug, but it is safer to use the released patch file as
-      sometimes patches get changed before they get checked in. 
-      It is also theoretically possible to
-      scour the fixed bug list and pick and choose which patches to apply
-      from a point release, but this is not recommended either as what you'll
-      end up with is a hodge podge Bugzilla that isn't really any version.
-      This would also make it more difficult to upgrade in the future.
+
+      <para>
+        To make this work, create a custom template for 
+        <filename>enter_bug.cgi</filename> (the default template, on which you
+        could base it, is <filename>create.html.tmpl</filename>),
+        and either call it <filename>create.html.tmpl</filename> or use a format and
+        call it <filename>create-&lt;formatname&gt;.html.tmpl</filename>.
+        Put it in the <filename class="directory">custom/bug/create</filename>
+        directory. In it, add widgets for each piece of information you'd like
+        collected - such as a build number, or set of steps to reproduce.
       </para>
 
-      <programlisting>
-bash$ <command>cd /var/www/html/bugzilla</command>
-bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.0-to-2.18.1.diff.gz</command>
-<emphasis>Output omitted</emphasis>
-bash$ <command>gunzip bugzilla-2.18.0-to-2.18.1.diff.gz</command>
-bash$ <command>patch -p1 &lt; bugzilla-2.18.0-to-2.18.1.diff</command>
-patching file checksetup.pl
-patching file collectstats.pl
-patching file globals.pl
-      </programlisting>
+      <para>
+        Then, create a template like 
+        <filename>custom/bug/create/comment.txt.tmpl</filename>, also named
+        after your format if you are using one, which
+        references the form fields you have created. When a bug report is
+        submitted, the initial comment attached to the bug report will be
+        formatted according to the layout of this template.
+      </para> 
 
       <para>
-        <caution>
-          <para>If you do this, beware that this doesn't change the entires in
-          your <filename id="dir">CVS</filename> directory so it may make
-          updates using CVS (<xref linkend="upgrade-cvs"/>) more difficult in the
-          future.
-          </para>
-        </caution>
+        For example, if your enter_bug template had a field
+        <programlisting>&lt;input type="text" name="buildid" size="30"&gt;</programlisting>
+        and then your comment.txt.tmpl had
+        <programlisting>BuildID: [% form.buildid %]</programlisting>
+        then
+        <programlisting>BuildID: 20020303</programlisting>
+        would appear in the initial checkin comment.
+      </para>        
+    </section>          
+    
+  </section>
+
+  <section id="cust-change-permissions">
+    <title>Change Permission Customisation</title>
+    
+    <warning>
+      <para>
+        This feature should be considered experimental; the Bugzilla code you
+        will be changing is not stable, and could change or move between 
+        versions. Be aware that if you make modifications to it, you may have
+        to re-make them or port them if Bugzilla changes internally between
+        versions.
       </para>
-    </example>
+    </warning>
+       
+    <para>
+      Companies often have rules about which employees, or classes of employees,
+      are allowed to change certain things in the bug system. For example, 
+      only the bug's designated QA Contact may be allowed to VERIFY the bug.
+      Bugzilla has been
+      designed to make it easy for you to write your own custom rules to define
+      who is allowed to make what sorts of value transition.
+    </para>
+    
+    <para>
+      For maximum flexibility, customising this means editing Bugzilla's Perl 
+      code. This gives the administrator complete control over exactly who is
+      allowed to do what. The relevant function is called 
+      <filename>CheckCanChangeField()</filename>,
+      and is found in <filename>process_bug.cgi</filename> in your 
+      Bugzilla directory. If you open that file and grep for 
+      "sub CheckCanChangeField", you'll find it.
+    </para>
+    
+    <para>
+      This function has been carefully commented to allow you to see exactly
+      how it works, and give you an idea of how to make changes to it. Certain
+      marked sections should not be changed - these are the "plumbing" which
+      makes the rest of the function work. In between those sections, you'll
+      find snippets of code like:
+      <programlisting>    # Allow the owner to change anything.
+    if ($ownerid eq $whoid) {
+        return 1;
+    }</programlisting>
+      It's fairly obvious what this piece of code does.
+    </para>      
+      
+    <para>
+      So, how does one go about changing this function? Well, simple changes
+      can be made just be removing pieces - for example, if you wanted to 
+      prevent any user adding a comment to a bug, just remove the lines marked
+      "Allow anyone to change comments." And if you want the reporter to have
+      no special rights on bugs they have filed, just remove the entire section
+      which refers to him.
+    </para>
+    
+    <para>
+      More complex customisations are not much harder. Basically, you add
+      a check in the right place in the function, i.e. after all the variables
+      you are using have been set up. So, don't look at $ownerid before 
+      $ownerid has been obtained from the database. You can either add a
+      positive check, which returns 1 (allow) if certain conditions are true,
+      or a negative check, which returns 0 (deny.) E.g.:
+      <programlisting>    if ($field eq "qacontact") {
+        if (UserInGroup("quality_assurance")) {
+            return 1;
+        } 
+        else {
+            return 0;
+        }
+    }</programlisting>
+      This says that only users in the group "quality_assurance" can change
+      the QA Contact field of a bug. Getting more weird:
+      <programlisting>    if (($field eq "priority") &&
+        ($vars->{'user'}{'login'} =~ /.*\@example\.com$/))
+    {
+        if ($oldvalue eq "P1") {
+            return 1;
+        } 
+        else {
+            return 0;
+        }
+    }</programlisting>
+      This says that if the user is trying to change the priority field,
+      and their email address is @example.com, they can only do so if the
+      old value of the field was "P1". Not very useful, but illustrative.
+    </para>
+    
+    <para>
+      For a list of possible field names, look in 
+      <filename>data/versioncache</filename> for the list called 
+      <filename>@::log_columns</filename>. If you need help writing custom
+      rules for your organisation, ask in the newsgroup.
+    </para>    
+  </section>   
+  
+  <section id="upgrading">
+    <title>Upgrading to New Releases</title>
 
+    <para>A plain Bugzilla is fairly easy to upgrade from one version to a
+    newer one. Always read the release notes to see if there are any issues
+    that you might need to take note of. It is recommended that you take a 
+    backup of your database and your entire Bugzilla installation before attempting an
+    upgrade. You can upgrade a 'clean' installation by untarring a new
+    tarball over the old installation. If you are upgrading from 2.12 or
+    later, and have cvs installed, you can type <filename>cvs -z3 update</filename>, 
+    and resolve conflicts if there are any.
+    </para>
+    
+    <para>However, things get a bit more complicated if you've made
+    changes to Bugzilla's code. In this case, you may have to re-make or
+    reapply those changes. One good method is to take a diff of your customised
+    version against the original, so you can survey all that you've changed.
+    Hopefully, templatisation will reduce the need for
+    this in the future.</para>
+
+    <para>From version 2.8 onwards, Bugzilla databases can be automatically
+    carried forward during an upgrade. However, because the developers of
+    Bugzilla are constantly adding new
+    tables, columns and fields, you'll probably get SQL errors if you just
+    update the code and attempt to use Bugzilla. Always run the
+    <filename>checksetup.pl</filename> 
+    script whenever you upgrade your installation.</para>
+
+    <para>If you are running Bugzilla version 2.8 or lower, and wish to
+    upgrade to the latest version, please consult the file,
+    "UPGRADING-pre-2.8" in the Bugzilla root directory after untarring the
+    archive.</para>
   </section>
+
+  <!-- Integrating Bugzilla with Third-Party Tools -->
+  &integration;
+
 </chapter>
 
 <!-- Keep this comment at the end of the file
@@ -1124,7 +1324,7 @@ sgml-local-ecat-files:nil
 sgml-minimize-attributes:nil
 sgml-namecase-general:t
 sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
 sgml-shorttag:t
 sgml-tag-region-if-active:t
 End: