-<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
-<chapter id="administration">
- <title>Administering Bugzilla</title>
-
- <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>
-
- <indexterm>
- <primary>checklist</primary>
- </indexterm>
-
- <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>
- </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>
- </step>
-
- <step>
- <para>
- <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>
- </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>
-
- <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>:
-
- 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.
- :-)
- </para>
- </step>
-
- <step>
- <para>
- <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>
-
- <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>
- </step>
-
- <step>
- <para>
- <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>
- </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.
- </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>
- </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.
- <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>
- <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>
- </step>
- </procedure>
- </section>
-
- <section id="useradmin">
- <title>User Administration</title>
-
- <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 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, 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>
- </tip>
- </section>
-
- <section id="manageusers">
- <title>Managing Other Users</title>
-
- <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 (assuming they
- aren't logged in as someone else already.) 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, and then click "Add a new user".</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.
- While useful for creating dummy accounts (watchers which
- shuttle mail to another system, for instance, or email
- addresses which are a mailing list), in general it is
- preferable to log out and use the
- <quote>New Account</quote>
-
- 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="modifyusers">
- <title>Modifying Users</title>
-
- <para>To see a specific user, search for their login name
- in the box provided on the "Edit Users" page. To see all users,
- leave the box blank.</para>
-
- <para>You can search in different ways the listbox to the right
- of the text entry box. You can match by
- case-insensitive substring (the default),
- regular expression, or a
- <emphasis>reverse</emphasis>
- regular expression match, which finds every user name which does NOT
- match the regular expression. (Please see
- the <command>man regexp</command>
- manual page for details on regular expression syntax.)
- </para>
-
- <para>Once you have found your user, you can change the following
- fields:</para>
-
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>Login Name</emphasis>:
- This is generally the user's full email address. However, if you
- have are using the emailsuffix Param, this may just be the user's
- login name. Note that users can now change their login names
- themselves (to any valid email address.)
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>Real Name</emphasis>: The user's real name. Note that
- Bugzilla does not require this to create an account.</para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>Password</emphasis>:
- You can change the user's password here. Users can automatically
- request a new password, so you shouldn't need to do this often.
- If you want to disable an account, see Disable Text below.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>Disable Text</emphasis>:
- If you type anything in this box, including just a space, the
- user is prevented from logging in, or making any changes to
- bugs via the web interface.
- The HTML you type in this box is presented to the user when
- they attempt to perform these actions, and should explain
- why the account was disabled.
- <warning>
- <para>Don't disable all the administrator accounts!</para>
- </warning>
-
- <note>
- <para>The user can still submit bugs via
- the e-mail gateway, if you set it up, even if the disabled text
- field is filled in. The e-mail gateway should
- <emphasis>not</emphasis>
- be enabled for secure installations of Bugzilla.</para>
- </note>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis><groupname></emphasis>:
- If you have created some groups, e.g. "securitysensitive", then
- checkboxes will appear here to allow you to add users to, or
- remove them from, these groups.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>canconfirm</emphasis>:
- This field is only used if you have enabled the "unconfirmed"
- status. If you enable this for a user,
- that user can then move bugs from "Unconfirmed" to a "Confirmed"
- status (e.g.: "New" status).</para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>creategroups</emphasis>:
- This option will allow a user to create and destroy groups in
- Bugzilla.</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. Even if this
- option is unchecked, users can still add comments to bugs.
- </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.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>editkeywords</emphasis>:
- If you use Bugzilla's keyword functionality, enabling this
- feature allows a user to 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.</para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis>editusers</emphasis>:
- This flag allows a user to do what you're doing right now: edit
- other users. This will allow those with the right to do so to
- remove administrator privileges from other users or grant them to
- themselves. Enable with care.</para>
- </listitem>
-
-
- <listitem>
- <para>
- <emphasis>tweakparams</emphasis>:
- This flag allows a user to change Bugzilla's Params
- (using <filename>editparams.cgi</filename>.)</para>
- </listitem>
-
- <listitem>
- <para>
- <emphasis><productname></emphasis>:
- This allows an administrator to specify the products in which
- a user can see bugs. The user must still have the
- "editbugs" privilege to edit bugs in these products.</para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- </section>
-
- <section id="products">
- <title>Products</title>
-
- <para>
- <glossterm linkend="gloss-product" baseform="product">
- Products</glossterm>
-
- 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>Many of Bugzilla's settings are configurable on a per-product
- basis. The number of "votes" available to users is set per-product,
- as is the number of votes
- required to move a bug automatically from the UNCONFIRMED status to the
- NEW status.</para>
-
- <para>To create a new product:</para>
-
- <orderedlist>
- <listitem>
- <para>Select "products" from the footer</para>
-
- </listitem>
-
- <listitem>
- <para>Select the "Add" link in the bottom right</para>
- </listitem>
-
- <listitem>
- <para>Enter the name of the product and a description. The
- Description field may contain HTML.</para>
- </listitem>
- </orderedlist>
-
- <para>Don't worry about the "Closed for bug entry", "Maximum Votes
- per person", "Maximum votes a person can put on a single bug",
- "Number of votes a bug in this Product needs to automatically get out
- of the UNCOMFIRMED state", and "Version" options yet. We'll cover
- those in a few moments.
- </para>
- </section>
-
- <section id="components">
- <title>Components</title>
-
- <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>
-
- <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>
-
- <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>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". 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>
-
- </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.</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>
-
- <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>
-
- <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>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>
- </section>
-
- <section id="voting">
- <title>Voting</title>
-
- <para>Voting allows users to be given a pot of votes which they can allocate
- to bugs, to indicate that they'd like them fixed.
- 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>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><emphasis>Maximum Votes per person</emphasis>:
- Setting this field to "0" disables voting.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Maximum Votes a person can put on a single
- 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
- any sense.</para>
- </listitem>
-
- <listitem>
- <para><emphasis>Number of votes a bug in this product needs to
- automatically get out of the UNCONFIRMED state</emphasis>:
- Setting this field to "0" disables the automatic move of
- bugs from UNCONFIRMED to NEW.
- </para>
- </listitem>
-
- <listitem>
- <para>Once you have adjusted the values to your preference, click
- "Update".</para>
- </listitem>
- </orderedlist>
- </section>
-
- <section id="groups">
- <title>Groups and Group Security</title>
-
- <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>
+<!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
+-->
- <para>
- If the makeproductgroups param is on, a new group will be automatically
- created for every new product.
- </para>
+<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 business 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>
+ Bring up "editparams.cgi" in your web browser. For instance, to edit parameters
+ at mozilla.org, the URL would be <ULINK URL="http://bugzilla.mozilla.org/editparams.cgi">
+ http://bugzilla.mozilla.org/editparams.cgi</ULINK>, also available under the "edit parameters"
+ link on your query page.
+ </PARA>
+ </STEP>
+ <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 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>
+ Ensure "newemailtech" is "on".
+ Your users will thank you. This is the default in the post-2.12 world, and is
+ only an issue if you are upgrading.
+ </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>
+
+ <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>
- <para>
- On the product edit page, there is a page to edit the
- <quote>Group Controls</quote>
- for a product and determine which groups are applicable, default,
- and mandatory for each product as well as controlling entry
- for each product and being able to set bugs in a product to be
- totally read-only unless some group restrictions are met.
- </para>
+ <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>
- <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>
+ <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>
- <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>
- <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>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>
-
- <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.
- </para>
- </section>
-
- <section id="upgrading">
- <title>Upgrading to New Releases</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>
- </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>
-
- <itemizedlist>
- <listitem>
- <para>If the new version is a revision or a new point release</para>
- </listitem>
- <listitem>
- <para>How many, if any, local changes have been made</para>
- </listitem>
- </itemizedlist>
-
- <para>There are also three different methods to upgrade your installation.
- </para>
-
- <orderedlist>
- <listitem>
- <para>Using CVS (<xref linkend="upgrade-cvs"/>)</para>
- </listitem>
- <listitem>
- <para>Downloading a new tarball (<xref linkend="upgrade-tarball"/>)</para>
- </listitem>
- <listitem>
- <para>Applying the relevant patches (<xref linkend="upgrade-patches"/>)</para>
- </listitem>
- </orderedlist>
-
- <para>Which options are available to you may depend on how large a jump
- you are making and/or your network configuration.
- </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.2 was released, it was a revision to 2.16.1.
- </para>
-
- <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.16.2 is a newer point
- release than 2.14.5.
- </para>
-
- <para>The examples in this section are written as if you were updating
- to version 2.16.2. 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>
-
- <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.
- </para>
-
- <example id="upgrade-cvs">
- <title>Upgrading using CVS</title>
-
- <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.
-
- <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>
-
- <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_16_2 -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>
- <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>
-
- <note>
- <para>You also need to run <command>./checksetup.pl</command>
- before your Bugzilla upgrade will be complete.
- </para>
- </note>
- </para>
- </example>
-
- <example id="upgrade-tarball">
- <title>Upgrading using the tarball</title>
-
- <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>
-
- <programlisting>
-bash$ <command>cd /var/www/html</command>
-bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz</command>
-<emphasis>Output omitted</emphasis>
-bash$ <command>tar xzvf bugzilla-2.16.2.tar.gz</command>
-bugzilla-2.16.2/
-bugzilla-2.16.2/.cvsignore
-bugzilla-2.16.2/1x1.gif
-<emphasis>Output truncated</emphasis>
-bash$ <command>cd bugzilla-2.16.2</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.16.2 bugzilla</command>
-bash$ <command>cd bugzilla</command>
-bash$ <command>./checksetup.pl</command>
-<emphasis>Output omitted</emphasis>
- </programlisting>
-
- <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>
-
- <note>
- <para>You will now have to reapply any changes you have made to your
- local installation manually.
- </para>
- </note>
- </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>
-
- <programlisting>
-bash$ <command>cd /var/www/html/bugzilla</command>
-bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz</command>
-<emphasis>Output omitted</emphasis>
-bash$ <command>gunzip bugzilla-2.16.1-to-2.16.2.diff.gz</command>
-bash$ <command>patch -p1 < bugzilla-2.16.1-to-2.16.2.diff</command>
-patching file checksetup.pl
-patching file collectstats.pl
-patching file globals.pl
- </programlisting>
-
- <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>
- </para>
- </example>
+ <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 the $BUGZILLA_HOME/data/ and
+ $BUGZILLA_HOME/shadow/ directories, as well as the $BUGZILLA_HOME/localconfig file.
+ 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, and
+ $BUGZILLA_HOME/shadow/ stores bug information for faster retrieval. If you fail to secure
+ these directories and this file, you will expose bug information to those who may not
+ be allowed to see it.
+ </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>
+ <Files comments>
+ allow from all
+ </Files>
+ 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>
+ <Files localconfig>
+ deny from all
+ </Files>
+ 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>
+ </ORDEREDLIST>
+ </PARA>
+ </SECTION>
+</CHAPTER>
- </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-auto-insert-required-elements:t
-sgml-balanced-tag-edit:t
-sgml-exposed-tags:nil
-sgml-general-insert-case:lower
-sgml-indent-data: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
-sgml-minimize-attributes:nil
-sgml-namecase-general:t
-sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
-sgml-shorttag:t
-sgml-tag-region-if-active:t
End:
-->
-
projects / thirdparty / bugzilla.git / commitdiff
