1908 lines
74 KiB
XML
1908 lines
74 KiB
XML
<!-- <!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>
|
|
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term>
|
|
maintainer
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
urlbase
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
makeproductgroups
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This dictates whether or not to automatically create groups
|
|
when new products are created.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
useentrygroupdefault
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
maildeliverymethod
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This is used to specify how email is sent, or if it is sent at
|
|
all. There are several options included for different MTAs,
|
|
along with two additional options that disable email sending.
|
|
"testfile" does not send mail, but instead saves it in
|
|
<filename>data/mailer.testfile</filename> for later review.
|
|
"none" disables email sending entirely.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
shadowdb
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
shutdownhtml
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If you need to shut down Bugzilla to perform administration, enter
|
|
some descriptive text (with embedded HTML codes, if you'd like)
|
|
into this box. Anyone who tries to use Bugzilla (including admins)
|
|
will receive a page displaying this text. Users can neither log in
|
|
nor log out while shutdownhtml is enabled.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Although regular log-in capability is disabled while 'shutdownhtml'
|
|
is enabled, safeguards are in place to protect the unfortunate
|
|
admin who loses connection to Bugzilla. Should this happen to you,
|
|
go directly to the <filename>editparams.cgi</filename> (by typing
|
|
the URL in manually, if necessary). Doing this will prompt you to
|
|
log in, and your name/password will be accepted here (but nowhere
|
|
else).
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
movebugs
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
useqacontact
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This allows you to define an email address for each component,
|
|
in addition to that of the default assignee, who will be sent
|
|
carbon copies of incoming bugs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
globalwatcher
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This allows to define specific users that will
|
|
receive notification each time a new bug in entered, or when
|
|
an existing bug changes, according to the normal groupset
|
|
permissions. It may be useful for sending notifications to a
|
|
mailing-list, for instance.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
usestatuswhiteboard
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
whinedays
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
commenton*
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
All these fields allow you to dictate what changes can pass
|
|
without comment, and which must have a comment from the
|
|
person who changed them. Often, administrators will allow
|
|
users to add themselves to the CC list, accept bugs, or
|
|
change the Status Whiteboard without adding a comment as to
|
|
their reasons for the change, yet require that most other
|
|
changes come with an explanation.
|
|
</para>
|
|
|
|
<para>
|
|
Set the "commenton" options according to your site policy. It
|
|
is a wise idea to require comments when users resolve, reassign, or
|
|
reopen bugs at the very least.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
It is generally far better to require a developer comment
|
|
when resolving bugs than not. Few things are more annoying to bug
|
|
database users than having a developer mark a bug "fixed" without
|
|
any comment as to what the fix was (or even that it was truly
|
|
fixed!)
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
supportwatchers
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Turning on this option allows users to ask to receive copies
|
|
of bug mail sent to another user. Watching a user with
|
|
different group permissions is not a way to 'get around' the
|
|
system; copied emails are still subject to the normal groupset
|
|
permissions of a bug, and <quote>watchers</quote> will only be
|
|
copied on emails from bugs they would normally be allowed to view.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
|
|
<varlistentry>
|
|
<term>
|
|
noresolveonopenblockers
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This option will prevent users from resolving bugs as FIXED if
|
|
they have unresolved dependencies. Only the FIXED resolution
|
|
is affected. Users will be still able to resolve bugs to
|
|
resolutions other than FIXED if they have unresolved dependent
|
|
bugs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
sendmailnow
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
When Bugzilla is using Sendmail older than 8.12, turning this option
|
|
off will improve performance by not waiting for Sendmail to actually
|
|
send mail. If Sendmail 8.12 or later is being used, there is
|
|
nothing to gain by turning this off. If another MTA is being used,
|
|
such as Postfix, then this option *must* be turned on (even if you
|
|
are using the fake sendmail executable that Postfix provides).
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
</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.
|
|
</para>
|
|
<para>
|
|
Users with disabled accounts will continue to receive
|
|
mail from Bugzilla; furthermore, they will not be able
|
|
to log in themselves to change their own preferences and
|
|
stop it. If you want an account (disabled or active) to
|
|
stop receiving mail, add the account name (one account
|
|
per line) to the file <filename>data/nomail</filename>.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Even users whose accounts have been disabled can still
|
|
submit bugs via the e-mail gateway, if one exists.
|
|
The e-mail gateway should <emphasis>not</emphasis> be
|
|
enabled for secure installations of Bugzilla.
|
|
</para>
|
|
</note>
|
|
<warning>
|
|
<para>
|
|
Don't disable all the administrator accounts!
|
|
</para>
|
|
</warning>
|
|
</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 id="impersonatingusers">
|
|
<title>Impersonating Users</title>
|
|
|
|
<para>
|
|
There may be times when an administrator would like to do something as
|
|
another user. The <command>sudo</command> feature may be used to do
|
|
this.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
To use the sudo feature, you must be in the
|
|
<emphasis>bz_sudoers</emphasis> group. By default, all
|
|
administrators are in this group.</para>
|
|
</note>
|
|
|
|
<para>
|
|
If you have access to this feature, you may start a session by
|
|
going to the Edit Users page, Searching for a user and clicking on
|
|
their login. You should see a link below their login name titled
|
|
"Impersonate this user". Click on the link. This will take you
|
|
to a page where you will see a description of the feature and
|
|
instructions for using it. After reading the text, simply
|
|
enter the login of the user you would like to impersonate, provide
|
|
a short message explaining why you are doing this, and press the
|
|
button.</para>
|
|
|
|
<para>
|
|
As long as you are using this feature, everything you do will be done
|
|
as if you were logged in as the user you are impersonating.</para>
|
|
|
|
<warning>
|
|
<para>
|
|
The user you are impersonating will not be told about what you are
|
|
doing. If you do anything that results in mail being sent, that
|
|
mail will appear to be from the user you are impersonating. You
|
|
should be extremely careful while using this feature.</para>
|
|
</warning>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="classifications">
|
|
<title>Classifications</title>
|
|
|
|
<para>Classifications tend to be used in order to group several related
|
|
products into one distinct entity.</para>
|
|
|
|
<para>The classifications layer is disabled by default; it can be turned
|
|
on or off using the useclassification parameter,
|
|
in the <emphasis>Bug Fields</emphasis> section of the edit parameters screen.</para>
|
|
|
|
<para>Access to the administration of classifications is controlled using
|
|
the <emphasis>editclassifications</emphasis> system group, which defines
|
|
a privilege for creating, destroying, and editing classifications.</para>
|
|
|
|
<para>When activated, classifications will introduce an additional
|
|
step when filling bugs (dedicated to classification selection), and they
|
|
will also appear in the advanced search form.</para>
|
|
</section>
|
|
|
|
<section id="products">
|
|
<title>Products</title>
|
|
|
|
<para>
|
|
<glossterm linkend="gloss-product" baseform="product">
|
|
Products</glossterm>
|
|
|
|
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 UNCONFIRMED 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 default assignee and (if you turned it on in the parameters),
|
|
a QA Contact. The default assignee 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 Assignee, QA Contact, and Reporter
|
|
will get email when new bugs are created in this Component and when
|
|
these bugs change. Default Assignee 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 "Default Assignee" and "Default QA Contact" (if enabled.)
|
|
The Component and Description fields may contain HTML;
|
|
the "Default Assignee" 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 (-32768 to 32767) 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="flags-overview">
|
|
<title>Flags</title>
|
|
|
|
<para>
|
|
Flags are a way to attach a specific status to a bug or attachment,
|
|
either <quote>+</quote> or <quote>-</quote>. The meaning of these symbols depends on the text
|
|
the flag itself, but contextually they could mean pass/fail,
|
|
accept/reject, approved/denied, or even a simple yes/no. If your site
|
|
allows requestable flags, then users may set a flag to <quote>?</quote> as a
|
|
request to another user that they look at the bug/attachment, and set
|
|
the flag to its correct status.
|
|
</para>
|
|
|
|
<section id="flags-simpleexample">
|
|
<title>A Simple Example</title>
|
|
|
|
<para>
|
|
A developer might want to ask their manager,
|
|
<quote>Should we fix this bug before we release version 2.0?</quote>
|
|
They might want to do this for a <emphasis>lot</emphasis> of bugs,
|
|
so it would be nice to streamline the process...
|
|
</para>
|
|
<para>
|
|
In Bugzilla, it would work this way:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
The Bugzilla administrator creates a flag type called
|
|
<quote>blocking2.0</quote> that shows up on all bugs in
|
|
your product.
|
|
</para>
|
|
|
|
<para>
|
|
It shows up on the <quote>Show Bug</quote> screen
|
|
as the text <quote>blocking2.0</quote> with a drop-down box next
|
|
to it. The drop-down box contains four values: an empty space,
|
|
<quote>?</quote>, <quote>-</quote>, and <quote>+</quote>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The developer sets the flag to <quote>?</quote>.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
The manager sees the <computeroutput>blocking2.0</computeroutput>
|
|
flag with a <quote>?</quote> value.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
If the manager thinks the feature should go into the product
|
|
before version 2.0 can be released, he sets the flag to
|
|
<quote>+</quote>. Otherwise, he sets it to <quote>-</quote>.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Now, every Bugzilla user who looks at the bug knows whether or
|
|
not the bug needs to be fixed before release of version 2.0.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="flags-about">
|
|
<title>About Flags</title>
|
|
|
|
<section id="flag-values">
|
|
<title>Values</title>
|
|
<para>
|
|
Flags can have three values:
|
|
<variablelist>
|
|
<varlistentry>
|
|
<term><computeroutput>?</computeroutput></term>
|
|
<listitem><simpara>
|
|
A user is requesting that a status be set. (Think of it as 'A question is being asked'.)
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><computeroutput>-</computeroutput></term>
|
|
<listitem><simpara>
|
|
The status has been set negatively. (The question has been answered <quote>no</quote>.)
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
<varlistentry>
|
|
<term><computeroutput>+</computeroutput></term>
|
|
<listitem><simpara>
|
|
The status has been set positively.
|
|
(The question has been answered <quote>yes</quote>.)
|
|
</simpara></listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
</para>
|
|
<para>
|
|
Actually, there's a fourth value a flag can have --
|
|
<quote>unset</quote> -- which shows up as a blank space. This
|
|
just means that nobody has expressed an opinion (or asked
|
|
someone else to express an opinion) about this bug or attachment.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="flag-askto">
|
|
<title>Using flag requests</title>
|
|
<para>
|
|
If a flag has been defined as 'requestable', and a user has enough privileges
|
|
to request it (see below), the user can set the flag's status to <quote>?</quote>.
|
|
This status indicates that someone (a.k.a. <quote>the requester</quote>) is asking
|
|
someone else to set the flag to either <quote>+</quote> or <quote>-</quote>.
|
|
</para>
|
|
<para>
|
|
If a flag has been defined as 'specifically requestable',
|
|
a text box will appear next to the flag into which the requester may
|
|
enter a Bugzilla username. That named person (a.k.a. <quote>the requestee</quote>)
|
|
will receive an email notifying them of the request, and pointing them
|
|
to the bug/attachment in question.
|
|
</para>
|
|
<para>
|
|
If a flag has <emphasis>not</emphasis> been defined as 'specifically requestable',
|
|
then no such text-box will appear. A request to set this flag cannot be made of
|
|
any specific individual, but must be asked <quote>to the wind</quote>.
|
|
A requester may <quote>ask the wind</quote> on any flag simply by leaving the text-box blank.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flag-types">
|
|
<title>Two Types of Flags</title>
|
|
|
|
<para>
|
|
Flags can go in two places: on an attachment, or on a bug.
|
|
</para>
|
|
|
|
<section id="flag-type-attachment">
|
|
<title>Attachment Flags</title>
|
|
|
|
<para>
|
|
Attachment flags are used to ask a question about a specific
|
|
attachment on a bug.
|
|
</para>
|
|
<para>
|
|
Many Bugzilla installations use this to
|
|
request that one developer <quote>review</quote> another
|
|
developer's code before they check it in. They attach the code to
|
|
a bug report, and then set a flag on that attachment called
|
|
<quote>review</quote> to
|
|
<computeroutput>review?boss@domain.com</computeroutput>.
|
|
boss@domain.com is then notified by email that
|
|
he has to check out that attachment and approve it or deny it.
|
|
</para>
|
|
|
|
<para>
|
|
For a Bugzilla user, attachment flags show up in three places:
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
On the list of attachments in the <quote>Show Bug</quote>
|
|
screen, you can see the current state of any flags that
|
|
have been set to ?, +, or -. You can see who asked about
|
|
the flag (the requester), and who is being asked (the
|
|
requestee).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
When you <quote>Edit</quote> an attachment, you can
|
|
see any settable flag, along with any flags that have
|
|
already been set. This <quote>Edit Attachment</quote>
|
|
screen is where you set flags to ?, -, +, or unset them.
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Requests are listed in the <quote>Request Queue</quote>, which
|
|
is accessible from the <quote>My Requests</quote> link (if you are
|
|
logged in) or <quote>Requests</quote> link (if you are logged out)
|
|
visible in the footer of all pages.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="flag-type-bug">
|
|
<title>Bug Flags</title>
|
|
|
|
<para>
|
|
Bug flags are used to set a status on the bug itself. You can
|
|
see Bug Flags in the <quote>Show Bug</quote> and <quote>Requests</quote>
|
|
screens, as described above.
|
|
</para>
|
|
<para>
|
|
Only users with enough privileges (see below) may set flags on bugs.
|
|
This doesn't necessarily include the assignee, reporter, or users with the
|
|
<computeroutput>editbugs</computeroutput> permission.
|
|
</para>
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="flags-admin">
|
|
<title>Administering Flags</title>
|
|
|
|
<para>
|
|
If you have the <quote>editcomponents</quote> permission, you will
|
|
have <quote>Edit: ... | Flags | ...</quote> in your page footer.
|
|
Clicking on that link will bring you to the <quote>Administer
|
|
Flag Types</quote> page. Here, you can select whether you want
|
|
to create (or edit) a Bug flag, or an Attachment flag.
|
|
</para>
|
|
<para>
|
|
No matter which you choose, the interface is the same, so we'll
|
|
just go over it once.
|
|
</para>
|
|
|
|
<section id="flags-create">
|
|
<title>Creating a Flag</title>
|
|
|
|
<para>
|
|
When you click on the <quote>Create a Flag Type for...</quote>
|
|
link, you will be presented with a form. Here is what the fields in
|
|
the form mean:
|
|
</para>
|
|
|
|
<section id="flags-create-field-name">
|
|
<title>Name</title>
|
|
<para>
|
|
This is the name of the flag. This will be displayed
|
|
to Bugzilla users who are looking at or setting the flag.
|
|
The name may contain any valid Unicode characters except commas
|
|
and spaces.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-field-description">
|
|
<title>Description</title>
|
|
<para>
|
|
The description describes the flag in more detail. It is visible
|
|
in a tooltip when hovering over a flag either in the <quote>Show Bug</quote>
|
|
or <quote>Edit Attachment</quote> pages. This field can be as
|
|
long as you like, and can contain any character you want.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-field-category">
|
|
<title>Category</title>
|
|
|
|
<para>
|
|
Default behaviour for a newly-created flag is to appear on
|
|
products and all components, which is why <quote>__Any__:__Any__</quote>
|
|
is already entered in the <quote>Inclusions</quote> box.
|
|
If this is not your desired behaviour, you must either set some
|
|
exclusions (for products on which you don't want the flag to appear),
|
|
or you must remove <quote>__Any__:__Any__</quote> from the Inclusions box
|
|
and define products/components specifically for this flag.
|
|
</para>
|
|
|
|
<para>
|
|
To create an Inclusion, select a Product from the top drop-down box.
|
|
You may also select a specific component from the bottom drop-down box.
|
|
(Setting <quote>__Any__</quote> for Product translates to,
|
|
<quote>all the products in this Bugzilla</quote>.
|
|
Selecting <quote>__Any__</quote> in the Component field means
|
|
<quote>all components in the selected product.</quote>)
|
|
Selections made, press <quote>Include</quote>, and your
|
|
Product/Component pairing will show up in the <quote>Inclusions</quote> box on the right.
|
|
</para>
|
|
|
|
<para>
|
|
To create an Exclusion, the process is the same; select a Product from the
|
|
top drop-down box, select a specific component if you want one, and press
|
|
<quote>Exclude</quote>. The Product/Component pairing will show up in the
|
|
<quote>Exclusions</quote> box on the right.
|
|
</para>
|
|
|
|
<para>
|
|
This flag <emphasis>will</emphasis> and <emphasis>can</emphasis> be set for any
|
|
products/components that appearing in the <quote>Inclusions</quote> box
|
|
(or which fall under the appropriate <quote>__Any__</quote>).
|
|
This flag <emphasis>will not</emphasis> appear (and therefore cannot be set) on
|
|
any products appearing in the <quote>Exclusions</quote> box.
|
|
<emphasis> IMPORTANT: Exclusions override inclusions.</emphasis>
|
|
</para>
|
|
|
|
<para>
|
|
You may select a Product without selecting a specific Component,
|
|
but you can't select a Component without a Product, or to select a
|
|
Component that does not belong to the named Product. If you do so,
|
|
Bugzilla will display an error message, even if all your products
|
|
have a component by that name.
|
|
</para>
|
|
|
|
<para><emphasis>Example:</emphasis> Let's say you have a product called
|
|
<quote>Jet Plane</quote> that has thousands of components. You want
|
|
to be able to ask if a problem should be fixed in the next model of
|
|
plane you release. We'll call the flag <quote>fixInNext</quote>.
|
|
But, there's one component in <quote>Jet Plane,</quote>
|
|
called <quote>Pilot.</quote> It doesn't make sense to release a
|
|
new pilot, so you don't want to have the flag show up in that component.
|
|
So, you include <quote>Jet Plane:__Any__</quote> and you exclude
|
|
<quote>Jet Plane:Pilot</quote>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-field-sortkey">
|
|
<title>Sort Key</title>
|
|
<para>
|
|
Flags normally show up in alphabetical order. If you want them to
|
|
show up in a different order, you can use this key set the order on each flag.
|
|
Flags with a lower sort key will appear before flags with a higher
|
|
sort key. Flags that have the same sort key will be sorted alphabetically,
|
|
but they will still be after flags with a lower sort key, and before flags
|
|
with a higher sort key.
|
|
</para>
|
|
<para>
|
|
<emphasis>Example:</emphasis> I have AFlag (Sort Key 100), BFlag (Sort Key 10),
|
|
CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in
|
|
the order: DFlag, BFlag, CFlag, AFlag.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-field-active">
|
|
<title>Active</title>
|
|
<para>
|
|
Sometimes, you might want to keep old flag information in the
|
|
Bugzilla database, but stop users from setting any new flags of this type.
|
|
To do this, uncheck <quote>active</quote>. Deactivated
|
|
flags will still show up in the UI if they are ?, +, or -, but they
|
|
may only be cleared (unset), and cannot be changed to a new value.
|
|
Once a deactivated flag is cleared, it will completely disappear from a
|
|
bug/attachment, and cannot be set again.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-field-requestable">
|
|
<title>Requestable</title>
|
|
<para>
|
|
New flags are, by default, <quote>requestable</quote>, meaning that they
|
|
offer users the <quote>?</quote> option, as well as <quote>+</quote>
|
|
and <quote>-</quote>.
|
|
To remove the ? option, uncheck <quote>requestable</quote>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-field-specific">
|
|
<title>Specifically Requestable</title>
|
|
<para>
|
|
By default this box is checked for new flags, meaning that users may make
|
|
flag requests of specific individuals. Unchecking this box will remove the
|
|
text box next to a flag; if it is still requestable, then requests may
|
|
only be made <quote>to the wind.</quote> Removing this after specific
|
|
requests have been made will not remove those requests; that data will
|
|
stay in the database (though it will no longer appear to the user).
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-field-multiplicable">
|
|
<title>Multiplicable</title>
|
|
<para>
|
|
Any flag with <quote>Multiplicable</quote> set (default for new flags is 'on')
|
|
may be set more than once. After being set once, an unset flag
|
|
of the same type will appear below it with <quote>addl.</quote> (short for
|
|
<quote>additional</quote>) before the name. There is no limit to the number of
|
|
times a Multiplicable flags may be set on the same bug/attachment.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-field-cclist">
|
|
<title>CC List</title>
|
|
|
|
<para>
|
|
If you want certain users to be notified every time this flag is
|
|
set to ?, -, +, or unset, add them here. This is a comma-separated
|
|
list of email addresses that need not be restricted to Bugzilla usernames.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-grant-group">
|
|
<title>Grant Group</title>
|
|
<para>
|
|
When this field is set to some given group, only users in the group
|
|
can set the flag to <quote>+</quote> and <quote>-</quote>. This
|
|
field does not affect who can request or cancel the flag. For that,
|
|
see the <quote>Request Group</quote> field below. If this field
|
|
is left blank, all users can set or delete this flag. This field is
|
|
useful for restricting which users can approve or reject requests.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="flags-create-request-group">
|
|
<title>Request Group</title>
|
|
<para>
|
|
When this field is set to some given group, only users in the group
|
|
can request or cancel this flag. Note that this field has no effect
|
|
if the <quote>grant group</quote> field is empty. You can set the
|
|
value of this field to a different group, but both fields have to be
|
|
set to a group for this field to have an effect.
|
|
</para>
|
|
</section>
|
|
</section> <!-- flags-create -->
|
|
|
|
<section id="flags-delete">
|
|
<title>Deleting a Flag</title>
|
|
|
|
<para>
|
|
When you are at the <quote>Administer Flag Types</quote> screen,
|
|
you will be presented with a list of Bug flags and a list of Attachment
|
|
Flags.
|
|
</para>
|
|
<para>
|
|
To delete a flag, click on the <quote>Delete</quote> link next to
|
|
the flag description.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
Once you delete a flag, it is <emphasis>gone</emphasis> from
|
|
your Bugzilla. All the data for that flag will be deleted.
|
|
Everywhere that flag was set, it will disappear,
|
|
and you cannot get that data back. If you want to keep flag data,
|
|
but don't want anybody to set any new flags or change current flags,
|
|
unset <quote>active</quote> in the flag Edit form.
|
|
</para>
|
|
</warning>
|
|
</section>
|
|
|
|
<section id="flags-edit">
|
|
<title>Editing a Flag</title>
|
|
<para>
|
|
To edit a flag's properties, just click on the <quote>Edit</quote>
|
|
link next to the flag's description. That will take you to the same
|
|
form described in the <quote>Creating a Flag</quote> section.
|
|
</para>
|
|
</section>
|
|
|
|
</section> <!-- flags-admin -->
|
|
|
|
<!-- XXX We should add a "Uses of Flags" section, here, with examples. -->
|
|
|
|
</section> <!-- flags -->
|
|
|
|
<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="quips">
|
|
<title>Quips</title>
|
|
|
|
<para>
|
|
Quips are small text messages that can be configured to appear
|
|
next to search results. A Bugzilla installation can have its own specific
|
|
quips. Whenever a quip needs to be displayed, a random selection
|
|
is made from the pool of already existing quips.
|
|
</para>
|
|
|
|
<para>
|
|
Quips are controlled by the <emphasis>enablequips</emphasis> parameter.
|
|
It has several possible values: on, approved, frozen or off.
|
|
In order to enable quips approval you need to set this parameter
|
|
to "approved". In this way, users are free to submit quips for
|
|
addition but an administrator must explicitly approve them before
|
|
they are actually used.
|
|
</para>
|
|
|
|
<para>
|
|
In order to see the user interface for the quips, it is enough to click
|
|
on a quip when it is displayed together with the search results. Or
|
|
it can be seen directly in the browser by visiting the quips.cgi URL
|
|
(prefixed with the usual web location of the Bugzilla installation).
|
|
Once the quip interface is displayed, it is enough to click the
|
|
"view and edit the whole quip list" in order to see the administration
|
|
page. A page with all the quips available in the database will
|
|
be displayed.
|
|
</para>
|
|
|
|
<para>
|
|
Next to each tip there is a checkbox, under the
|
|
"Approved" column. Quips who have this checkbox checked are
|
|
already approved and will appear next to the search results.
|
|
The ones that have it unchecked are still preserved in the
|
|
database but they will not appear on search results pages.
|
|
User submitted quips have initially the checkbox unchecked.
|
|
</para>
|
|
|
|
<para>
|
|
Also, there is a delete link next to each quip,
|
|
which can be used in order to permanently delete a quip.
|
|
</para>
|
|
</section>
|
|
|
|
<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>
|
|
|
|
<para>
|
|
If the makeproductgroups param is on, a new group will be automatically
|
|
created for every new product. It is primarily available for backward
|
|
compatibility with older sites.
|
|
</para>
|
|
<para>
|
|
Note that group permissions are such that you need to be a member
|
|
of <emphasis>all</emphasis> the groups a bug is in, for whatever
|
|
reason, to see that bug. Similarly, you must be a member
|
|
of <emphasis>all</emphasis> of the entry groups for a product
|
|
to add bugs to a product and you must be a member
|
|
of <emphasis>all</emphasis> of the canedit groups for a product
|
|
in order to make <emphasis>any</emphasis> change to bugs in that
|
|
product.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
By default, bugs can also be seen by the Assignee, the Reporter, and
|
|
by everyone on the CC List, regardless of whether or not the bug would
|
|
typically be viewable by them. Visibility to the Reporter and CC List can
|
|
be overridden (on a per-bug basis) by bringing up the bug, finding the
|
|
section that starts with <quote>Users in the roles selected below...</quote>
|
|
and un-checking the box next to either 'Reporter' or 'CC List' (or both).
|
|
</para>
|
|
</note>
|
|
<section>
|
|
<title>Creating Groups</title>
|
|
<para>To create Groups:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Select the <quote>groups</quote>
|
|
link in the footer.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Take a moment to understand the instructions on the <quote>Edit
|
|
Groups</quote> screen, then select the <quote>Add Group</quote> link.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fill out the <quote>Group</quote>, <quote>Description</quote>,
|
|
and <quote>User RegExp</quote> fields.
|
|
<quote>User RegExp</quote> allows you to automatically
|
|
place all users who fulfill the Regular Expression into the new group.
|
|
When you have finished, click <quote>Add</quote>.</para>
|
|
<para>Users whose email addresses match the regular expression
|
|
will automatically be members of the group as long as their
|
|
email addresses continue to match the regular expression.</para>
|
|
<note>
|
|
<para>This is a change from 2.16 where the regular expression
|
|
resulted in a user acquiring permanent membership in a group.
|
|
To remove a user from a group the user was in due to a regular
|
|
expression in version 2.16 or earlier, the user must be explicitly
|
|
removed from the group. This can easily be done by pressing
|
|
buttons named 'Remove Memberships' or 'Remove Memberships
|
|
included in regular expression' under the table.</para>
|
|
</note>
|
|
<warning>
|
|
<para>If specifying a domain in the regexp, make sure you end
|
|
the regexp with a $. Otherwise, when granting access to
|
|
"@mycompany\.com", you will allow access to
|
|
'badperson@mycompany.com.cracker.net'. You need to use
|
|
'@mycompany\.com$' as the regexp.</para>
|
|
</warning>
|
|
</listitem>
|
|
<listitem>
|
|
<para>If you plan to use this group to directly control
|
|
access to bugs, check the "use for bugs" box. Groups
|
|
not used for bugs are still useful because other groups
|
|
can include the group as a whole.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>After you add your new group, edit the new group. On the
|
|
edit page, you can specify other groups that should be included
|
|
in this group and which groups should be permitted to add and delete
|
|
users from this group.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
<section>
|
|
<title>Assigning Users to Groups</title>
|
|
<para>Users can become a member of a group in several ways.</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The user can be explicitly placed in the group by editing
|
|
the user's own profile</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The group can include another group of which the user is
|
|
a member.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>The user's email address can match a regular expression
|
|
that the group specifies to automatically grant membership to
|
|
the group.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Assigning Group Controls to Products</title>
|
|
<para>
|
|
On the product edit page, there is a page to edit the
|
|
<quote>Group Controls</quote>
|
|
for a product. This allows you to
|
|
configure how a group relates to the product.
|
|
Groups may be applicable, default,
|
|
and mandatory as well as used to control entry
|
|
or used to make bugs in the product
|
|
totally read-only unless the group restrictions are met.
|
|
</para>
|
|
|
|
<para>
|
|
For each group, it is possible to specify if membership in that
|
|
group is...
|
|
</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
required for bug entry,
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Not applicable to this product(NA),
|
|
a possible restriction for a member of the
|
|
group to place on a bug in this product(Shown),
|
|
a default restriction for a member of the
|
|
group to place on a bug in this product(Default),
|
|
or a mandatory restriction to be placed on bugs
|
|
in this product(Mandatory).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
Not applicable by non-members to this product(NA),
|
|
a possible restriction for a non-member of the
|
|
group to place on a bug in this product(Shown),
|
|
a default restriction for a non-member of the
|
|
group to place on a bug in this product(Default),
|
|
or a mandatory restriction to be placed on bugs
|
|
in this product when entered by a non-member(Mandatory).
|
|
</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>
|
|
required in order to make <emphasis>any</emphasis> change
|
|
to bugs in this product <emphasis>including comments.</emphasis>
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>These controls are often described in this order, so a
|
|
product that requires a user to be a member of group "foo"
|
|
to enter a bug and then requires that the bug stay restricted
|
|
to group "foo" at all times and that only members of group "foo"
|
|
can edit the bug even if they otherwise could see the bug would
|
|
have its controls summarized by...</para>
|
|
<programlisting>
|
|
foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
|
|
</programlisting>
|
|
|
|
</section>
|
|
<section>
|
|
<title>Common Applications of Group Controls</title>
|
|
<section>
|
|
<title>General User Access With Security Group</title>
|
|
<para>To permit any user to file bugs in each product (A, B, C...)
|
|
and to permit any user to submit those bugs into a security
|
|
group....</para>
|
|
<programlisting>
|
|
Product A...
|
|
security: SHOWN/SHOWN
|
|
Product B...
|
|
security: SHOWN/SHOWN
|
|
Product C...
|
|
security: SHOWN/SHOWN
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>General User Access With A Security Product</title>
|
|
<para>To permit any user to file bugs in a Security product
|
|
while keeping those bugs from becoming visible to anyone
|
|
outside the securityworkers group unless a member of the
|
|
securityworkers group removes that restriction....</para>
|
|
<programlisting>
|
|
Product Security...
|
|
securityworkers: DEFAULT/MANDATORY
|
|
</programlisting>
|
|
</section>
|
|
<section>
|
|
<title>Product Isolation With Common Group</title>
|
|
<para>To permit users of product A to access the bugs for
|
|
product A, users of product B to access product B, and support
|
|
staff to access both, 3 groups are needed</para>
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Support: Contains members of the support staff.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>AccessA: Contains users of product A and the Support group.</para>
|
|
</listitem>
|
|
<listitem>
|
|
<para>AccessB: Contains users of product B and the Support group.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
<para>Once these 3 groups are defined, the products group controls
|
|
can be set to..</para>
|
|
<programlisting>
|
|
Product A...
|
|
AccessA: ENTRY, MANDATORY/MANDATORY
|
|
Product B...
|
|
AccessB: ENTRY, MANDATORY/MANDATORY
|
|
</programlisting>
|
|
<para>Optionally, the support group could be permitted to make
|
|
bugs inaccessible to the users and could be permitted to publish
|
|
bugs relevant to all users in a common product that is read-only
|
|
to anyone outside the support group. That configuration could
|
|
be...</para>
|
|
<programlisting>
|
|
Product A...
|
|
AccessA: ENTRY, MANDATORY/MANDATORY
|
|
Support: SHOWN/NA
|
|
Product B...
|
|
AccessB: ENTRY, MANDATORY/MANDATORY
|
|
Support: SHOWN/NA
|
|
Product Common...
|
|
Support: ENTRY, DEFAULT/MANDATORY, CANEDIT
|
|
</programlisting>
|
|
</section>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="upgrading">
|
|
<title>Upgrading to New Releases</title>
|
|
|
|
<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 local changes (if any) have been made
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
|
|
<section id="upgrading-version-defns">
|
|
<title>Version Definitions</title>
|
|
|
|
<para>
|
|
Bugzilla displays the version you are using at the top of most
|
|
pages you load. It will look something like '2.16.7' or '2.18rc3'
|
|
or '2.19.1+'. The first number in this series is the Major Version.
|
|
This does not change very often (that is to say, almost never);
|
|
Bugzilla was 1.x.x when it was first created, and went to 2.x.x
|
|
when it was re-written in perl in Sept 1998. If/When the major version
|
|
is changed to 3.x.x, it will signify a significant structural change
|
|
and will be accompanied by much fanfare and many instructions on
|
|
how to upgrade, including a revision to this page. :)
|
|
</para>
|
|
|
|
<para>
|
|
The second number in the version is called the 'minor number', and
|
|
a release that changes the minor number is called a 'point release'.
|
|
An even number in this position (2.14, 2.16, 2.18, 2.20, etc.)
|
|
represents a stable version, while an odd number (2.17, 2.19, etc.)
|
|
represents a development version. In the past, stable point releases
|
|
were feature-based, coming when certain enhancements had been
|
|
completed, or the Bugzilla development team felt that enough
|
|
progress had been made overall. As of version 2.18, however,
|
|
Bugzilla has moved to a time-based release schedule; current plans
|
|
are to create a stable point release every 6 months or so after
|
|
2.18 is deployed.
|
|
</para>
|
|
|
|
<para>
|
|
The third number in the Bugzilla version represents a bugfix version.
|
|
Bugfix Revisions are normally released only to address security
|
|
vulnerabilities; in the future, it is likely that the Bugzilla
|
|
development team will back-port bugfixes in a new point release to
|
|
the old point release for a limited period. Once enough of these
|
|
bugfixes have accumulated (or a new security vulnerability is
|
|
identified and closed), a bugfix release will be made. As an
|
|
example, 2.16.6 was a bugfix release, and improved on 2.16.5.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
When reading version numbers, everything separated by a point ('.')
|
|
should be read as a single number. It is <emphasis>not</emphasis>
|
|
the same as decimal. 2.14 is newer than 2.8 because minor version
|
|
14 is greater than minor version 8. 2.24.11 would be newer than
|
|
2.24.9 (because bugfix 11 is greater than bugfix 9. This is
|
|
confusing to some people who aren't used to dealing with software.
|
|
</para>
|
|
</note>
|
|
</section>
|
|
|
|
<section id="upgrading-methods">
|
|
<title>Upgrading - Methods and Procedure</title>
|
|
<para>
|
|
There are three different ways 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>
|
|
Each of these options has its own pros and cons; the one that's
|
|
right for you depends on how long it has been since you last
|
|
installed, the degree to which you have customized your installation,
|
|
and/or your network configuration. (Some discussion of the various
|
|
methods of updating compared with degree and methods of local
|
|
customization can be found in <xref linkend="template-method"/>.)
|
|
</para>
|
|
|
|
<para>
|
|
The larger the jump you are trying to make, the more difficult it
|
|
is going to be to upgrade if you have made local customizations.
|
|
Upgrading from 2.18 to 2.18.1 should be fairly painless even if
|
|
you are heavily customized, but going from 2.14 to 2.18 is going
|
|
to mean a fair bit of work re-writing your local changes to use
|
|
the new files, logic, templates, etc. If you have done no local
|
|
changes at all, however, then upgrading should be approximately
|
|
the same amount of work regardless of how long it has been since
|
|
your version was released.
|
|
</para>
|
|
|
|
<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>
|
|
The examples in the following sections are written as though the
|
|
user were updating to version 2.18.1, but the procedures are the
|
|
same regardless of whether one is updating to a new point release
|
|
or simply trying to obtain a new bugfix release. Also, in the
|
|
examples the user's Bugzilla installation is found at
|
|
<filename>/var/www/html/bugzilla</filename>. If that is not the
|
|
same as the location of your Bugzilla installation, simply
|
|
substitute the proper paths where appropriate.
|
|
</para>
|
|
|
|
<section id="upgrade-cvs">
|
|
<title>Upgrading using CVS</title>
|
|
|
|
<para>
|
|
Every release of Bugzilla, whether it is a point release or a bugfix,
|
|
is tagged in CVS. Also, every tarball that has been distributed since
|
|
version 2.12 has been created in such a way that it can be used with
|
|
CVS once it is unpacked. Doing so, however, requires that you are able
|
|
to access cvs-mirror.mozilla.org on port 2401, which may not be an
|
|
option or a possibility for some users, especially those behind a
|
|
highly restrictive firewall.
|
|
</para>
|
|
|
|
<tip>
|
|
<para>
|
|
If you can, updating using CVS is probably the most painless
|
|
method, especially if you have a lot of local changes.
|
|
</para>
|
|
</tip>
|
|
|
|
<para>
|
|
The following shows the sequence of commands needed to update a
|
|
Bugzilla installation via CVS, and a typical series of results.
|
|
</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: <emphasis>('anonymous', or just leave it blank)</emphasis>
|
|
bash$ <command>cvs -q update -r BUGZILLA-2_18_1 -dP</command>
|
|
P checksetup.pl
|
|
P collectstats.pl
|
|
P globals.pl
|
|
P docs/rel_notes.txt
|
|
P template/en/default/list/quips.html.tmpl
|
|
<emphasis>(etc.)</emphasis>
|
|
</programlisting>
|
|
|
|
<caution>
|
|
<para>
|
|
If a line in the output from <command>cvs update</command> begins
|
|
with a <computeroutput>C</computeroutput>, then 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>
|
|
</section>
|
|
|
|
<section 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 obtain the latest tarball from the <ulink
|
|
url="http://www.bugzilla.org/download/">Download Page</ulink> and
|
|
create a new Bugzilla installation from that.
|
|
</para>
|
|
|
|
<para>
|
|
This sequence of commands shows how to get the tarball from the
|
|
command-line; it is also possible to download it from the site
|
|
directly in a web browser. If you go that route, save the file
|
|
to the <filename class="directory">/var/www/html</filename>
|
|
directory (or its equivalent, if you use something else) and
|
|
omit the first three lines of the example.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html</command>
|
|
bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.1.tar.gz</command>
|
|
<emphasis>(Output omitted)</emphasis>
|
|
bash$ <command>tar xzvf bugzilla-2.18.1.tar.gz</command>
|
|
bugzilla-2.18.1/
|
|
bugzilla-2.18.1/.cvsignore
|
|
bugzilla-2.18.1/1x1.gif
|
|
<emphasis>(Output truncated)</emphasis>
|
|
bash$ <command>cd bugzilla-2.18.1</command>
|
|
bash$ <command>cp ../bugzilla/localconfig* .</command>
|
|
bash$ <command>cp -r ../bugzilla/data .</command>
|
|
bash$ <command>cd ..</command>
|
|
bash$ <command>mv bugzilla bugzilla.old</command>
|
|
bash$ <command>mv bugzilla-2.18.1 bugzilla</command>
|
|
</programlisting>
|
|
|
|
<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.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
This upgrade method will give you a clean install of Bugzilla with the
|
|
same version as the tarball. That's fine if you don't have any local
|
|
customizations that you want to maintain, but if you do then you will
|
|
need to reapply them by hand to the appropriate files.
|
|
</para>
|
|
|
|
<para>
|
|
It's worth noting that since 2.12, the Bugzilla tarballs come
|
|
CVS-ready, so if you decide at a later date that you'd rather use
|
|
CVS as an upgrade method, your code will already be set up for it.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="upgrade-patches">
|
|
<title>Upgrading using patches</title>
|
|
|
|
<para>
|
|
If you are doing a bugfix upgrade -- that is, one where only the
|
|
last number of the revision changes, such as from 2.16.6 to 2.16.7
|
|
-- then you have the option of obtaining and applying a patch file
|
|
from the <ulink
|
|
url="http://www.bugzilla.org/download/">Download Page</ulink>.
|
|
This file is made available by the <ulink
|
|
url="http://www.bugzilla.org/developers/profiles.html">Bugzilla
|
|
Development Team</ulink>, and is a collection of all the bug fixes
|
|
and security patches that have been made since the last bugfix
|
|
release. If you are planning to upgrade via patches, it is safer
|
|
to grab this developer-made patch file than to read the patch
|
|
notes and apply all (or even just some of) the patches oneself,
|
|
as sometimes patches on bugs get changed before they get checked in.
|
|
</para>
|
|
|
|
<para>
|
|
As above, this example starts with obtaining the file via the
|
|
command line. If you have already downloaded it, you can omit the
|
|
first two commands.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd /var/www/html/bugzilla</command>
|
|
bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.0-to-2.18.1.diff.gz</command>
|
|
<emphasis>(Output omitted)</emphasis>
|
|
bash$ <command>gunzip bugzilla-2.18.0-to-2.18.1.diff.gz</command>
|
|
bash$ <command>patch -p1 < bugzilla-2.18.0-to-2.18.1.diff</command>
|
|
patching file checksetup.pl
|
|
patching file collectstats.pl
|
|
patching file globals.pl
|
|
<emphasis>(etc.)</emphasis>
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>
|
|
Be aware that upgrading from a patch file does not change the
|
|
entries in your <filename class="directory">CVS</filename> directory.
|
|
This could make it more difficult to upgrade using CVS
|
|
(<xref linkend="upgrade-cvs"/>) in the future.
|
|
</para>
|
|
</warning>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id="upgrading-completion">
|
|
<title>Completing Your Upgrade</title>
|
|
|
|
<para>
|
|
Regardless of which upgrade method you choose, you will need to
|
|
run <command>./checksetup.pl</command> before your Bugzilla
|
|
upgrade will be complete.
|
|
</para>
|
|
|
|
<programlisting>
|
|
bash$ <command>cd bugzilla</command>
|
|
bash$ <command>./checksetup.pl</command>
|
|
</programlisting>
|
|
|
|
<warning>
|
|
<para>
|
|
The period at the beginning of the command
|
|
<command>./checksetup.pl</command> is important and can not
|
|
be omitted.
|
|
</para>
|
|
</warning>
|
|
|
|
<para>
|
|
If you have done a lot of local modifications, it wouldn't hurt
|
|
to run the Bugzilla Testing suite. This is not a required step,
|
|
but it isn't going to hurt anything, and might help point out
|
|
some areas that could be improved. (More information on the
|
|
test suite can be had by following this link to the appropriate
|
|
section in the <ulink
|
|
url="http://www.bugzilla.org/docs/developer.html#testsuite">Developers'
|
|
Guide</ulink>.)
|
|
</para>
|
|
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
|
|
<!-- Keep this comment at the end of the file
|
|
Local variables:
|
|
mode: sgml
|
|
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-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:
|
|
-->
|
|
|