Bug 256019 - The documentation was unclear regarding what to do if the administrator gets logged out while "shutdownhtml" is active.

Patch by Shane H. W. Travis <travis@sedsystems.ca>
r=jake

1 files changed, 167 insertions, 127 deletions

diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index e28e6fc8d..67f818e1f 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -5,10 +5,12 @@
   <section id="parameters">
     <title>Bugzilla Configuration</title>
 
-    <para>Bugzilla is configured by changing various parameters, accessed
-    from the "Edit parameters" link in the page footer. Here are
-    some of the key parameters on that page. You should run down this
-    list and set them appropriately after installing Bugzilla.</para>
+    <para>
+      Bugzilla is configured by changing various parameters, accessed
+      from the "Edit parameters" link in the page footer. Here are
+      some of the key parameters on that page. You should run down this
+      list and set them appropriately after installing Bugzilla.
+    </para>
 
     <indexterm>
       <primary>checklist</primary>
@@ -17,189 +19,228 @@
     <procedure>
       <step>
         <para> 
-        <command>maintainer</command>:
-        The maintainer parameter is the email address of the person 
-        responsible for maintaining this
-        Bugzilla installation. The address need not be that of a valid Bugzilla
-        account.</para>
+          <command>maintainer</command>:
+
+          The maintainer parameter is the email address of the person 
+          responsible for maintaining this Bugzilla installation.
+          The address need not be that of a valid Bugzilla account.
+        </para>
       </step>
 
       <step>
         <para>
-        <command>urlbase</command>:
-        This parameter defines the fully qualified domain name and web 
-        server path to your Bugzilla installation.</para>
-
-        <para>For example, if your Bugzilla query page is
-        <filename>http://www.foo.com/bugzilla/query.cgi</filename>, 
-        set your <quote>urlbase</quote>
-        to <filename>http://www.foo.com/bugzilla/</filename>.</para>
+          <command>urlbase</command>:
+
+          This parameter defines the fully qualified domain name and web 
+          server path to your Bugzilla installation.
+        </para>
+
+        <para>
+          For example, if your Bugzilla query page is
+          <filename>http://www.foo.com/bugzilla/query.cgi</filename>, 
+          set your <quote>urlbase</quote>
+          to <filename>http://www.foo.com/bugzilla/</filename>.
+        </para>
       </step>
 
       <step>
         <para>
-        <command>makeproductgroups</command>:
-        This dictates whether or not to automatically create groups
-        when new products are created.
+          <command>makeproductgroups</command>:
+
+          This dictates whether or not to automatically create groups
+          when new products are created.
         </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>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>
       </step>
 
       <step>
         <para>
-        <command>shadowdb</command>:
-        You run into an interesting problem when Bugzilla reaches a
-        high level of continuous activity. MySQL supports only table-level
-        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>
-        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.
-        Although your database size will double, a shadow database can cause
-        an enormous performance improvement when implemented on extremely
-        high-traffic Bugzilla databases.</para>
+          <command>shadowdb</command>:
+
+          You run into an interesting problem when Bugzilla reaches a
+          high level of continuous activity. MySQL supports only table-level
+          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> 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. Although your database size will
+          double, a shadow database can cause an enormous performance
+          improvement when implemented on extremely high-traffic Bugzilla
+          databases.
+        </para>
         
         <para>
-        As a guide, on reasonably old hardware, 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>
+          As a guide, on reasonably old hardware, 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>
       </step>
 
       <step>
         <para>
-        <command>shutdownhtml</command>:
+          <command>shutdownhtml</command>:
 
-        If you need to shut down Bugzilla to perform administration, enter
-        some descriptive HTML here and anyone who tries to use Bugzilla will
-        receive a page to that effect. Obviously, editparams.cgi will
-        still be accessible so you can remove the HTML and re-enable Bugzilla.
-        :-)
+          If you need to shut down Bugzilla to perform administration, enter
+          some descriptive text (with embedded HTML codes, if you'd like)
+          into this box. Anyone who tries to use Bugzilla (including admins)
+          will receive a page displaying this text. Users can neither log in
+          nor log out while shutdownhtml is enabled.
         </para>
+
+        <note>
+          <para>
+            Although regular log-in capability is disabled while 'shutdownhtml'
+            is enabled, safeguards are in place to protect the unfortunate 
+            admin who loses connection to Bugzilla. Should this happen to you,
+            go directly to the <filename>editparams.cgi</filename> (by typing
+            the URL in manually, if necessary). Doing this will prompt you to
+            log in, and your name/password will be accepted here (but nowhere
+            else). 
+          </para>
+        </note>
       </step>
 
       <step>
         <para>
-        <command>passwordmail</command>:
+          <command>passwordmail</command>:
 
-        Every time a user creates an account, the text of
-        this parameter (with substitutions) is sent to the new user along with
-        their password message.</para>
+          Every time a user creates an account, the text of this parameter
+          (with substitutions) is sent to the new user along with their
+          password message.
+        </para>
 
-        <para>Add any text you wish to the "passwordmail" parameter box. For
-        instance, many people choose to use this box to give a quick training
-        blurb about how to use Bugzilla at your site.</para>
+        <para>
+          Add any text you wish to the "passwordmail" parameter box. For
+          instance, many people choose to use this box to give a quick 
+          training 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>
+          <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>:
+          <command>useqacontact</command>:
 
-        This allows you to define an email address for each component, in
-        addition
-        to that of the default owner, who will be sent carbon copies of
-        incoming bugs.</para>
+          This allows you to define an email address for each component, 
+          in addition to that of the default owner, who will be sent
+          carbon copies of incoming bugs.
+        </para>
       </step>
+
       <step>
         <para>
-        <command>usestatuswhiteboard</command>:
-        This defines whether you wish to have a free-form, overwritable field
-        associated with each bug. The advantage of the Status Whiteboard is
-        that it can be deleted or modified with ease, and provides an
-        easily-searchable field for indexing some bugs that have some trait
-        in common.         
+          <command>usestatuswhiteboard</command>:
+
+          This defines whether you wish to have a free-form, overwritable field
+          associated with each bug. The advantage of the Status Whiteboard is
+          that it can be deleted or modified with ease, and provides an
+          easily-searchable field for indexing some bugs that have some trait
+          in common.         
         </para>
       </step>
 
       <step>
         <para>
-        <command>whinedays</command>:
-        Set this to the number of days you want to let bugs go
-        in the NEW or REOPENED state before notifying people they have
-        untouched new bugs. If you do not plan to use this feature, simply do
-        not set up the whining cron job described in the installation
-        instructions, or set this value to "0" (never whine).</para>
+          <command>whinedays</command>:
+
+          Set this to the number of days you want to let bugs go
+          in the NEW or REOPENED state before notifying people they have
+          untouched new bugs. If you do not plan to use this feature, simply 
+          do not set up the whining cron job described in the installation
+          instructions, or set this value to "0" (never whine).
+        </para>
       </step>
 
       <step>
         <para>
-        <command>commenton*</command>:
-        All these
-        fields allow you to dictate what changes can pass without comment,
-        and which must have a comment from the person who changed them.
-        Often, administrators will allow users to add themselves to the CC
-        list, accept bugs, or change the Status Whiteboard without adding a
-        comment as to their reasons for the change, yet require that most
-        other changes come with an explanation.</para>
-
-        <para>Set the "commenton" options according to your site policy. It
-        is a wise idea to require comments when users resolve, reassign, or
-        reopen bugs at the very least. 
+          <command>commenton*</command>:
+
+          All these fields allow you to dictate what changes can pass
+          without comment, and which must have a comment from the
+          person who changed them.  Often, administrators will allow
+          users to add themselves to the CC list, accept bugs, or
+          change the Status Whiteboard without adding a comment as to
+          their reasons for the change, yet require that most other
+          changes come with an explanation.
+        </para>
+
+        <para>
+          Set the "commenton" options according to your site policy. It
+          is a wise idea to require comments when users resolve, reassign, or
+          reopen bugs at the very least. 
+        </para>
+
         <note>
-          <para>It is generally far better to require a developer comment
-          when resolving bugs than not. Few things are more annoying to bug
-          database users than having a developer mark a bug "fixed" without
-          any comment as to what the fix was (or even that it was truly
-          fixed!)</para>
+          <para>
+            It is generally far better to require a developer comment
+            when resolving bugs than not. Few things are more annoying to bug
+            database users than having a developer mark a bug "fixed" without
+            any comment as to what the fix was (or even that it was truly
+            fixed!)
+          </para>
         </note>
-        </para>
       </step>
 
       <step>
         <para>
-        <command>supportwatchers</command>:
-
-        Turning on this option allows users to ask to receive copies of 
-        all a particular other user's bug email. This is, of
-        course, subject to the groupset restrictions on the bug; if the 
-        <quote>watcher</quote>
-        would not normally be allowed to view a bug, the watcher cannot get
-        around the system by setting herself up to watch the bugs of someone
-        with bugs outside her privileges. They would still only receive email
-        updates for those bugs she could normally view.</para>        
+          <command>supportwatchers</command>:
+
+          Turning on this option allows users to ask to receive copies 
+          of bug mail sent to another user.  Watching a user with
+          different group permissions is not a way to 'get around' the
+          system; copied emails are still subject to the normal groupset
+          permissions of a bug, and <quote>watchers</quote> will only be 
+          copied on emails from bugs they would normally be allowed to view. 
+        </para> 
       </step>
 
+
       <step>
         <para>
           <command>noresolveonopenblockers</command>:
@@ -209,7 +250,6 @@
           is affected. Users will be still able to resolve bugs to
           resolutions other than FIXED if they have unresolved dependent
           bugs.
-
         </para>
       </step>