2214 lines
86 KiB
XML
2214 lines
86 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>
|
|
mail_delivery_method
|
|
</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 you to define specific users who 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, edit the tweakparams, editusers,
|
|
creategroups, editcomponents, and editkeywords groups to add the
|
|
entire admin group to those groups (which is the case by default).
|
|
</para>
|
|
</tip>
|
|
</section>
|
|
|
|
<section id="manageusers">
|
|
<title>Managing Other Users</title>
|
|
|
|
<section id="user-account-search">
|
|
<title>Searching for existing users</title>
|
|
|
|
<para>
|
|
If you have <quote>editusers</quote> privileges or if you are allowed
|
|
to grant privileges for some groups, the <quote>Users</quote> link
|
|
appears in the footer.
|
|
</para>
|
|
|
|
<para>
|
|
The first screen you get is a search form to search for existing user
|
|
accounts. You can run searches based either on the ID, real name or
|
|
login name (i.e. the email address in most cases) of users. 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, a <emphasis>reverse</emphasis> regular expression
|
|
match, which finds every user name which does NOT match the regular
|
|
expression, or the exact string if you know exactly who you are looking for.
|
|
</para>
|
|
|
|
<para>
|
|
You can also restrict your search to users being in some specific group.
|
|
By default, the restriction is turned off. Then you get a list of
|
|
users matching your criteria, and clicking their login name lets you
|
|
edit their properties.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="createnewusers">
|
|
<title>Creating new users</title>
|
|
|
|
<section id="self-registration">
|
|
<title>Self-registration</title>
|
|
|
|
<para>
|
|
By default, users can create their own user accounts by clicking the
|
|
<quote>New Account</quote> link at the bottom of each page (assuming
|
|
they aren't logged in as someone else already). If you want to disable
|
|
this self-registration, or if you want to restrict who can create his
|
|
own user account, you have to edit the <quote>createemailregexp</quote>
|
|
parameter in the <quote>Configuration</quote> page, see
|
|
<xref linkend="parameters" />.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="user-account-creation">
|
|
<title>Accounts created by an administrator</title>
|
|
|
|
<para>
|
|
Users with <quote>editusers</quote> privileges, such as administrators,
|
|
can create user accounts for other users:
|
|
</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>
|
|
|
|
<section id="modifyusers">
|
|
<title>Modifying Users</title>
|
|
|
|
<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 <quote>emailsuffix</quote> parameter, 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>Bugmail Disabled</emphasis>:
|
|
Mark this checkbox to disable bugmail and whinemail completely
|
|
for this account. This checkbox replaces the data/nomail file
|
|
which existed in older versions of Bugzilla.
|
|
</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, simply check the
|
|
<quote>Bugmail Disabled</quote> checkbox above.
|
|
</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. If you turn on the
|
|
<quote>makeproductgroups</quote> parameter in
|
|
the Group Security Panel in the Parameters page,
|
|
then Bugzilla creates one group per product (at the time you create
|
|
the product), and this group has exactly the same name as the
|
|
product itself. Note that for products that already exist when
|
|
the parameter is turned on, the corresponding group will not be
|
|
created. The user must still have the <quote>editbugs</quote>
|
|
privilege to edit bugs in these products.</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
|
|
<section id="user-account-deletion">
|
|
<title>Deleting Users</title>
|
|
<para>
|
|
If the <quote>allowuserdeletion</quote> parameter is turned on, see
|
|
<xref linkend="parameters" />, then you can also delete user accounts.
|
|
Note that this is most of the time not the best thing to do. If only
|
|
a warning in a yellow box is displayed, then the deletion is safe.
|
|
If a warning is also displayed in a red box, then you should NOT try
|
|
to delete the user account, else you will get referential integrity
|
|
problems in your database, which can lead to unexpected behavior,
|
|
such as bugs not appearing in bug lists anymore, or data displaying
|
|
incorrectly. You have been warned!
|
|
</para>
|
|
</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
|
|
<quote>Common</quote> 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 <quote>votes</quote> 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 <quote>Adminstration</quote> from the footer and then
|
|
choose <quote>Products</quote> from the main administration page.
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Select the <quote>Add</quote> 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>
|
|
|
|
|
|
<section>
|
|
<title>Assigning Group Controls to Products</title>
|
|
<para>
|
|
On the <quote>Product Edit</quote> page,
|
|
there is a link called
|
|
<quote>Edit Group Access Controls</quote>.
|
|
The settings on this page control the relationship
|
|
of the groups to the product being edited.
|
|
</para>
|
|
<para>
|
|
Groups may be applicable, default, and
|
|
mandatory for each product. Groups can also control access
|
|
to bugs for a given product, or be used to make bugs
|
|
for a product totally read-only unless the group
|
|
restrictions are met.
|
|
</para>
|
|
<para>
|
|
If any group has <emphasis>Entry</emphasis> selected, then the
|
|
product will restrict bug entry to only those users
|
|
who are members of all the groups with
|
|
<emphasis>Entry</emphasis> selected.
|
|
</para>
|
|
<para>
|
|
If any group has <emphasis>Canedit</emphasis> selected,
|
|
then the product will be read-only for any users
|
|
who are not members of all of the groups with
|
|
<emphasis>Canedit</emphasis> selected. ONLY users who
|
|
are members of all the <emphasis>Canedit</emphasis> groups
|
|
will be able to edit. This is an
|
|
additional restriction that further limits
|
|
what can be edited by a user.
|
|
</para>
|
|
<para>
|
|
The following settings let you
|
|
choose privileges on a <emphasis>per-product basis</emphasis>.
|
|
This is a convenient way to give privileges to
|
|
some users for some products only, without having
|
|
to give them global privileges which would affect
|
|
all products.
|
|
</para>
|
|
<para>
|
|
Any group having <emphasis>editcomponents</emphasis>
|
|
selected allows users who are in this group to edit all
|
|
aspects of this product, including components, milestones
|
|
and versions.
|
|
</para>
|
|
<para>
|
|
Any group having <emphasis>canconfirm</emphasis> selected
|
|
allows users who are in this group to confirm bugs
|
|
in this product.
|
|
</para>
|
|
<para>
|
|
Any group having <emphasis>editbugs</emphasis> selected allows
|
|
users who are in this group to edit all fields of
|
|
bugs in this product.
|
|
</para>
|
|
<para>
|
|
The <emphasis>MemberControl</emphasis> and
|
|
<emphasis>OtherControl</emphasis> fields indicate which
|
|
bugs will be placed in this group according
|
|
to the following definitions.
|
|
</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>
|
|
|
|
<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 <quote>Edit components</quote> link
|
|
from the <quote>Edit product</quote> page</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Select the <quote>Add</quote> link in the bottom right.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Fill out the <quote>Component</quote> field, a
|
|
short <quote>Description</quote>, the
|
|
<quote>Default Assignee</quote>, <quote>Default CC List</quote>
|
|
and <quote>Default QA Contact</quote> (if enabled).
|
|
The <quote>Component Description</quote> field may contain a
|
|
limited subset of HTML tags. The <quote>Default Assignee</quote>
|
|
field must be a login name already existing in the Bugzilla 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 can
|
|
edit Flag Types from the main administration page. Clicking the
|
|
<quote>Flags</quote> 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-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 as described below (<xref linkend="flags-create"/>).
|
|
</para>
|
|
</section>
|
|
|
|
<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> <!-- flags-admin -->
|
|
|
|
<!-- XXX We should add a "Uses of Flags" section, here, with examples. -->
|
|
|
|
</section> <!-- flags -->
|
|
|
|
<section id="custom-fields">
|
|
<title>Custom Fields</title>
|
|
|
|
<para>
|
|
One of the most requested features was the ability to add your own custom
|
|
fields to bugs, based on your needs. With the release of Bugzilla 3.0, this
|
|
dream finally comes true. Administrators can manage these fields using the
|
|
<quote>Custom Fields</quote> link in the footer of pages. The first thing
|
|
they will see is the list of existing custom fields (which is empty by default).
|
|
</para>
|
|
|
|
<section id="add-custom-fields">
|
|
<title>Adding Custom Fields</title>
|
|
|
|
<para>
|
|
The <quote>Add a new custom field</quote> link permits you to add a
|
|
new field which can be either a free text box or a drop down menu.
|
|
More field types will be available in future releases.
|
|
</para>
|
|
|
|
<para>
|
|
The following attributes must be set for each new custom field:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Name:</emphasis>
|
|
the name of the field, used internally. This name MUST begin
|
|
with <quote>cf_</quote>. If you omit this string, it will
|
|
be automatically added to the name you entered. This way, all
|
|
custom fields added to Bugzilla begin with <quote>cf_</quote>,
|
|
avoiding any conflict with default fields.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Description:</emphasis>
|
|
the string which is used as a label for this custom field.
|
|
That is the string that users will see, and so should be
|
|
short and explicit.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Type:</emphasis>
|
|
as mentioned above, only two types are implemented so far.
|
|
Free text boxes let you type any string, while drop down menus
|
|
only let you choose one value in the list provided. The list of
|
|
legal values for this field can be created and edited as soon as
|
|
this custom field is added to the DB. See
|
|
<xref linkend="edit-values-list" /> for information about editing
|
|
legal values.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Sortkey:</emphasis>
|
|
this integer determines in which order custom fields are
|
|
displayed in the UI, especially when viewing a bug. Fields
|
|
with lower values are displayed first.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Can be set on bug creation:</emphasis>
|
|
this boolean determines whether this field can be set on
|
|
bug creation or not. If not, then you have to create the
|
|
bug first before being able to set this field. Else you
|
|
can set its value at the same time you file a bug,
|
|
see <xref linkend="bugreports" /> about filing bugs.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Displayed in bugmail for new bugs:</emphasis>
|
|
this boolean determines whether the value set on this field
|
|
should appear in bugmail when the bug is filed. This attribute
|
|
has no effect if the field cannot be set on bug creation.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Is obsolete:</emphasis>
|
|
this boolean determines whether or not this field should
|
|
be displayed at all. Obsolete custom fields are hidden.
|
|
</para>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</para>
|
|
</section>
|
|
|
|
<section id="edit-custom-fields">
|
|
<title>Editing Custom Fields</title>
|
|
|
|
<para>
|
|
As soon as a custom field is created, its name and type cannot be
|
|
changed. If this field is a drop down menu, its legal values can
|
|
be set as described in <xref linkend="edit-values-list" />. All
|
|
other attributes can be edited as described above.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="delete-custom-fields">
|
|
<title>Deleting Custom Fields</title>
|
|
|
|
<para>
|
|
At this point, it is not possible to delete custom fields from
|
|
your web browser. If you don't want to make one available anymore,
|
|
mark it as obsolete. This way, you will preserve your DB
|
|
referential integrity.
|
|
</para>
|
|
</section>
|
|
</section>
|
|
|
|
<section id="edit-values">
|
|
<title>Legal Values</title>
|
|
|
|
<para>
|
|
Since Bugzilla 2.20 RC1, legal values for Operating Systems, platforms,
|
|
bug priorities and severities can be edited from the User Interface
|
|
directly. This means that it is no longer required to manually edit
|
|
<filename>localconfig</filename>. Starting with Bugzilla 2.23.3, you
|
|
can also customize the list of valid resolutions from the same interface.
|
|
</para>
|
|
|
|
<section id="edit-values-list">
|
|
<title>Viewing/Editing legal values</title>
|
|
<para>
|
|
Editing legal values requires <quote>admin</quote> privileges.
|
|
A link named <quote>Field Values</quote> is visible in your footer and
|
|
clicking on it displays the list of fields whose values can be edited.
|
|
</para>
|
|
<para>
|
|
You can add as many legal values as you want, and each value must be
|
|
unique (on a per field basis). The sortkey is important to display these
|
|
values in the desired order.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="edit-values-delete">
|
|
<title>Deleting legal values</title>
|
|
<para>
|
|
You can also delete legal values, but only if the two following conditions
|
|
are respected:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>The value is not used by default for the field.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>No bug is currently using this value.</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
<para>
|
|
If any of these conditions is not respected, the value cannot be deleted.
|
|
The only way to delete these values is to reassign bugs to another value
|
|
and to set another value as default for the field.
|
|
</para>
|
|
</section>
|
|
</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="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 id="create-groups">
|
|
<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 id="edit-groups">
|
|
<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>
|
|
For information on assigning group controls to
|
|
products, see <xref linkend="products" />.
|
|
</para>
|
|
</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 the home
|
|
page <filename>index.cgi</filename>. It looks something like
|
|
'2.20.3', '2.22.1' or '3.0rc1'. The first number in this series is
|
|
the Major Version. This does not change very often;
|
|
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. The major version
|
|
3.x.x, released in early 2007, is pretty far from what the 2.x.x
|
|
series looked like, both about its UI and its code.
|
|
</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.18, 2.20, 2.22, 3.0, 3.2, etc.)
|
|
represents a stable version, while an odd number (2.19, 2.21, 2.23, 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 released only to address security vulnerabilities
|
|
and, for a limited period, bug fixes. Once enough of these
|
|
bugfixes have accumulated (or a new security vulnerability is
|
|
identified and closed), a bugfix release is made. As an
|
|
example, 2.20.3 was a bugfix release, and improved on 2.20.2.
|
|
</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.22 is newer than 2.8 because minor version
|
|
22 is greater than minor version 8. The now unsupported release 2.16.11
|
|
was newer than 2.16.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-notifications">
|
|
<title>Upgrading - Notifications</title>
|
|
|
|
<para>
|
|
Bugzilla 3.0 introduces the ability to automatically notify
|
|
administrators when new releases are available, based on the
|
|
<literal>upgrade_notification</literal> parameter, see
|
|
<xref linkend="parameters"/>. Administrators will see these
|
|
notifications when they access the <filename>index.cgi</filename>
|
|
page, i.e. generally when logging in. Bugzilla will check once per
|
|
day for new releases, unless the parameter is set to
|
|
<quote>disabled</quote>. If you are behind a proxy, you may have to set
|
|
the <literal>proxy_url</literal> parameter accordingly. If the proxy
|
|
requires authentication, use the
|
|
<literal>http://user:pass@proxy_url/</literal> syntax.
|
|
</para>
|
|
</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.22 to 2.22.1 should be fairly painless even if
|
|
you are heavily customized, but going from 2.18 to 3.0 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.22.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_22_1 -dP</command>
|
|
P checksetup.pl
|
|
P collectstats.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 http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz</command>
|
|
<emphasis>(Output omitted)</emphasis>
|
|
bash$ <command>tar xzvf bugzilla-2.22.1.tar.gz</command>
|
|
bugzilla-2.22.1/
|
|
bugzilla-2.22.1/.cvsignore
|
|
<emphasis>(Output truncated)</emphasis>
|
|
bash$ <command>cd bugzilla-2.22.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.22.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.22 to 2.22.1
|
|
-- 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 http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz</command>
|
|
<emphasis>(Output omitted)</emphasis>
|
|
bash$ <command>gunzip bugzilla-2.22-to-2.22.1.diff.gz</command>
|
|
bash$ <command>patch -p1 < bugzilla-2.22-to-2.22.1.diff</command>
|
|
patching file checksetup.pl
|
|
patching file collectstats.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:
|
|
-->
|
|
|