Documentation update; added docs/sgml, docs/html, docs/txt.

No text version of The Bugzilla Guide availabe yet, however.

1 files changed, 1107 insertions, 0 deletions

diff --git a/docs/sgml/administration.sgml b/docs/sgml/administration.sgml
new file mode 100644
index 000000000..3ab02653b
--- /dev/null
+++ b/docs/sgml/administration.sgml
@@ -0,0 +1,1107 @@
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
+
+<!-- TOC
+Chapter: Administration
+ Localconfig and Checksetup.pl customizations
+ The Email Gateway
+ Editing parameters
+  Deciding your site policies
+  The Shadow Database
+  Customizing password mail & layout
+  The Whining Cron
+  Why you shouldn't allow deletion
+ User administration
+  Creating Users
+  Disabling Users
+  User Permissions
+ Product Administration
+  Creating products
+  Creating components
+  Assigning default owners and Q/A contacts to components
+  Product Milestones
+  Product Versions
+  Voting
+-->
+
+<CHAPTER id="administration">
+  <TITLE>Administering Bugzilla</TITLE>
+<SUBTITLE>Or, I just got this cool thing installed.  Now what the heck do I do with it?</SUBTITLE>
+
+<PARA>
+So you followed the README isntructions to the letter, and
+just logged into bugzilla with your super-duper god account and you are sitting at the query
+screen. Yet, you have nothing to query. Your first act of bisuness needs to be to setup the
+operating parameters for bugzilla.</PARA>
+
+  <SECTION id="postinstall-check">
+    <TITLE>Post-Installation Checklist</TITLE>
+    <PARA>
+      After installation, follow the checklist below to ensure that
+      you have a successful installation.
+      If you do not see a recommended setting for a parameter,
+      consider leaving it at the default
+      while you perform your initial tests on your Bugzilla setup.
+    </PARA>
+      <INDEXTERM>
+	<PRIMARY>checklist</PRIMARY>
+      </INDEXTERM>
+    <PROCEDURE>
+      <STEP>
+	<PARA>
+	  Set "maintainer" to <EMPHASIS>your</EMPHASIS> email address.
+	  This allows Bugzilla's error messages
+	  to display your email
+	  address and allow people to contact you for help.
+	</PARA>
+      </STEP>
+      <STEP>
+	<PARA>
+	  Set "urlbase" to the URL reference for your Bugzilla installation.
+	  If your bugzilla query page is at http://www.foo.com/bugzilla/query.cgi,
+	  your url base is http://www.foo.com/bugzilla/
+	</PARA>
+      </STEP>
+      <STEP>
+	<PARA>
+	  Set "usebuggroups" to "1" <EMPHASIS>only</EMPHASIS>
+	  if you need to restrict access to products.
+	  I suggest leaving this parameter <EMPHASIS>off</EMPHASIS>
+	  while initially testing your Bugzilla.
+	</PARA>
+      </STEP>
+      <STEP>
+	<PARA>
+	  Set "usebuggroupsentry" to "1" if you want to be able to restrict access to products.
+	  Once again, if you are simply testing your installation, I suggest against
+	  turning this parameter on; the strict security checking may stop you from
+	  being able to modify your new entries.
+	</PARA>
+      </STEP>
+      <STEP>
+        <PARA>
+	  Set "shadowdb" to "bug_shadowdb" if you will be
+	  running a *very* large installation of Bugzilla.
+	  The shadow database enables many simultaneous users
+	  to read and write to the database
+	  without interfering with one another.  
+	  <NOTE>
+	    <PARA>
+	      Enabling "shadowdb" can adversely affect the stability
+	      of your installation of Bugzilla.
+	      You may frequently need to manually synchronize your databases,
+	      or schedule nightly syncs
+	      via "cron"
+	    </PARA>
+	  </NOTE>
+	  Once again, in testing you should
+	  avoid this option -- use it if or when you <EMPHASIS>need</EMPHASIS> to use it, and have
+	  repeatedly run into the problem it was designed to solve -- very long wait times while
+	  attempting to commit a change to the database.
+        </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>
+        <PARA>
+	  If you have custom logos or HTML you must put in place to fit within your site design guidelines,
+	  place the code in the "headerhtml", "footerhtml", "errorhtml", "bannerhtml", or "blurbhtml" text boxes.
+	  <NOTE>
+	    <PARA>
+	      The "headerhtml" text box is the HTML printed out <EMPHASIS>before</EMPHASIS> any other code on the page.
+	      If you have a special banner, put the code for it in "bannerhtml".  You may want to leave these
+	      settings at the defaults initially.
+	    </PARA>
+	  </NOTE>
+	</PARA>
+      </STEP>
+      <STEP>
+        <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>
+	  Set "newemailtech" to "on".  Your users will thank you.  This is the default in the post-2.12 world.
+	</PARA>
+      </STEP>
+      <STEP>
+	<PARA>
+	  Do you want to use the qa contact ("useqacontact") and status whiteboard ("usestatuswhiteboard") fields?
+	  These fields are useful because they allow for more flexibility, particularly when you have an existing
+	  Quality Assurance and/or Release Engineering team, 
+	  but they may not be needed for smaller installations.
+	</PARA>
+      </STEP>
+      <STEP>
+	<PARA>
+	  Set "whinedays" to the amount 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 README, or set this value to "0".
+	</PARA>
+      </STEP>
+      <STEP>
+	<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.
+	  <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>
+	  </NOTE>
+	</PARA>
+      </STEP>
+      <STEP>
+	<PARA>
+	  Set "supportwatchers" to "On".  This feature is helpful for team leads to monitor progress in their
+	  respective areas, and can offer many other benefits, such as allowing a developer to pick up a
+	  former engineer's bugs without requiring her to change all the information in the bug.
+	</PARA>
+      </STEP>
+    </PROCEDURE>
+  </SECTION>
+
+  <SECTION id="useradmin">
+    <TITLE>User Administration</TITLE>
+    <PARA>
+      User administration is one of the easiest parts of Bugzilla.
+      Keeping it from getting out of hand, however, can become a challenge.
+    </PARA>
+
+    <SECTION id="defaultuser">
+      <TITLE>Creating the Default User</TITLE>
+
+      <PARA>
+	When you first run checksetup.pl after installing Bugzilla, it will prompt you
+	for the administrative username (email address) and password for this "super user".
+	If for some reason you were to delete the "super user" account, re-running
+	checksetup.pl will again prompt you for this username and password.
+      </PARA>
+      <TIP>
+	<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 ("mysql>" denotes the 
+	mysql prompt, not something you should type in):
+	<COMMAND><PROMPT>mysql></PROMPT> use bugs;</COMMAND>
+	<COMMAND><PROMPT>mysql></PROMPT> update profiles set groupset=0x7ffffffffffffff
+	  where login_name = "(user's login name)"; </COMMAND>
+	</PARA>
+      </TIP>
+    </SECTION>
+
+    <SECTION id="manageusers">
+      <TITLE>Managing Other Users</TITLE>
+
+      <SECTION id="login">
+	<TITLE>Logging In</TITLE>
+	<ORDEREDLIST>
+	  <LISTITEM>
+	    <PARA>
+	      Open the index.html page for your Bugzilla installation in your browser window.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      Click the "Query Existing Bug Reports" link.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      Click the "Log In" link at the foot of the page.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      Type your email address, and the password which was emailed to you when you
+	      created your Bugzilla account, into the spaces provided.
+	    </PARA>
+	  </LISTITEM>
+	</ORDEREDLIST>
+	<PARA>Congratulations, you are logged in!</PARA>
+      </SECTION>
+
+      <SECTION id="createnewusers">
+	<TITLE>Creating new users</TITLE>
+	<PARA>
+	  Your users can create their own user accounts by clicking the "New Account"
+	  link at the bottom of each page.
+	  However, should you desire to create user accounts ahead of time, here is how you do it.
+	</PARA>
+	<ORDEREDLIST>
+	  <LISTITEM>
+	    <PARA>
+	      After logging in, click the "Users" link at the footer of the query page.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      To see a specific user, type a portion of their login name
+	      in the box provided and click "submit".
+	      To see all users, simply click the "submit" button.
+	      You must click "submit" here to be able to add a new user.
+	    </PARA>
+	    <TIP>
+	      <PARA>
+		More functionality is available via the list on the right-hand side
+		of the text entry box.
+		You can match what you type as a case-insensitive substring (the default)
+		of all users on your system, a case-sensitive regular expression
+		(please see the "man regexp" manual page for details on regular expression syntax),
+		or a <EMPHASIS>reverse</EMPHASIS> regular expression match,
+		where every user name which does NOT match the regular expression
+		is selected.
+	      </PARA>
+	    </TIP>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      Click the "Add New User" link at the bottom of the user list
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      Fill out the form presented.  This page is self-explanatory.  When done, click "submit".
+	    </PARA>
+	    <NOTE>
+	      <PARA>
+		Adding a user this way will <EMPHASIS>not</EMPHASIS> send an email
+		informing them of their username and password.
+		In general, it is preferable to log out and use the "New Account"
+		button to create users, as it will pre-populate all the required fields and also notify 
+		the user of her account name and password.
+	      </PARA>
+	    </NOTE>
+	  </LISTITEM>
+	</ORDEREDLIST>
+      </SECTION>
+
+      <SECTION id="disableusers">
+	<TITLE>Disabling Users</TITLE>
+	<PARA>
+	  I bet you noticed that big "Disabled Text" entry box available from the "Add New User" screen,
+	  when you edit an account?
+	  By entering any text in this box and selecting "submit",
+	  you have prevented the user from using Bugzilla via the web interface.
+	  Your explanation, written in this text box, will be presented to the user
+	  the next time she attempts to use the system.
+	  <WARNING>
+	    <PARA>
+	      Don't disable your own administrative account, or you will hate life!
+	    </PARA>
+	  </WARNING>
+	</PARA>
+      </SECTION>
+
+      <SECTION id="modifyusers">
+	<TITLE>Modifying Users</TITLE>
+	<PARA>
+	  Here I will attempt to describe the function of each option on the user edit screen.
+	</PARA>
+	<ITEMIZEDLIST>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Login Name</EMPHASIS>: This is generally the user's email address.
+	      However, if you have edited your system parameters,
+	      this may just be the user's login name or some other identifier.
+	      <TIP>
+		<PARA>
+		  For compatability reasons, you should probably
+		  stick with email addresses as user login names.  It will make your life easier.
+		</PARA>
+	      </TIP>
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Real Name</EMPHASIS>: Duh!
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Password</EMPHASIS>: You will only see asterisks in versions
+	      of Bugzilla newer than 2.10 or early 2.11.  You can change the user password here.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Email Notification</EMPHASIS>: You may choose from one of three options:
+	      <ORDEREDLIST>
+		<LISTITEM>
+		  <PARA>
+		    All qualifying bugs except those which I change:
+		    The user will be notified of any change to any bug
+		    for which she is the reporter, assignee, Q/A contact, CC recipient, or "watcher".
+		  </PARA>
+		</LISTITEM>
+		<LISTITEM>
+		  <PARA>
+		    Only those bugs which I am listed on the CC line:
+		    The user will not be notified of changes to bugs where she is the assignee,
+		    reporter, or Q/A contact, but will receive them if she is on the CC list.
+		    <NOTE>
+		      <PARA>
+			She will still receive whining cron emails if you set up the "whinemail" feature.
+		      </PARA>
+		    </NOTE>
+		  </PARA>
+		</LISTITEM>
+		<LISTITEM>
+		  <PARA>
+		    <EMPHASIS>All Qualifying Bugs</EMPHASIS>: This user is a glutton for punishment.
+		    If her name is in the reporter, Q/A contact, CC, assignee, or is a "watcher",
+		    she will get email updates regarding the bug.
+		  </PARA>
+		</LISTITEM>
+	      </ORDEREDLIST>
+</PARA>
+	    <PARA>
+	      <EMPHASIS>Disable Text</EMPHASIS>: If you type anything in this box,
+	      including just a space, the user account is disabled from making any changes
+	      to bugs via the web interface, and what you type in this box is presented as the reason.
+	      <WARNING>
+		<PARA>Don't disable the administrator account!</PARA>
+	      </WARNING>
+	      <NOTE>
+		<PARA>
+		  As of this writing, the user can still submit bugs via the e-mail gateway,
+		  if you set it up, despite the disabled text field.  The e-mail gateway should
+		  <EMPHASIS>not</EMPHASIS> be enabled for secure installations of Bugzilla.
+		</PARA>
+	      </NOTE>
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>CanConfirm</EMPHASIS>: This field is only used if you have enabled
+	      "unconfirmed" status in your parameters screen.  If you enable this for a user,
+	      that user can then move bugs from "Unconfirmed" to "Confirmed" status (ergo: "New" status).
+	      Be judicious about allowing users to turn this bit on for other users.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Creategroups</EMPHASIS>: This option will allow a user to create and
+	      destroy groups in Bugzilla.  Unless you are using the Bugzilla GroupSentry security
+	      option "usebuggroupsentry" in your parameters, this setting has no effect.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Editbugs</EMPHASIS>: Unless a user has this bit set, they can only edit
+	      those bugs for which they are the assignee or the reporter.  
+	      <NOTE>
+		<PARA>
+		  Leaving this option unchecked does not prevent users from adding
+		  comments to a bug!  They simply cannot change a bug priority, severity,
+		  etc. unless they are the assignee or reporter.
+		</PARA>
+	      </NOTE>
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Editcomponents</EMPHASIS>: This flag allows a user to create new 
+	      products and components, as well as modify and destroy those that have no bugs
+	      associated with them.  If a product or component has bugs associated with it,
+	      those bugs must be moved to a different product or component before Bugzilla
+	      will allow them to be destroyed.  The name of a product or component can be
+	      changed without affecting the associated bugs, but it tends to annoy
+	      the hell out of your users when these change a lot.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Editkeywords</EMPHASIS>: If you use Bugzilla's keyword functionality,
+	      enabling this feature allows a user can create and destroy keywords.
+	      As always, the keywords for existing bugs containing the keyword
+	      the user wishes to destroy must be changed before Bugzilla will allow it to die.
+	      You must be very careful about creating too many new keywords
+	      if you run a very large Bugzilla installation; keywords are global variables 
+	      across products, and you can often run into a phenomenon called "keyword bloat".
+	      This confuses users, and then the feature goes unused.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>Editusers</EMPHASIS>: This flag allows a user do what you're doing
+	      right now: edit other users.
+	      This will allow those with the right to do so to remove administrator
+	      priveleges from other users or grant them to themselves.  Enable with care.
+	    </PARA>
+	  </LISTITEM>
+	  <LISTITEM>
+	    <PARA>
+	      <EMPHASIS>PRODUCT</EMPHASIS>: PRODUCT bugs access.  This allows an administrator,
+	      with product-level granularity, to specify in which products a user can edit bugs. 
+	      The user must still have the "editbugs" privelege to edit bugs in this area;
+	      this simply restricts them from even seeing bugs outside these boundaries if the administrator
+	      has enabled the group sentry parameter "usebuggroupsentry".  Unless you are using bug groups,
+	      this option has no effect.
+	    </PARA>
+	  </LISTITEM>
+	</ITEMIZEDLIST>
+      </SECTION>
+    </SECTION>
+  </SECTION>
+
+  <SECTION id="programadmin">
+    <TITLE>Product, Component, Milestone, and Version Administration</TITLE>
+    <EPIGRAPH>
+      <PARA>
+	Dear Lord, we have to get our users to do WHAT?
+      </PARA>
+    </EPIGRAPH>
+    <REMARK>
+      Many thanks to Zach Lipton for his contributions to this section
+    </REMARK>
+
+    <SECTION id="products">
+      <TITLE>Products</TITLE>
+      <SUBTITLE>Formerly, and in some spots still, called "Programs"</SUBTITLE>
+      <PARA>
+	<GLOSSTERM baseform="product" linkend="gloss_product">Products</GLOSSTERM> are the
+	broadest category in Bugzilla, and you should have the least of these.
+	If your company makes computer games, you should have one product per game,
+	and possibly a few special products
+	(website, meetings...)
+      </PARA>
+      <PARA>
+	A Product (formerly called "Program", and still referred to that way
+	in some portions of the source code) controls some very important functions.
+	The number of "votes" available for users to vote for the most important bugs
+	is set per-product, as is the number of votes required to move a bug automatically
+	from the UNCONFIRMED status to the NEW status.  One can close a Product for further
+	bug entry and define various Versions available from the Edit Product screen.
+      </PARA>
+      <PARA>To create a new product:</PARA>
+      <ORDEREDLIST>
+	<LISTITEM>
+	  <PARA>
+	    Select "components" from the yellow footer
+	  </PARA>
+	  <TIP>
+	    <PARA>
+	      It may seem counterintuitive to click "components" when you want
+	      to edit the properties associated with Products.  This is one of a long
+	      list of things we want in Bugzilla 3.0...
+	    </PARA>
+	  </TIP>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Select the "Add" link to the right of "Add a new product".
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Enter the name of the product and a description.
+	    The Description field is free-form.
+	  </PARA>
+	</LISTITEM>
+      </ORDEREDLIST>
+      <TIP>
+	<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>
+      </TIP>
+    </SECTION>
+    
+    <SECTION id="components">
+      <TITLE>Components</TITLE>
+      <PARA>
+	Components are subsections of a Product. 
+
+	<EXAMPLE>
+	  <TITLE>Creating some Components</TITLE>
+	  <INFORMALEXAMPLE>
+	    <PARA>
+	      The computer game you are designing may 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>
+	  </INFORMALEXAMPLE>
+	</EXAMPLE>
+
+	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>; the Owner and Q/A Contact fields in a bug 
+	are otherwise unrelated to the Component.
+      </PARA>
+
+      <PARA>
+	To create a new Component:
+      </PARA>
+      <ORDEREDLIST>
+	<LISTITEM>
+	  <PARA>
+	    Select the "Edit components" link from the "Edit Product" page
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Select the "Add" link to the right of the "Add a new component" text
+	    on the "Select Component" page.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Fill out the "Component" field, a short "Description", and the "Initial Owner".
+	    The "Component" field should not contain a space.  The "Description" field is
+	    free-form.  The "Initial Owner" field must be that of a valid user already
+	    existing in the database.  If the initial owner does not exist, Bugzilla
+	    will refuse to create the component.
+	    <TIP>
+	      <PARA>
+		Is your "Default Owner" a user who is not yet in the database?
+		No problem.
+		<ORDEREDLIST>
+		  <LISTITEM>
+		    <PARA>
+		      Select the "Log out" link on the footer of the page.
+		    </PARA>
+		  </LISTITEM>
+		  <LISTITEM>
+		    <PARA>
+		      Select the "New Account" link on the footer of the "Relogin" page
+		    </PARA>
+		  </LISTITEM>
+		  <LISTITEM>
+		    <PARA>
+		      Type in the email address of the default owner you want to create
+		      in the "E-mail address" field, and her full name in the "Real name"
+		      field, then select the "Submit Query" button.
+		    </PARA>
+		  </LISTITEM>
+		  <LISTITEM>
+		    <PARA>
+		      Now select "Log in" again, type in your login information, and you
+		      can modify the product to use the Default Owner information
+		      you require.
+		    </PARA>
+		  </LISTITEM>
+		</ORDEREDLIST>
+	      </PARA>
+	    </TIP>
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Either "edit" more components or return to the "query" page on the ensuing
+	    "Addming new component" page.  To return to the Product you were editing, you
+	    must select the "components" link as before.
+	  </PARA>
+	</LISTITEM>
+      </ORDEREDLIST>
+    </SECTION>
+    
+    <SECTION id="versions">
+      <TITLE>Versions</TITLE>
+      <PARA>
+	Versions are the revisions of the product, such as "Flinders 3.1", "Flinders 95",
+	and "Flinders 2000".  Using Versions helps you isolate code changes and are an aid
+	in reporting.
+
+	<EXAMPLE>
+	  <TITLE>Common Use of Versions</TITLE>
+	  <INFORMALEXAMPLE>
+	    <PARA>
+	      A user reports a bug
+	      against Version "Beta 2.0" of your product.  The current Version of your software
+	      is "Release Candidate 1", and no longer has the bug.  This will
+	      help you triage and classify bugs according to their relevance.  It is also
+	      possible people may report bugs against bleeding-edge beta versions that are
+	    not evident in older versions of the software.  This can help isolate code
+	      changes that caused the bug
+	    </PARA>
+	  </INFORMALEXAMPLE>
+	</EXAMPLE>
+	<EXAMPLE>
+	  <TITLE>A Different Use of Versions</TITLE>
+	  <INFORMALEXAMPLE>
+	    <PARA>
+	      This field has been used to good effect by an online service provider in a slightly
+	      different way.  They had three versions of the product: "Production", "QA",
+	      and "Dev".  Although it may be the same product, a bug in the development
+	      environment is not normally as critical as a Production bug, nor does it
+	      need to be reported publicly.  When used in conjunction with Target Milestones,
+	      one can easily specify the environment where a bug can be reproduced, and
+	      the Milestone by which it will be fixed.
+	    </PARA>
+	  </INFORMALEXAMPLE>
+	</EXAMPLE>
+       </PARA>
+      <PARA>
+	To create and edit Versions:
+      </PARA>
+      <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".
+	    If your product doesn't use version numbers, you may want to leave this as it is
+	    or edit it so that it is "---". You can then go back to the edit versions page
+	    and add new versions to your product.
+	  </PARA>
+	  <PARA>
+	    Otherwise, click the "Add" button to the right of the "Add a new version" text.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Enter the name of the Version.  This can be free-form characters up to the limit of the
+	    text box.  Then select the "Add" button.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    At this point you can select "Edit" to edit more Versions, or return to the "Query"
+	    page, from which you can navigate back to the product through the "components" link
+	    at the foot of the Query page.
+	  </PARA>
+	</LISTITEM>
+      </ORDEREDLIST>
+    </SECTION>
+    
+    <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. Or, you have a
+	bug that you plan to fix for 2.8, this would have a milestone of 2.8.
+      </PARA>
+      <NOTE>
+	<PARA>
+	  Milestone options will only appear for a Product if you turned the "usetargetmilestone" field
+	  in the "Edit Parameters" screen "On".
+	</PARA>
+      </NOTE>
+      <PARA>
+	To create new Milestones, set Default Milestones, and set Milestone URL: 
+      </PARA>
+      <ORDEREDLIST>
+	<LISTITEM>
+	  <PARA>
+	    Select "edit milestones"
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Select "Add" to the right of the "Add a new milestone" 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.
+	    Select "Add".
+	  </PARA>
+	  <EXAMPLE>
+	    <TITLE>Using SortKey with Target Milestone</TITLE>
+	    <INFORMALEXAMPLE>
+	      <PARA>
+		Let's say you create a target milestone called "Release 1.0", with Sortkey set to "0".
+		Later, you realize that you will have a public beta, called "Beta1".
+		You can create a Milestone called "Beta1", with a Sortkey of "-1" in order to ensure
+		people will see the Target Milestone of "Beta1" earlier on the list than "Release 1.0"
+	      </PARA>
+	    </INFORMALEXAMPLE>
+	  </EXAMPLE>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    If you want to add more milestones, select the "Edit" link.
+	    If you don't, well shoot, you have to go back to the "query" page and select "components"
+	    again, and make your way back to the Product you were editing.
+	    <NOTE>
+	      <PARA>
+		This is another in the list of unusual user interface decisions that
+		we'd like to get cleaned up.  Shouldn't there be a link to the effect of
+		"edit the Product I was editing when I ended up here"?  In any case,
+		clicking "components" in the footer takes you back to the "Select product"
+		screen, from which you can begin editing your product again.
+	      </PARA>
+	    </NOTE>
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    From the Edit Product screen again (once you've made your way back), enter the URL
+	    for a description of what your milestones are for this product in the "Milestone URL" field.
+	    It should be of the format "http://www.foo.com/bugzilla/product_milestones.html"
+	  </PARA>
+	  <PARA>
+	    Some common uses of this field include product descriptions, product roadmaps,
+	    and of course a simple description of the meaning of each milestone.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    If you're using Target Milestones, the "Default Milestone" field must have some
+	    kind of entry.  If you really don't care if people set coherent Target Milestones, 
+	    simply leave this at the default, "---".  However, controlling and regularly updating the Default
+	    Milestone field is a powerful tool when reporting the status of projects.
+	  </PARA>
+	  <PARA>Select the "Update" button when you are done.</PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    
+	  </PARA>
+	</LISTITEM>
+      </ORDEREDLIST>
+    </SECTION>
+    
+    <SECTION id="voting">
+      <TITLE>Voting</TITLE>
+      <PARA>
+	The concept of "voting" is a poorly understood, yet powerful feature for the management
+	of open-source projects.  Each user is assigned so many Votes per product, which they can
+	freely reassign (or assign multiple votes to a single bug).
+	This allows developers to gauge user need for a particular enhancement
+	or bugfix.  By allowing bugs with a certain number of votes to automatically move from
+	"UNCONFIRMED" to "NEW", users of the bug system can help high-priority bugs garner
+	attention so they don't sit for a long time awaiting triage.
+      </PARA>
+      <PARA>
+	The daunting challenge of Votes is deciding where you draw the line for a "vocal majority".  If you
+	only have a user base of 100 users, setting a low threshold for bugs to move from UNCONFIRMED
+	to NEW makes sense.  As the Bugzilla user base expands, however, these thresholds must be
+	re-evaluated.  You should gauge whether this feature is worth the time and close monitoring involved,
+	and perhaps forego implementation until you have a critical mass of users who demand it.
+      </PARA>
+      <PARA>To modify Voting settings:</PARA>
+      <ORDEREDLIST>
+	<LISTITEM>
+	  <PARA>
+	    Navigate to the "Edit Product" screen for the Product you wish to modify
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Set "Maximum Votes per person" to your calculated value.  Setting this field
+	    to "0" disables voting.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Set "Maximum Votes a person can put on a single bug" to your calculated value.  It
+	    should probably be some number lower than the "Maximum votes per person".
+	    Setting this field to "0" disables voting, but leaves the voting options open
+	    to the user.  This is confusing.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Set "Number of votes a bug in this product needs to automatically get out of the
+	    UNCONFIRMED state" to your calculated number.  Setting this field to "0" 
+	    disables the automatic move of bugs from UNCONFIRMED to NEW.  Some people
+	    advocate leaving this at "0", but of what use are Votes if your Bugzilla
+	    user base is unable to affect which bugs appear on Development radar?
+	    <TIP>
+	      <PARA>
+		You should probably set this number to higher than a small coalition of
+		Bugzilla users can influence it.  Most sites use this as a "referendum"
+		mechanism -- if users are able to vote a bug out of UNCONFIRMED, it
+		is a <EMPHASIS>really</EMPHASIS> bad bug!
+	      </PARA>
+	    </TIP>
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Once you have adjusted the values to your preference, select the "Update" button.
+	  </PARA>
+	</LISTITEM>
+      </ORDEREDLIST>
+    </SECTION>    
+
+    <SECTION id="groups">
+      <TITLE>Groups and Group Security</TITLE>
+      <PARA>
+	Groups can be very useful in bugzilla, because they allow users to isolate
+	bugs or products that should only be seen by certain people.  Groups can also
+	be a complicated minefield of interdependencies and weirdness if mismanaged.
+
+	<EXAMPLE>
+	  <TITLE>When to Use Group Security</TITLE>
+	  <INFORMALEXAMPLE>
+	    <PARA>
+	      Many Bugzilla sites isolate "Security-related" bugs from all other bugs.
+	      This way, they can have a fix ready before the security vulnerability
+	      is announced to the world.  You can create a "Security" product which, by
+	      default, has no members, and only add members to the group (in their individual
+	      User page, as described under User Administration) who should have
+	      priveleged access to "Security" bugs.  Alternately, you may create a Group
+	      independently of any Product, and change the Group mask on individual bugs
+	      to restrict access to members only of certain Groups.
+	    </PARA>
+	  </INFORMALEXAMPLE>
+	</EXAMPLE>
+	
+	Groups only work if you enable the "usebuggroups" paramater.
+	In addition, if the "usebuggroupsentry" parameter is "On", one can restrict access
+	to products by groups, so that only members of a product group are able to view
+	bugs within that product.
+	Group security in Bugzilla can be divided into two categories:
+	Generic and Product-Based.
+      </PARA>
+      <NOTE>
+	<PARA>
+	  Groups in Bugzilla are a complicated beast that evolved out of very simple user
+	  permission bitmasks, apparently itself derived from common concepts in UNIX access
+	  controls.  A "bitmask" is a fixed-length number whose value can describe one, and
+	  only one, set of states.  For instance, UNIX file permissions are assigned bitmask
+	  values:  "execute" has a value of 1, "write" has a value of 2, 
+	  and "read" has a value of 4.  Add them together,
+	  and a file can be read, written to, and executed if it has a bitmask of "7". (This
+	  is a simplified example -- anybody who knows UNIX security knows there is much
+	  more to it than this.  Please bear with me for the purpose of this note.)  The only
+	  way a bitmask scheme can work is by doubling the bit count for each value.  Thus
+	  if UNIX wanted to offer another file permission, the next would have to be a value of
+	  8, then the next 16, the next 32, etc.
+	</PARA>
+	<PARA>
+	  Similarly, Bugzilla offers a bitmask to define group permissions, with an internal
+	  limit of 64.  Several are already occupied
+	  by built-in permissions.  The way around this limitation is
+	  to avoid assigning groups to products if you have many products, avoid bloating
+	  of group lists, and religiously prune irrelevant groups.  In reality, most installations
+	  of Bugzilla support far fewer than 64 groups, so this limitation has not hit
+	  for most sites, but it is on the table to be revised for Bugzilla 3.0
+	  because it interferes with the security schemes of some administrators.
+	</PARA>
+      </NOTE>
+      <PARA>
+	To enable Generic Group Security ("usebuggroups"):
+      </PARA>
+      <ORDEREDLIST>
+	<LISTITEM>
+	  <PARA>
+	    Turn "On" "usebuggroups" in the "Edit Parameters" screen.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    You will generally have no groups set up.  Select the "groups" link
+	    in the footer.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Take a moment to understand the instructions on the "Edit Groups" screen.
+	    Once you feel confident you understand what is expected of you, select the
+	    "Add Group" link.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Fill out the "New Name" (remember, no spaces!), "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.
+
+	    <EXAMPLE>
+	      <TITLE>Creating a New Group</TITLE>
+	      <INFORMALEXAMPLE>
+		<PARA>
+		  I created a group called "DefaultGroup" with a description of "This is simply
+		  a group to play with", and a "New User RegExp" of "*@velio.com".  This
+		  new group automatically includes all Bugzilla users with "@velio.com" at the
+		  end of their user id.  When I finished, my new group was assigned bit #128.
+		</PARA>
+	      </INFORMALEXAMPLE>
+	    </EXAMPLE>
+	    
+	    When you have finished, select the "Add" button.
+	  </PARA>
+	</LISTITEM>
+      </ORDEREDLIST>
+
+      <PARA>
+	To enable Product-Based Group Security ("usebuggroupsentry"):
+      </PARA>
+      <WARNING>
+	<PARA>
+	  Don't forget that you only have 64 groups masks available, total, for
+	  your installation of Bugzilla!  If you plan on having more than 50
+	  products in your individual Bugzilla installation, and require group
+	  security for your products, you should
+	  consider either running multiple Bugzillas or using Generic Group Security
+	  instead of Product-Based ("usebuggroupsentry") Group Security.
+	</PARA>
+      </WARNING>
+      <ORDEREDLIST>
+	<LISTITEM>
+	  <PARA>
+	    Turn "On" "usebuggroups" and "usebuggroupsentry" in the "Edit Parameters" screen.
+	  </PARA>
+	  <WARNING>
+	    <PARA>
+	      "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>
+	    You will generally have no Groups set up, unless you enabled "usebuggroupsentry"
+	    prior to creating any Products.  To create "Generic Group Security" groups,
+	    follow the instructions given above.  To create Product-Based Group security,
+	    simply follow the instructions for creating a new Product.  If you need to
+	    add users to these new groups as you create them, you will find the option
+	    to add them to the group available under the "Edit User" screens.
+	  </PARA>
+	</LISTITEM>
+      </ORDEREDLIST>
+    </SECTION>
+  </SECTION>
+  
+  <SECTION id="security">
+    <TITLE>Bugzilla Security</TITLE>
+    <EPIGRAPH>
+      <PARA>
+	Putting your money in a wall safe is better protection than depending on the fact that
+	no one knows that you hide your money in a mayonnaise jar in your fridge.
+      </PARA>
+    </EPIGRAPH>
+    <NOTE>
+      <PARA>
+	Poorly-configured MySQL, Bugzilla, and FTP 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>
+    </NOTE>
+    <PARA>
+      First thing's first: Secure your installation.
+      <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>
+      <ORDEREDLIST>
+	<LISTITEM>
+	  <PARA>
+	    Ensure you are running at least MysQL version 3.22.32 or newer.  Earlier versions had
+	    notable security holes and poorly secured default configuration choices.
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA><EMPHASIS>There is no substitute for understanding the tools on your system!</EMPHASIS>
+	    Read <ULINK URL="http://www.mysql.com/documentation/mysql/bychapter/manual_Privilege_system.html">
+	  The MySQL Privelege System</ULINK> until you can recite it from memory!</PARA>
+	  <PARA>
+	    At the very least, ensure you password the "mysql -u root" account and the "bugs" account, establish grant
+	    table rights (consult the Keystone guide in Appendix C: The Bugzilla Database for some easy-to-use details)
+	    that do not allow CREATE, DROP, RELOAD, SHUTDOWN, and PROCESS for user "bugs".  I wrote up the Keystone
+	    advice back when I knew far less about security than I do now : )
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <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>Do not run Apache as "nobody".  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.</PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    Ensure you have adequate access controls for $BUGZILLA_HOME/data/ and $BUGZILLA_HOME/localconfig.
+	    The localconfig file stores your "bugs" user password, which would be terrible to have in the hands
+	    of a criminal.  Also some files under $BUGZILLA_HOME/data store sensitive information.
+	  </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> 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/ and shadow/ directories. 
+	  </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>
+	    Place the following text into a file named ".htaccess", readable by your web server,
+	    in your $BUGZILLA_HOME/shadow directory.
+	    <LITERALLAYOUT>
+	      deny from all
+	    </LITERALLAYOUT>
+	  </PARA>
+	</LISTITEM>
+	<LISTITEM>
+	  <PARA>
+	    
+	  </PARA>
+	</LISTITEM>
+
+      </ORDEREDLIST>
+    </PARA>
+  </SECTION>
+</CHAPTER>
+
+
+<!-- Keep this comment at the end of the file
+Local variables:
+mode: sgml
+sgml-omittag:t
+sgml-shorttag:t
+sgml-namecase-general:t
+sgml-general-insert-case:upper
+sgml-minimize-attributes:nil
+sgml-always-quote-attributes:t
+sgml-indent-step:2
+sgml-indent-data:t
+sgml-parent-document:nil
+sgml-exposed-tags:nil
+sgml-local-catalogs:nil
+sgml-local-ecat-files:nil
+End:
+-->