3046 lines
118 KiB
XML
3046 lines
118 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 "Parameters" link in the Administration page (the
|
|
Administration page can be found by clicking the "Administration"
|
|
link in the footer). The parameters are divided into several categories,
|
|
accessed via the menu on the left. Following is a description of the
|
|
different categories and important parameters within those categories.
|
|
</para>
|
|
|
|
<section id="param-requiredsettings">
|
|
<title>Required Settings</title>
|
|
|
|
<para>
|
|
The core required parameters for any Bugzilla installation are set
|
|
here. These parameters must be set before a new Bugzilla installation
|
|
can be used. Administrators should review this list before
|
|
deploying a new Bugzilla installation.
|
|
</para>
|
|
|
|
<indexterm>
|
|
<primary>checklist</primary>
|
|
</indexterm>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
maintainer
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
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>
|
|
Defines the fully qualified domain name and web
|
|
server path to this Bugzilla installation.
|
|
</para>
|
|
<para>
|
|
For example, if the Bugzilla query page is
|
|
<filename>http://www.foo.com/bugzilla/query.cgi</filename>,
|
|
the <quote>urlbase</quote> should be set
|
|
to <filename>http://www.foo.com/bugzilla/</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
docs_urlbase
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Defines path to the Bugzilla documentation. This can be a fully
|
|
qualified domain name, or a path relative to "urlbase".
|
|
</para>
|
|
<para>
|
|
For example, if the "Bugzilla Configuration" page
|
|
of the documentation is
|
|
<filename>http://www.foo.com/bugzilla/docs/html/parameters.html</filename>,
|
|
set the <quote>docs_urlbase</quote>
|
|
to <filename>http://www.foo.com/bugzilla/docs/html/</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
sslbase
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Defines the fully qualified domain name and web
|
|
server path for HTTPS (SSL) connections to this Bugzilla installation.
|
|
</para>
|
|
<para>
|
|
For example, if the Bugzilla main page is
|
|
<filename>https://www.foo.com/bugzilla/index.cgi</filename>,
|
|
the <quote>sslbase</quote> should be set
|
|
to <filename>https://www.foo.com/bugzilla/</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
ssl_redirect
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If enabled, Bugzilla will force HTTPS (SSL) connections, by
|
|
automatically redirecting any users who try to use a non-SSL
|
|
connection.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
cookiedomain
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Defines the domain for Bugzilla cookies. This is typically left blank.
|
|
If there are multiple hostnames that point to the same webserver, which
|
|
require the same cookie, then this parameter can be utilized. For
|
|
example, If your website is at
|
|
<filename>https://www.foo.com/</filename>, setting this to
|
|
<filename>.foo.com/</filename> will also allow
|
|
<filename>bar.foo.com/</filename> to access Bugzilla cookies.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
cookiepath
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Defines a path, relative to the web server root, that Bugzilla
|
|
cookies will be restricted to. For example, if the
|
|
<command>urlbase</command> is set to
|
|
<filename>http://www.foo.com/bugzilla/</filename>, the
|
|
<command>cookiepath</command> should be set to
|
|
<filename>/bugzilla/</filename>. Setting it to "/" will allow all sites
|
|
served by this web server or virtual host to read Bugzilla cookies.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
utf8
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Determines whether to use UTF-8 (Unicode) encoding for all text in
|
|
Bugzilla. New installations should set this to true to avoid character
|
|
encoding problems. Existing databases should set this to true only
|
|
after the data has been converted from existing legacy character
|
|
encoding to UTF-8, using the
|
|
<filename>contrib/recode.pl</filename> script.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If you turn this parameter from "off" to "on", you must re-run
|
|
<filename>checksetup.pl</filename> immediately afterward.
|
|
</para>
|
|
</note>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
shutdownhtml
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If there is any text in this field, this Bugzilla installation will
|
|
be completely disabled and this text will appear instead of all
|
|
Bugzilla pages for all users, including Admins. Used in the event
|
|
of site maintenance or outage situations.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Although regular log-in capability is disabled while
|
|
<command>shutdownhtml</command>
|
|
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>
|
|
announcehtml
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Any text in this field will be displayed at the top of every HTML
|
|
page in this Bugzilla installation. The text is not wrapped in any
|
|
tags. For best results, wrap the text in a <quote><div></quote>
|
|
tag. Any style attributes from the CSS can be applied. For example,
|
|
to make the text green inside of a red box, add <quote>id=message</quote>
|
|
to the <quote><div></quote> tag.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
proxy_url
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If this Bugzilla installation is behind a proxy, enter the proxy
|
|
information here to enable Bugzilla to access the Internet. Bugzilla
|
|
requires Internet access to utilize the
|
|
<command>upgrade_notification</command> parameter (below). If the
|
|
proxy requires authentication, use the syntax:
|
|
<filename>http://user:pass@proxy_url/</filename>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
upgrade_notification
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Enable or disable a notification on the homepage of this Bugzilla
|
|
installation when a newer version of Bugzilla is available. This
|
|
notification is only visible to administrators. Choose "disabled",
|
|
to turn off the notification. Otherwise, choose which version of
|
|
Bugzilla you want to be notified about: "development_snapshot" is the
|
|
latest release on the trunk; "latest_stable_release" is the most
|
|
recent release available on the most recent stable branch;
|
|
"stable_branch_release" the most recent release on the branch
|
|
this installation is based on.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="param-admin-policies">
|
|
<title>Administrative Policies</title>
|
|
<para>
|
|
This page contains parameters for basic administrative functions.
|
|
Options include whether to allow the deletion of bugs and users,
|
|
and whether to allow users to change their email address.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="param-user-authentication">
|
|
<title>User Authentication</title>
|
|
<para>
|
|
This page contains the settings that control how this Bugzilla
|
|
installation will do its authentication. Choose what authentication
|
|
mechanism to use (the Bugzilla database, or an external source such
|
|
as LDAP), and set basic behavioral parameters. For example, choose
|
|
whether to require users to login to browse bugs, the management
|
|
of authentication cookies, and the regular expression used to
|
|
validate email addresses. Some parameters are highlighted below.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
emailregexp
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Defines the regular expression used to validate email addresses
|
|
used for login names. The default attempts to match fully
|
|
qualified email addresses (i.e. 'user@example.com'). Some
|
|
Bugzilla installations allow only local user names (i.e 'user'
|
|
instead of 'user@example.com'). In that case, the
|
|
<command>emailsuffix</command> parameter should be used to define
|
|
the email domain.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
emailsuffix
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This string is appended to login names when actually sending
|
|
email to a user. For example,
|
|
If <command>emailregexp</command> has been set to allow
|
|
local usernames,
|
|
then this parameter would contain the email domain for all users
|
|
(i.e. '@example.com').
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="param-attachments">
|
|
<title>Attachments</title>
|
|
<para>
|
|
This page allows for setting restrictions and other parameters
|
|
regarding attachments to bugs. For example, control size limitations
|
|
and whether to allow pointing to external files via a URI.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="param-bug-change-policies">
|
|
<title>Bug Change Policies</title>
|
|
<para>
|
|
Set policy on default behavior for bug change events. For example,
|
|
choose which status to set a bug to when it is marked as a duplicate,
|
|
and choose whether to allow bug reporters to set the priority or
|
|
target milestone. Also allows for configuration of what changes
|
|
should require the user to make a comment, described below.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<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>
|
|
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>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="param-bugfields">
|
|
<title>Bug Fields</title>
|
|
<para>
|
|
The parameters in this section determine the default settings of
|
|
several Bugzilla fields for new bugs, and also control whether
|
|
certain fields are used. For example, choose whether to use the
|
|
"target milestone" field or the "status whiteboard" field.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<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>
|
|
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>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="param-bugmoving">
|
|
<title>Bug Moving</title>
|
|
<para>
|
|
This page controls whether this Bugzilla installation allows certain
|
|
users to move bugs to an external database. If bug moving is enabled,
|
|
there are a number of parameters that control bug moving behaviors.
|
|
For example, choose which users are allowed to move bugs, the location
|
|
of the external database, and the default product and component that
|
|
bugs moved <emphasis>from</emphasis> other bug databases to this
|
|
Bugzilla installation are assigned to.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="param-dependency-graphs">
|
|
<title>Dependency Graphs</title>
|
|
<para>
|
|
This page has one parameter that sets the location of a Web Dot
|
|
server, or of the Web Dot binary on the local system, that is used
|
|
to generate dependency graphs. Web Dot is a CGI program that creates
|
|
images from <filename>.dot</filename> graphic description files. If
|
|
no Web Dot server or binary is specified, then dependency graphs will
|
|
be disabled.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="param-group-security">
|
|
<title>Group Security</title>
|
|
<para>
|
|
Bugzilla allows for the creation of different groups, with the
|
|
ability to restrict the visibility of bugs in a group to a set of
|
|
specific users. Specific products can also be associated with
|
|
groups, and users restricted to only see products in their groups.
|
|
Several parameters are described in more detail below. Most of the
|
|
configuration of groups and their relationship to products is done
|
|
on the "Groups" and "Product" pages of the "Administration" area.
|
|
The options on this page control global default behavior.
|
|
For more information on Groups and Group Security, see
|
|
<xref linkend="groups"/>
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
makeproductgroups
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Determines whether or not to automatically create groups
|
|
when new products are created. If this is on, the groups will be
|
|
used for querying bugs.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
usevisibilitygroups
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
If selected, user visibility will be restricted to members of
|
|
groups, as selected in the group configuration settings.
|
|
Each user-defined group can be allowed to see members of selected
|
|
other groups.
|
|
For details on configuring groups (including the visibility
|
|
restrictions) see <xref linkend="edit-groups"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
querysharegroup
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The name of the group of users who are allowed to share saved
|
|
searches with one another. For more information on using
|
|
saved searches, see <xref linkend="savedsearches"/>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="bzldap">
|
|
<title>LDAP Authentication</title>
|
|
|
|
<para>LDAP authentication is a module for Bugzilla's plugin
|
|
authentication architecture. This page contains all the parameters
|
|
necessary to configure Bugzilla for use with LDAP authentication.
|
|
</para>
|
|
|
|
<para>
|
|
The existing authentication
|
|
scheme for Bugzilla uses email addresses as the primary user ID, and a
|
|
password to authenticate that user. All places within Bugzilla that
|
|
require a user ID (e.g assigning a bug) use the email
|
|
address. The LDAP authentication builds on top of this scheme, rather
|
|
than replacing it. The initial log-in is done with a username and
|
|
password for the LDAP directory. Bugzilla tries to bind to LDAP using
|
|
those credentials and, if successful, tries to map this account to a
|
|
Bugzilla account. If an LDAP mail attribute is defined, the value of this
|
|
attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP
|
|
username to form a full email address. If an account for this address
|
|
already exists in the Bugzilla installation, it will log in to that account.
|
|
If no account for that email address exists, one is created at the time
|
|
of login. (In this case, Bugzilla will attempt to use the "displayName"
|
|
or "cn" attribute to determine the user's full name.) After
|
|
authentication, all other user-related tasks are still handled by email
|
|
address, not LDAP username. For example, bugs are still assigned by
|
|
email address and users are still queried by email address.
|
|
</para>
|
|
|
|
<caution>
|
|
<para>Because the Bugzilla account is not created until the first time
|
|
a user logs in, a user who has not yet logged is unknown to Bugzilla.
|
|
This means they cannot be used as an assignee or QA contact (default or
|
|
otherwise), added to any CC list, or any other such operation. One
|
|
possible workaround is the <filename>bugzilla_ldapsync.rb</filename>
|
|
script in the
|
|
<glossterm linkend="gloss-contrib">
|
|
<filename class="directory">contrib</filename></glossterm>
|
|
directory. Another possible solution is fixing
|
|
<ulink url="https://bugzilla.mozilla.org/show_bug.cgi?id=201069">bug
|
|
201069</ulink>.
|
|
</para>
|
|
</caution>
|
|
|
|
<para>Parameters required to use LDAP Authentication:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="param-user_verify_class_for_ldap">
|
|
<term>user_verify_class</term>
|
|
<listitem>
|
|
<para>If you want to list <quote>LDAP</quote> here,
|
|
make sure to have set up the other parameters listed below.
|
|
Unless you have other (working) authentication methods listed as
|
|
well, you may otherwise not be able to log back in to Bugzilla once
|
|
you log out.
|
|
If this happens to you, you will need to manually edit
|
|
<filename>data/params</filename> and set user_verify_class to
|
|
<quote>DB</quote>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPserver">
|
|
<term>LDAPserver</term>
|
|
<listitem>
|
|
<para>This parameter should be set to the name (and optionally the
|
|
port) of your LDAP server. If no port is specified, it assumes
|
|
the default LDAP port of 389.
|
|
</para>
|
|
<para>For example: <quote>ldap.company.com</quote>
|
|
or <quote>ldap.company.com:3268</quote>
|
|
</para>
|
|
<para>You can also specify a LDAP URI, so as to use other
|
|
protocols, such as LDAPS or LDAPI. If port was not specified in
|
|
the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS'
|
|
schemes respectively.
|
|
</para>
|
|
<tip>
|
|
<para>
|
|
In order to use SSL with LDAP, specify a URI with "ldaps://".
|
|
This will force the use of SSL over port 636.
|
|
</para>
|
|
</tip>
|
|
<para>For example, normal LDAP:
|
|
<quote>ldap://ldap.company.com</quote>, LDAP over SSL:
|
|
<quote>ldaps://ldap.company.com</quote> or LDAP over a UNIX
|
|
domain socket <quote>ldapi://%2fvar%2flib%2fldap_sock</quote>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPbinddn">
|
|
<term>LDAPbinddn [Optional]</term>
|
|
<listitem>
|
|
<para>Some LDAP servers will not allow an anonymous bind to search
|
|
the directory. If this is the case with your configuration you
|
|
should set the LDAPbinddn parameter to the user account Bugzilla
|
|
should use instead of the anonymous bind.
|
|
</para>
|
|
<para>Ex. <quote>cn=default,cn=user:password</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPBaseDN">
|
|
<term>LDAPBaseDN</term>
|
|
<listitem>
|
|
<para>The LDAPBaseDN parameter should be set to the location in
|
|
your LDAP tree that you would like to search for email addresses.
|
|
Your uids should be unique under the DN specified here.
|
|
</para>
|
|
<para>Ex. <quote>ou=People,o=Company</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPuidattribute">
|
|
<term>LDAPuidattribute</term>
|
|
<listitem>
|
|
<para>The LDAPuidattribute parameter should be set to the attribute
|
|
which contains the unique UID of your users. The value retrieved
|
|
from this attribute will be used when attempting to bind as the
|
|
user to confirm their password.
|
|
</para>
|
|
<para>Ex. <quote>uid</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-LDAPmailattribute">
|
|
<term>LDAPmailattribute</term>
|
|
<listitem>
|
|
<para>The LDAPmailattribute parameter should be the name of the
|
|
attribute which contains the email address your users will enter
|
|
into the Bugzilla login boxes.
|
|
</para>
|
|
<para>Ex. <quote>mail</quote></para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="bzradius">
|
|
<title>RADIUS Authentication</title>
|
|
|
|
<para>
|
|
RADIUS authentication is a module for Bugzilla's plugin
|
|
authentication architecture. This page contains all the parameters
|
|
necessary for configuring Bugzilla to use RADIUS authentication.
|
|
</para>
|
|
<note>
|
|
<para>
|
|
Most caveats that apply to LDAP authentication apply to RADIUS
|
|
authentication as well. See <xref linkend="bzldap"/> for details.
|
|
</para>
|
|
</note>
|
|
|
|
<para>Parameters required to use RADIUS Authentication:</para>
|
|
|
|
<variablelist>
|
|
<varlistentry id="param-user_verify_class_for_radius">
|
|
<term>user_verify_class</term>
|
|
<listitem>
|
|
<para>If you want to list <quote>RADIUS</quote> here,
|
|
make sure to have set up the other parameters listed below.
|
|
Unless you have other (working) authentication methods listed as
|
|
well, you may otherwise not be able to log back in to Bugzilla once
|
|
you log out.
|
|
If this happens to you, you will need to manually edit
|
|
<filename>data/params</filename> and set user_verify_class to
|
|
<quote>DB</quote>.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-RADIUS_server">
|
|
<term>RADIUS_server</term>
|
|
<listitem>
|
|
<para>This parameter should be set to the name (and optionally the
|
|
port) of your RADIUS server.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-RADIUS_secret">
|
|
<term>RADIUS_secret</term>
|
|
<listitem>
|
|
<para>This parameter should be set to the RADIUS server's secret.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry id="param-RADIUS_email_suffix">
|
|
<term>RADIUS_email_suffix</term>
|
|
<listitem>
|
|
<para>Bugzilla needs an e-mail address for each user account.
|
|
Therefore, it needs to determine the e-mail address corresponding
|
|
to a RADIUS user.
|
|
Bugzilla offers only a simple way to do this: it can concatenate
|
|
a suffix to the RADIUS user name to convert it into an e-mail
|
|
address.
|
|
You can specify this suffix in the RADIUS_email_suffix parameter.
|
|
</para>
|
|
<para>If this simple solution does not work for you, you'll
|
|
probably need to modify
|
|
<filename>Bugzilla/Auth/Verify/RADIUS.pm</filename> to match your
|
|
requirements.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="param-email">
|
|
<title>Email</title>
|
|
<para>
|
|
This page contains all of the parameters for configuring how
|
|
Bugzilla deals with the email notifications it sends. See below
|
|
for a summary of important options.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<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.
|
|
"Test" 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>
|
|
mailfrom
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
This is the email address that will appear in the "From" field
|
|
of all emails sent by this Bugzilla installation. Some email
|
|
servers require mail to be from a valid email address, therefore
|
|
it is recommended to choose a valid email address here.
|
|
</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>
|
|
|
|
<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>
|
|
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>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="param-patchviewer">
|
|
<title>Patch Viewer</title>
|
|
<para>
|
|
This page contains configuration parameters for the CVS server,
|
|
Bonsai server and LXR server that Bugzilla will use to enable the
|
|
features of the Patch Viewer. Bonsai is a tool that enables queries
|
|
to a CVS tree. LXR is a tool that can cross reference and index source
|
|
code.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="param-querydefaults">
|
|
<title>Query Defaults</title>
|
|
<para>
|
|
This page controls the default behavior of Bugzilla in regards to
|
|
several aspects of querying bugs. Options include what the default
|
|
query options are, what the "My Bugs" page returns, whether users
|
|
can freely add bugs to the quip list, and how many duplicate bugs are
|
|
needed to add a bug to the "most frequently reported" list.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="param-shadowdatabase">
|
|
<title>Shadow Database</title>
|
|
<para>
|
|
This page controls whether a shadow database is used, and all the
|
|
parameters associated with the shadow database. Versions of Bugzilla
|
|
prior to 3.2 used the MyISAM table type, which supports
|
|
only table-level write locking. With MyISAM, any time someone is making a change to
|
|
a bug, the entire table is locked until the write operation is complete.
|
|
Locking for write also blocks reads until the write is complete.
|
|
</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.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
As of version 3.2, Bugzilla no longer uses the MyISAM table type.
|
|
Instead, InnoDB is used, which can do transaction-based locking.
|
|
Therefore, the limitations the Shadow Database feature was designed
|
|
to workaround no longer exist.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
<section id="admin-usermatching">
|
|
<title>User Matching</title>
|
|
<para>
|
|
The settings on this page control how users are selected and queried
|
|
when adding a user to a bug. For example, users need to be selected
|
|
when choosing who the bug is assigned to, adding to the CC list or
|
|
selecting a QA contact. With the "usemenuforusers" parameter, it is
|
|
possible to configure Bugzilla to
|
|
display a list of users in the fields instead of an empty text field.
|
|
This should only be used in Bugzilla installations with a small number
|
|
of users. If users are selected via a text box, this page also
|
|
contains parameters for how user names can be queried and matched
|
|
when entered.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
</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
|
|
will appear in the Administration page.
|
|
</para>
|
|
|
|
<para>
|
|
The first screen is a search form to search for existing user
|
|
accounts. You can run searches based either on the user ID, real
|
|
name or login name (i.e. the email address, or just the first part
|
|
of the email address if the "emailsuffix" parameter is set).
|
|
The search can be conducted
|
|
in different ways using 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. The search can be restricted to users who are in a
|
|
specific group. By default, the restriction is turned off.
|
|
</para>
|
|
|
|
<para>
|
|
The search returns a list of
|
|
users matching your criteria. User properties can be edited by clicking
|
|
the login name. The Account History of a user can be viewed by clicking
|
|
the "View" link in the Account History column. The Account History
|
|
displays changes that have been made to the user account, the time of
|
|
the change and the user who made the change. For example, the Account
|
|
History page will display details of when a user was added or removed
|
|
from a group.
|
|
</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. The first checkbox gives the
|
|
user the ability to add and remove other users as members of
|
|
this group. The second checkbox adds the user himself as a member
|
|
of the group.
|
|
</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" xreflabel="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" xreflabel="Products">
|
|
<title>Products</title>
|
|
|
|
<para>
|
|
<glossterm linkend="gloss-product" baseform="product">
|
|
Products</glossterm> typically represent real-world
|
|
shipping products. Products can be given
|
|
<xref linkend="classifications"/>.
|
|
For example, if a company makes computer games,
|
|
they could have a classification of "Games", and a separate
|
|
product for each game. This company might also have a
|
|
<quote>Common</quote> product for units of technology used
|
|
in multiple games, and perhaps a few special products that
|
|
represent items that are not actually shipping products
|
|
(for example, "Website", or "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>
|
|
When creating or editing products the following options are
|
|
available:
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Product
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
The name of the product
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Description
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
A brief description of the product
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Default milestone
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Select the default milestone for this product.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Closed for bug entry
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Select this box to prevent new bugs from being
|
|
entered against this product.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Maximum votes per person
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Maximum votes a user is allowed to give for this
|
|
product
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Maximum votes a person can put on a single bug
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Maximum votes a user is allowed to give for this
|
|
product in a single bug
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Confirmation threshold
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Number of votes needed to automatically remove any
|
|
bug against this product from the UNCONFIRMED state
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Version
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Specify which version of the product bugs will be
|
|
entered against.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
<term>
|
|
Create chart datasets for this product
|
|
</term>
|
|
<listitem>
|
|
<para>
|
|
Select to make chart datasets available for this product.
|
|
</para>
|
|
</listitem>
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
<para>
|
|
When editing a product there is also a link to edit Group Access Controls,
|
|
see <xref linkend="product-group-controls"/>.
|
|
</para>
|
|
|
|
<section id="create-product">
|
|
<title>Creating New Products</title>
|
|
|
|
<para>
|
|
To create a new product:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>
|
|
Select <quote>Administration</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>
|
|
|
|
<listitem>
|
|
<para>
|
|
When the product is created, Bugzilla will give a message
|
|
stating that a component must be created before any bugs can
|
|
be entered against the new product. Follow the link to create
|
|
a new component. See <xref linkend="components"/> for more
|
|
information.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section id="edit-products">
|
|
<title>Editing Products</title>
|
|
|
|
<para>
|
|
To edit an existing product, click the "Products" link from the
|
|
"Administration" page. If the 'useclassification' parameter is
|
|
turned on, a table of existing classifications is displayed,
|
|
including an "Unclassified" category. The table indicates how many products
|
|
are in each classification. Click on the classification name to see its
|
|
products. If the 'useclassification' parameter is not in use, the table
|
|
lists all products directly. The product table summarizes the information
|
|
about the product defined
|
|
when the product was created. Click on the product name to edit these
|
|
properties, and to access links to other product attributes such as the
|
|
product's components, versions, milestones, and group access controls.
|
|
</para>
|
|
|
|
</section>
|
|
|
|
<section id="comps-vers-miles-products">
|
|
<title>Adding or Editing Components, Versions and Target Milestones</title>
|
|
<para>
|
|
To edit existing, or add new, Components, Versions or Target Milestones
|
|
to a Product, select the "Edit Components", "Edit Versions" or "Edit
|
|
Milestones" links from the "Edit Product" page. A table of existing
|
|
Components, Versions or Milestones is displayed. Click on a item name
|
|
to edit the properties of that item. Below the table is a link to add
|
|
a new Component, Version or Milestone.
|
|
</para>
|
|
<para>
|
|
For more information on components, see <xref linkend="components"/>.
|
|
</para>
|
|
<para>
|
|
For more information on versions, see <xref linkend="versions"/>.
|
|
</para>
|
|
<para>
|
|
For more information on milestones, see <xref linkend="milestones"/>.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="product-group-controls">
|
|
<title>Assigning Group Controls to Products</title>
|
|
|
|
<para>
|
|
On the <quote>Edit Product</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>
|
|
Group Access Controls are an important aspect of using groups for
|
|
isolating products and restricting access to bugs filed against those
|
|
products. For more information on groups, including how to create, edit
|
|
add users to, and alter permission of, see <xref linkend="groups"/>.
|
|
</para>
|
|
|
|
<para>
|
|
After selecting the "Edit Group Access Controls" link from the "Edit
|
|
Product" page, a table containing all user-defined groups for this
|
|
Bugzilla installation is displayed. The system groups that are created
|
|
when Bugzilla is installed are not applicable to Group Access Controls.
|
|
Below is description of what each of these fields means.
|
|
</para>
|
|
|
|
<para>
|
|
Groups may be applicable (e.g bugs in this product can be associated
|
|
with this group) , default (e.g. bugs in this product are in this group
|
|
by default), and mandatory (e.g. bugs in this product must be associated
|
|
with this group) 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. The best way to
|
|
understand these relationships is by example. See
|
|
<xref linkend="group-control-examples"/> for examples of
|
|
product and group relationships.
|
|
</para>
|
|
|
|
<note>
|
|
<para>
|
|
Products and Groups are not limited to a one-to-one relationship.
|
|
Multiple groups can be associated with the same product, and groups
|
|
can be associated with more than one product.
|
|
</para>
|
|
</note>
|
|
|
|
<para>
|
|
If any group has <emphasis>Entry</emphasis> selected, then the
|
|
product will restrict bug entry to only those users
|
|
who are members of <emphasis>all</emphasis> 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 <emphasis>all</emphasis> of the groups with
|
|
<emphasis>Canedit</emphasis> selected. <emphasis>Only</emphasis> users who
|
|
are members of all the <emphasis>Canedit</emphasis> groups
|
|
will be able to edit bugs for this product. This is an additional
|
|
restriction that enables finer-grained control over products rather
|
|
than just all-or-nothing access levels.
|
|
</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> are used in tandem to determine which
|
|
bugs will be placed in this group. The only allowable combinations of
|
|
these two parameters are listed in a table on the "Edit Group Access Controls"
|
|
page. Consult this table for details on how these fields can be used.
|
|
Examples of different uses are described below.
|
|
</para>
|
|
|
|
<section id="group-control-examples">
|
|
<title>Common Applications of Group Controls</title>
|
|
|
|
<para>
|
|
The use of groups is best explained by providing examples that illustrate
|
|
configurations for common use cases. The examples follow a common syntax:
|
|
<emphasis>Group: Entry, MemberControl, OtherControl, CanEdit,
|
|
EditComponents, CanConfirm, EditBugs</emphasis>. Where "Group" is the name
|
|
of the group being edited for this product. The other fields all
|
|
correspond to the table on the "Edit Group Access Controls" page. If any
|
|
of these options are not listed, it means they are not checked.
|
|
</para>
|
|
|
|
<para>
|
|
Basic Product/Group Restriction
|
|
</para>
|
|
|
|
<para>
|
|
Suppose there is a product called "Bar". The
|
|
"Bar" product can only have bugs entered against it by users in the
|
|
group "Foo". Additionally, bugs filed against product "Bar" must stay
|
|
restricted to users to "Foo" at all times. Furthermore, only members
|
|
of group "Foo" can edit bugs filed against product "Bar", even if other
|
|
users could see the bug. This arrangement would achieved by the
|
|
following:
|
|
</para>
|
|
|
|
<programlisting>
|
|
Product Bar:
|
|
foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
|
|
</programlisting>
|
|
|
|
<para>
|
|
Perhaps such strict restrictions are not needed for product "Bar". A
|
|
more lenient way to configure product "Bar" and group "Foo" would be:
|
|
</para>
|
|
|
|
<programlisting>
|
|
Product Bar:
|
|
foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS
|
|
</programlisting>
|
|
|
|
<para>
|
|
The above indicates that for product "Bar", members of group "Foo" can
|
|
enter bugs. Any one with permission to edit a bug against product "Bar"
|
|
can put the bug
|
|
in group "Foo", even if they themselves are not in "Foo". Anyone in group
|
|
"Foo" can edit all aspects of the components of product "Bar", can confirm
|
|
bugs against product "Bar", and can edit all fields of any bug against
|
|
product "Bar".
|
|
</para>
|
|
|
|
<para>
|
|
General User Access With Security Group
|
|
</para>
|
|
|
|
<para>
|
|
To permit any user to file bugs against "Product A",
|
|
and to permit any user to submit those bugs into a
|
|
group called "Security":
|
|
</para>
|
|
|
|
<programlisting>
|
|
Product A:
|
|
security: SHOWN/SHOWN
|
|
</programlisting>
|
|
|
|
<para>
|
|
General User Access With A Security Product
|
|
</para>
|
|
|
|
<para>
|
|
To permit any user to file bugs against product called "Security"
|
|
while keeping those bugs from becoming visible to anyone
|
|
outside the group "SecurityWorkers" (unless a member of the
|
|
"SecurityWorkers" group removes that restriction):
|
|
</para>
|
|
|
|
<programlisting>
|
|
Product Security:
|
|
securityworkers: DEFAULT/MANDATORY
|
|
</programlisting>
|
|
|
|
<para>
|
|
Product Isolation With a Common Group
|
|
</para>
|
|
|
|
<para>
|
|
To permit users of "Product A" to access the bugs for
|
|
"Product A", users of "Product B" to access the bugs for
|
|
"Product B", and support staff, who are members of the "Support
|
|
Group" to access both, three groups are needed:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
<para>Support Group: Contains members of the support staff.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>AccessA Group: Contains users of product A and the Support group.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>AccessB Group: Contains users of product B and the Support group.</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
|
|
<para>
|
|
Once these three groups are defined, the product group controls
|
|
can be set to:
|
|
</para>
|
|
|
|
<programlisting>
|
|
Product A:
|
|
AccessA: ENTRY, MANDATORY/MANDATORY
|
|
Product B:
|
|
AccessB: ENTRY, MANDATORY/MANDATORY
|
|
</programlisting>
|
|
|
|
<para>
|
|
Perhaps the "Support Group" wants more control. For example,
|
|
the "Support Group" could be permitted to make bugs inaccessible to
|
|
users of both groups "AccessA" and "AccessB".
|
|
Then, the "Support Group" could be permitted to publish
|
|
bugs relevant to all users in a third product (let's call it
|
|
"Product Common") that is read-only
|
|
to anyone outside the "Support Group". In this way the "Support Group"
|
|
could control bugs that should be seen by both groups.
|
|
That configuration would 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>
|
|
|
|
<para>
|
|
Make a Product Read Only
|
|
</para>
|
|
|
|
<para>
|
|
Sometimes a product is retired and should no longer have
|
|
new bugs filed against it (for example, an older version of a software
|
|
product that is no longer supported). A product can be made read-only
|
|
by creating a group called "readonly" and adding products to the
|
|
group as needed:
|
|
</para>
|
|
|
|
<programlisting>
|
|
Product A:
|
|
ReadOnly: ENTRY, NA/NA, CANEDIT
|
|
</programlisting>
|
|
|
|
<note>
|
|
<para>
|
|
For more information on Groups outside of how they relate to products
|
|
see <xref linkend="groups"/>.
|
|
</para>
|
|
</note>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
</section>
|
|
|
|
<section id="components" xreflabel="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" parameter in the "Bug Fields" tab of the
|
|
"Parameters" page.
|
|
</para>
|
|
</note>
|
|
|
|
<para>To create new Milestones, and set Default Milestones:</para>
|
|
|
|
<orderedlist>
|
|
<listitem>
|
|
<para>Select "Edit milestones" from the "Edit product" page.</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Select "Add" in the bottom right corner.</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>
|
|
</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 the flag's name.
|
|
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="keywords">
|
|
<title>Keywords</title>
|
|
|
|
<para>
|
|
The administrator can define keywords which can be used to tag and
|
|
categorise bugs. For example, the keyword "regression" is commonly used.
|
|
A company might have a policy stating all regressions
|
|
must be fixed by the next release - this keyword can make tracking those
|
|
bugs much easier.
|
|
</para>
|
|
<para>
|
|
Keywords are global, rather than per-product. If the administrator changes
|
|
a keyword currently applied to any bugs, the keyword cache must be rebuilt
|
|
using the <xref linkend="sanitycheck"/> script. Currently keywords can not
|
|
be marked obsolete to prevent future usage.
|
|
</para>
|
|
<para>
|
|
Keywords can be created, edited or deleted by clicking the "Keywords"
|
|
link in the admin page. There are two fields for each keyword - the keyword
|
|
itself and a brief description. Once created, keywords can be selected
|
|
and applied to individual bugs in that bug's "Details" section.
|
|
</para>
|
|
</section>
|
|
|
|
<section id="custom-fields">
|
|
<title>Custom Fields</title>
|
|
|
|
<para>
|
|
The release of Bugzilla 3.0 added the ability to create Custom Fields.
|
|
Custom Fields are treated like any other field - they can be set in bugs
|
|
and used for search queries. Administrators should keep in mind that
|
|
adding too many fields can make the user interface more complicated and
|
|
harder to use. Custom Fields should be added only when necessary and with
|
|
careful consideration.
|
|
</para>
|
|
<tip>
|
|
<para>
|
|
Before adding a Custom Field, make sure that Bugzilla can not already
|
|
do the desired behavior. Many Bugzilla options are not enabled by
|
|
default, and many times Administrators find that simply enabling
|
|
certain options that already exist is sufficient.
|
|
</para>
|
|
</tip>
|
|
<para>
|
|
Administrators can manage Custom Fields using the
|
|
<quote>Custom Fields</quote> link on the Administration page. The Custom
|
|
Fields administration page displays a list of Custom Fields, if any exist,
|
|
and a link to "Add a new custom field".
|
|
</para>
|
|
|
|
<section id="add-custom-fields">
|
|
<title>Adding Custom Fields</title>
|
|
|
|
<para>
|
|
To add a new Custom Field, click the "Add a new custom field" link. This
|
|
page displays several options for the new field, described below.
|
|
</para>
|
|
|
|
<para>
|
|
The following attributes must be set for each new custom field:
|
|
<itemizedlist>
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Name:</emphasis>
|
|
The name of the field in the database, used internally. This name
|
|
MUST begin with <quote>cf_</quote> to prevent confusion with
|
|
standard fields. If this string is omitted, it will
|
|
be automatically added to the name entered.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Description:</emphasis>
|
|
A brief string which is used as the label for this Custom Field.
|
|
That is the string that users will see, and should be
|
|
short and explicit.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Type:</emphasis>
|
|
The type of field to create. There are
|
|
several types available:
|
|
<simplelist>
|
|
<member>
|
|
Large Text Box: A multiple line box for entering free text.
|
|
</member>
|
|
<member>
|
|
Free Text: A single line box for entering free text.
|
|
</member>
|
|
<member>
|
|
Multiple-Selection Box: A list box where multiple options
|
|
can be selected. After creating this field, it must be edited
|
|
to add the selection options. See
|
|
<xref linkend="edit-values-list" /> for information about
|
|
editing legal values.
|
|
</member>
|
|
<member>
|
|
Drop Down: A list box where only one option can be selected.
|
|
After creating this field, it must be edited to add the
|
|
selection options. See
|
|
<xref linkend="edit-values-list" /> for information about
|
|
editing legal values.
|
|
</member>
|
|
<member>
|
|
Date/Time: A date field. This field appears with a
|
|
calendar widget for choosing the date.
|
|
</member>
|
|
</simplelist>
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Sortkey:</emphasis>
|
|
Integer that determines in which order Custom Fields are
|
|
displayed in the User Interface, especially when viewing a bug.
|
|
Fields with lower values are displayed first.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Can be set on bug creation:</emphasis>
|
|
Boolean that determines whether this field can be set on
|
|
bug creation. If not selected, then a bug must be created
|
|
before this field can be set. See <xref linkend="bugreports" />
|
|
for information about filing bugs.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
<emphasis>Displayed in bugmail for new bugs:</emphasis>
|
|
Boolean that 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>
|
|
Boolean that determines whether 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>
|
|
Only custom fields which are marked as obsolete, and which never
|
|
have been used, can be deleted completely (else the integrity
|
|
of the bug history would be compromised). For custom fields marked
|
|
as obsolete, a "Delete" link will appear in the <quote>Action</quote>
|
|
column. If the custom field has been used in the past, the deletion
|
|
will be rejected. But marking the field as obsolete is sufficient
|
|
to hide it from the user interface entirely.
|
|
</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,
|
|
the list of valid resolutions can be customized from the same interface.
|
|
Since Bugzilla 3.1.1 the list of valid bug statuses can be customized
|
|
as well.
|
|
</para>
|
|
|
|
<section id="edit-values-list">
|
|
<title>Viewing/Editing legal values</title>
|
|
<para>
|
|
Editing legal values requires <quote>admin</quote> privileges.
|
|
Select "Legal Values" from the Administration page. A list of all
|
|
fields, both system fields and Custom Fields, for which legal values
|
|
can be edited appears. Click a field name to edit its legal values.
|
|
</para>
|
|
<para>
|
|
There is no limit to how many values a field can have, but each value
|
|
must be unique to that field. 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>
|
|
Legal values from Custom Fields can be deleted, but only if the
|
|
following two 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="bug_status_workflow">
|
|
<title>Bug Status Workflow</title>
|
|
|
|
<para>
|
|
The bug status workflow is no longer hardcoded but can be freely customized
|
|
from the web interface. Only one bug status cannot be renamed nor deleted,
|
|
UNCONFIRMED, but the workflow involving it is free. The configuration
|
|
page displays all existing bug statuses twice, first on the left for bug
|
|
statuses we come from and on the top for bug statuses we move to.
|
|
If the checkbox is checked, then the transition between the two bug statuses
|
|
is legal, else it's forbidden independently of your privileges. The bug status
|
|
used for the "duplicate_or_move_bug_status" parameter must be part of the
|
|
workflow as that is the bug status which will be used when duplicating or
|
|
moving a bug, so it must be available from each bug status.
|
|
</para>
|
|
<para>
|
|
When the workflow is set, the "View Current Triggers" link below the table
|
|
lets you set which transitions require a comment from the user.
|
|
</para>
|
|
</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 for separating bugs into logical divisions.
|
|
Groups are typically used
|
|
to isolate bugs that should only be seen by certain people. For
|
|
example, a company might create a different group for each one of its customers
|
|
or partners. Group permissions could be set so that each partner or customer would
|
|
only have access to their own bugs. Or, groups might be used to create
|
|
variable access controls for different departments within an organization.
|
|
Another common use of groups is to associate groups with products,
|
|
creating isolation and access control on a per-product basis.
|
|
</para>
|
|
|
|
<para>
|
|
Groups and group behaviors are controlled in several places:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
<para>
|
|
The group configuration page. To view or edit existing groups, or to
|
|
create new groups, access the "Groups" link from the "Administration"
|
|
page. This section of the manual deals primarily with the aspect of
|
|
group controls accessed on this page.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Global configuration parameters. Bugzilla has several parameters
|
|
that control the overall default group behavior and restriction
|
|
levels. For more information on the parameters that control
|
|
group behavior globally, see <xref linkend="param-group-security"/>.
|
|
</para>
|
|
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Product association with groups. Most of the functionality of groups
|
|
and group security is controlled at the product level. Some aspects
|
|
of group access controls for products are discussed in this section,
|
|
but for more detail see <xref linkend="product-group-controls"/>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
Group access for users. See <xref linkend="users-and-groups"/> for
|
|
details on how users are assigned group access.
|
|
</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
|
|
<para>
|
|
Group permissions are such that if a bug belongs to a group, only members
|
|
of that group can see the bug. If a bug is in more than one group, only
|
|
members of <emphasis>all</emphasis> the groups that the bug is in can see
|
|
the bug. For information on granting read-only access to certain people and
|
|
full edit access to others, see <xref linkend="product-group-controls"/>.
|
|
</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 a new group, follow the steps below:
|
|
</para>
|
|
|
|
<orderedlist>
|
|
|
|
<listitem>
|
|
<para>
|
|
Select the <quote>Administration</quote> link in the page footer,
|
|
and then select the <quote>Groups</quote> link from the
|
|
Administration page.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
A table of all the existing groups is displayed. Below the table is a
|
|
description of all the fields. To create a new group, select the
|
|
<quote>Add Group</quote> link under the table of existing groups.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
There are five fields to fill out. These fields are documented below
|
|
the form. Choose a name and description for the group. Decide whether
|
|
this group should be used for bugs (in all likelihood this should be
|
|
selected). Optionally, choose a regular expression that will
|
|
automatically add any matching users to the group, and choose an
|
|
icon that will help identify user comments for the group. The regular
|
|
expression can be useful, for example, to automatically put all users
|
|
from the same company into one group (if the group is for a specific
|
|
customer or partner).
|
|
</para>
|
|
<note>
|
|
<para>
|
|
If <quote>User RegExp</quote> is filled out, 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. If their email address changes
|
|
and no longer matches the regular expression, they will be removed
|
|
from the group. Versions 2.16 and older of Bugzilla did not automatically
|
|
remove users who's email addresses no longer matched the RegExp.
|
|
</para>
|
|
</note>
|
|
<warning>
|
|
<para>
|
|
If specifying a domain in the regular expression, end
|
|
the regexp with a "$". Otherwise, when granting access to
|
|
"@mycompany\.com", access will also be granted to
|
|
'badperson@mycompany.com.cracker.net'. Use the syntax,
|
|
'@mycompany\.com$' for the regular expression.
|
|
</para>
|
|
</warning>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
After the new group is created, it can be edited for additional options.
|
|
The "Edit Group" page allows for specifying other groups that should be included
|
|
in this group and which groups should be permitted to add and delete
|
|
users from this group. For more details, see <xref linkend="edit-groups"/>.
|
|
</para>
|
|
</listitem>
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section id="edit-groups">
|
|
<title>Editing Groups and Assigning Group Permissions</title>
|
|
|
|
<para>
|
|
To access the "Edit Groups" page, select the
|
|
<quote>Administration</quote> link in the page footer,
|
|
and then select the <quote>Groups</quote> link from the Administration page.
|
|
A table of all the existing groups is displayed. Click on a group name
|
|
you wish to edit or control permissions for.
|
|
</para>
|
|
|
|
<para>
|
|
The "Edit Groups" page contains the same five fields present when
|
|
creating a new group. Below that are two additional sections, "Group
|
|
Permissions," and "Mass Remove". The "Mass Remove" option simply removes
|
|
all users from the group who match the regular expression entered. The
|
|
"Group Permissions" section requires further explanation.
|
|
</para>
|
|
|
|
<para>
|
|
The "Group Permissions" section on the "Edit Groups" page contains four sets
|
|
of permissions that control the relationship of this group to other
|
|
groups. If the 'usevisibilitygroups' parameter is in use (see
|
|
<xref linkend="parameters"/>) two additional sets of permissions are displayed.
|
|
Each set consists of two select boxes. On the left, a select box
|
|
with a list of all existing groups. On the right, a select box listing
|
|
all groups currently selected for this permission setting (this box will
|
|
be empty for new groups). The way these controls allow groups to relate
|
|
to one another is called <emphasis>inheritance</emphasis>.
|
|
Each of the six permissions is described below.
|
|
</para>
|
|
|
|
<variablelist>
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
<emphasis>Groups That Are a Member of This Group</emphasis>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Members of any groups selected here will automatically have
|
|
membership in this group. In other words, members of any selected
|
|
group will inherit membership in this group.
|
|
</para>
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
<emphasis>Groups That This Group Is a Member Of</emphasis>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Members of this group will inherit membership to any group
|
|
selected here. For example, suppose the group being edited is
|
|
an Admin group. If there are two products (Product1 and Product2)
|
|
and each product has its
|
|
own group (Group1 and Group2), and the Admin group
|
|
should have access to both products,
|
|
simply select both Group1 and Group2 here.
|
|
</para>
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
<emphasis>Groups That Can Grant Membership in This Group</emphasis>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
The members of any group selected here will be able add users
|
|
to this group, even if they themselves are not in this group.
|
|
</para>
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
<emphasis>Groups That This Group Can Grant Membership In</emphasis>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Members of this group can add users to any group selected here,
|
|
even if they themselves are not in the selected groups.
|
|
</para>
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
<emphasis>Groups That Can See This Group</emphasis>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Members of any selected group can see the users in this group.
|
|
This setting is only visible if the 'usevisibilitygroups' parameter
|
|
is enabled on the Bugzilla Configuration page. See
|
|
<xref linkend="parameters"/> for information on configuring Bugzilla.
|
|
</para>
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
<varlistentry>
|
|
|
|
<term>
|
|
<emphasis>Groups That This Group Can See</emphasis>
|
|
</term>
|
|
|
|
<listitem>
|
|
<para>
|
|
Members of this group can see members in any of the selected groups.
|
|
This setting is only visible if the 'usevisibilitygroups' parameter
|
|
is enabled on the the Bugzilla Configuration page. See
|
|
<xref linkend="parameters"/> for information on configuring Bugzilla.
|
|
</para>
|
|
</listitem>
|
|
|
|
</varlistentry>
|
|
|
|
</variablelist>
|
|
|
|
</section>
|
|
|
|
<section id="users-and-groups">
|
|
<title>Assigning Users to Groups</title>
|
|
|
|
<para>
|
|
A User 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 profile. This can be done by accessing the "Users" page
|
|
from the "Administration" page. Use the search form to find the user
|
|
you want to edit group membership for, and click on their email
|
|
address in the search results to edit their profile. The profile
|
|
page lists all the groups, and indicates if the user is a member of
|
|
the group either directly or indirectly. More information on indirect
|
|
group membership is below. For more details on User administration,
|
|
see <xref linkend="useradmin"/>.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The group can include another group of which the user is
|
|
a member. This is indicated by square brackets around the checkbox
|
|
next to the group name in the user's profile.
|
|
See <xref linkend="edit-groups"/> for details on group inheritance.
|
|
</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>
|
|
The user's email address can match the regular expression
|
|
that has been specified to automatically grant membership to
|
|
the group. This is indicated by "*" around the check box by the
|
|
group name in the user's profile.
|
|
See <xref linkend="create-groups"/> for details on
|
|
the regular expression option when creating groups.
|
|
</para>
|
|
</listitem>
|
|
|
|
</orderedlist>
|
|
|
|
</section>
|
|
|
|
<section>
|
|
<title>Assigning Group Controls to Products</title>
|
|
|
|
<para>
|
|
The primary functionality of groups is derived from the relationship of
|
|
groups to products. The concepts around segregating access to bugs with
|
|
product group controls can be confusing. For details and examples on this
|
|
topic, see <xref linkend="product-group-controls" />.
|
|
</para>
|
|
|
|
</section>
|
|
</section>
|
|
|
|
<section id="sanitycheck">
|
|
<title>Checking and Maintaining Database Integrity</title>
|
|
|
|
<para>
|
|
Over time it is possible for the Bugzilla database to become corrupt
|
|
or to have anomalies.
|
|
This could happen through normal usage of Bugzilla, manual database
|
|
administration outside of the Bugzilla user interface, or from some
|
|
other unexpected event. Bugzilla includes a "Sanity Check" script that
|
|
can perform several basic database checks, and repair certain problems or
|
|
inconsistencies.
|
|
</para>
|
|
<para>
|
|
To run the "Sanity Check" script, log in as an Administrator and click the
|
|
"Sanity Check" link in the admin page. Any problems that are found will be
|
|
displayed in red letters. If the script is capable of fixing a problem,
|
|
it will present a link to initiate the fix. If the script can not
|
|
fix the problem it will require manual database administration or recovery.
|
|
</para>
|
|
<para>
|
|
The "Sanity Check" script can also be run from the command line via the perl
|
|
script <filename>sanitycheck.pl</filename>. The script can also be run as
|
|
a <command>cron</command> job. Results will be delivered by email.
|
|
</para>
|
|
<para>
|
|
The "Sanity Check" script should be run on a regular basis as a matter of
|
|
best practice.
|
|
</para>
|
|
<warning>
|
|
<para>
|
|
The "Sanity Check" script is no substitute for a competent database
|
|
administrator. It is only designed to check and repair basic database
|
|
problems.
|
|
</para>
|
|
</warning>
|
|
|
|
</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:
|
|
-->
|
|
|