diff options
Diffstat (limited to 'docs/en/rst/administration.rst')
| -rw-r--r-- | docs/en/rst/administration.rst | 2149 |
1 files changed, 2149 insertions, 0 deletions
diff --git a/docs/en/rst/administration.rst b/docs/en/rst/administration.rst new file mode 100644 index 000000000..2bac84499 --- /dev/null +++ b/docs/en/rst/administration.rst @@ -0,0 +1,2149 @@ + + +.. _administration: + +====================== +Administering Bugzilla +====================== + +.. _parameters: + +Bugzilla Configuration +###################### + +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. + +.. _param-requiredsettings: + +Required Settings +================= + +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. + +maintainer + Email address of the person + responsible for maintaining this Bugzilla installation. + The address need not be that of a valid Bugzilla account. + +urlbase + Defines the fully qualified domain name and web + server path to this Bugzilla installation. + For example, if the Bugzilla query page is + :file:`http://www.foo.com/bugzilla/query.cgi`, + the ``urlbase`` should be set + to :file:`http://www.foo.com/bugzilla/`. + +docs_urlbase + Defines path to the Bugzilla documentation. This can be a fully + qualified domain name, or a path relative to "urlbase". + For example, if the "Bugzilla Configuration" page + of the documentation is + :file:`http://www.foo.com/bugzilla/docs/html/parameters.html`, + set the ``docs_urlbase`` + to :file:`http://www.foo.com/bugzilla/docs/html/`. + +sslbase + Defines the fully qualified domain name and web + server path for HTTPS (SSL) connections to this Bugzilla installation. + For example, if the Bugzilla main page is + :file:`https://www.foo.com/bugzilla/index.cgi`, + the ``sslbase`` should be set + to :file:`https://www.foo.com/bugzilla/`. + +ssl_redirect + If enabled, Bugzilla will force HTTPS (SSL) connections, by + automatically redirecting any users who try to use a non-SSL + connection. + +cookiedomain + 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 + :file:`https://www.foo.com/`, setting this to + :file:`.foo.com/` will also allow + :file:`bar.foo.com/` to access Bugzilla cookies. + +cookiepath + Defines a path, relative to the web server root, that Bugzilla + cookies will be restricted to. For example, if the + :command:`urlbase` is set to + :file:`http://www.foo.com/bugzilla/`, the + :command:`cookiepath` should be set to + :file:`/bugzilla/`. Setting it to "/" will allow all sites + served by this web server or virtual host to read Bugzilla cookies. + +utf8 + 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 + :file:`contrib/recode.pl` script. + + .. note:: If you turn this parameter from "off" to "on", you must + re-run :file:`checksetup.pl` immediately afterward. + +shutdownhtml + 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. + + .. note:: Although regular log-in capability is disabled + while :command:`shutdownhtml` + is enabled, safeguards are in place to protect the unfortunate + admin who loses connection to Bugzilla. Should this happen to you, + go directly to the :file:`editparams.cgi` (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). + +announcehtml + 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 ``<div>`` + tag. Any style attributes from the CSS can be applied. For example, + to make the text green inside of a red box, add ``id=message`` + to the ``<div>`` tag. + +proxy_url + 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` parameter (below). If the + proxy requires authentication, use the syntax: + :file:`http://user:pass@proxy_url/`. + +upgrade_notification + 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. + +.. _param-admin-policies: + +Administrative Policies +======================= + +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. + +.. _param-user-authentication: + +User Authentication +=================== + +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. + +emailregexp + 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') in a slightly + more restrictive way than what is allowed in RFC 2822. + Some Bugzilla installations allow only local user names (i.e 'user' + instead of 'user@example.com'). In that case, this parameter + should be used to define the email domain. + +emailsuffix + This string is appended to login names when actually sending + email to a user. For example, + If :command:`emailregexp` has been set to allow + local usernames, + then this parameter would contain the email domain for all users + (i.e. '@example.com'). + +.. _param-attachments: + +Attachments +=========== + +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. + +.. _param-bug-change-policies: + +Bug Change Policies +=================== + +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. + +commenton* + 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. + Set the "commenton" options according to your site policy. It + is a wise idea to require comments when users resolve, reassign, or + reopen bugs at the very least. + + .. note:: 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!) + +noresolveonopenblockers + 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. + +.. _param-bugfields: + +Bug Fields +========== + +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. + +useqacontact + 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. + +usestatuswhiteboard + 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. + +.. _param-bugmoving: + +Bug Moving +========== + +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 *from* other bug databases to this +Bugzilla installation are assigned to. + +.. _param-dependency-graphs: + +Dependency Graphs +================= + +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 :file:`.dot` graphic description files. If +no Web Dot server or binary is specified, then dependency graphs will +be disabled. + +.. _param-group-security: + +Group Security +============== + +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 +:ref:`groups` + +makeproductgroups + 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. + +usevisibilitygroups + 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 :ref:`edit-groups`. + +querysharegroup + 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 :ref:`savedsearches`. + +.. _bzldap: + +LDAP Authentication +=================== + +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. + +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. + +.. caution:: 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 :file:`bugzilla_ldapsync.rb` + script in the :file:`contrib` + directory. Another possible solution is fixing + `bug + 201069 <https://bugzilla.mozilla.org/show_bug.cgi?id=201069>`_. + +Parameters required to use LDAP Authentication: + +user_verify_class + If you want to list ``LDAP`` 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 + :file:`data/params` and set user_verify_class to + ``DB``. + +LDAPserver + 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. + For example: ``ldap.company.com`` + or ``ldap.company.com:3268`` + 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. + + .. tip:: In order to use SSL with LDAP, specify a URI with "ldaps://". + This will force the use of SSL over port 636. + For example, normal LDAP: + ``ldap://ldap.company.com``, LDAP over SSL: + ``ldaps://ldap.company.com`` or LDAP over a UNIX + domain socket ``ldapi://%2fvar%2flib%2fldap_sock``. + +LDAPbinddn \[Optional] + 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. + Ex. ``cn=default,cn=user:password`` + +LDAPBaseDN + 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. + Ex. ``ou=People,o=Company`` + +LDAPuidattribute + 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. + Ex. ``uid`` + +LDAPmailattribute + The LDAPmailattribute parameter should be the name of the + attribute which contains the email address your users will enter + into the Bugzilla login boxes. + Ex. ``mail`` + +.. _bzradius: + +RADIUS Authentication +===================== + +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. + +.. note:: Most caveats that apply to LDAP authentication apply to RADIUS + authentication as well. See :ref:`bzldap` for details. + +Parameters required to use RADIUS Authentication: + +user_verify_class + If you want to list ``RADIUS`` 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 + :file:`data/params` and set user_verify_class to + ``DB``. + +RADIUS_server + This parameter should be set to the name (and optionally the + port) of your RADIUS server. + +RADIUS_secret + This parameter should be set to the RADIUS server's secret. + +RADIUS_email_suffix + 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. + If this simple solution does not work for you, you'll + probably need to modify + :file:`Bugzilla/Auth/Verify/RADIUS.pm` to match your + requirements. + +.. _param-email: + +Email +===== + +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. + +mail_delivery_method + 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 + :file:`data/mailer.testfile` for later review. + "None" disables email sending entirely. + +mailfrom + 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. + +smtpserver + This is the SMTP server address, if the ``mail_delivery_method`` + parameter is set to SMTP. Use "localhost" if you have a local MTA + running, otherwise use a remote SMTP server. Append ":" and the port + number, if a non-default port is needed. + +smtp_username + Username to use for SASL authentication to the SMTP server. Leave + this parameter empty if your server does not require authentication. + +smtp_password + Password to use for SASL authentication to the SMTP server. This + parameter will be ignored if the ``smtp_username`` + parameter is left empty. + +smtp_ssl + Enable SSL support for connection to the SMTP server. + +smtp_debug + This parameter allows you to enable detailed debugging output. + Log messages are printed the web server's error log. + +whinedays + Set this to the number of days you want to let bugs go + in the CONFIRMED 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). + +globalwatcher + 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. + +.. _param-patchviewer: + +Patch Viewer +============ + +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. + +.. _param-querydefaults: + +Query Defaults +============== + +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. + +.. _param-shadowdatabase: + +Shadow Database +=============== + +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. + +The ``shadowdb`` 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. + +.. note:: 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. + +.. _admin-usermatching: + +User Matching +============= + +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. + +Another setting called 'ajax_user_autocompletion' enables certain +user fields to display a list of matched user names as a drop down after typing +a few characters. Note that it is recommended to use mod_perl when +enabling 'ajax_user_autocompletion'. + +.. _useradmin: + +User Administration +################### + +.. _defaultuser: + +Creating the Default User +========================= + +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. + +.. tip:: 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). + +.. _manageusers: + +Managing Other Users +==================== + +.. _user-account-search: + +Searching for existing users +---------------------------- + +If you have ``editusers`` privileges or if you are allowed +to grant privileges for some groups, the ``Users`` link +will appear in the Administration page. + +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 *reverse* 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. + +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. + +.. _createnewusers: + +Creating new users +------------------ + +.. _self-registration: + +Self-registration +~~~~~~~~~~~~~~~~~ + +By default, users can create their own user accounts by clicking the +``New Account`` link at the bottom of each page (assuming +they aren't logged in as someone else already). 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 ``createemailregexp`` +parameter in the ``Configuration`` page, see +:ref:`parameters`. + +.. _user-account-creation: + +Accounts created by an administrator +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Users with ``editusers`` privileges, such as administrators, +can create user accounts for other users: + +#. After logging in, click the "Users" link at the footer of + the query page, and then click "Add a new user". + +#. Fill out the form presented. This page is self-explanatory. + When done, click "Submit". + + .. note:: Adding a user this way will *not* + 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 ``New Account`` + button to create users, as it will pre-populate all the + required fields and also notify the user of her account name + and password. + +.. _modifyusers: + +Modifying Users +--------------- + +Once you have found your user, you can change the following +fields: + +- *Login Name*: + This is generally the user's full email address. However, if you + have are using the ``emailsuffix`` 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). + +- *Real Name*: The user's real name. Note that + Bugzilla does not require this to create an account. + +- *Password*: + 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. + +- *Bugmail Disabled*: + 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. + +- *Disable Text*: + 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. + 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 + ``Bugmail Disabled`` checkbox above. + + .. note:: Even users whose accounts have been disabled can still + submit bugs via the e-mail gateway, if one exists. + The e-mail gateway should *not* be + enabled for secure installations of Bugzilla. + + .. warning:: Don't disable all the administrator accounts! + +- *<groupname>*: + 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. + +- *canconfirm*: + 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). + +- *creategroups*: + This option will allow a user to create and destroy groups in + Bugzilla. + +- *editbugs*: + 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. + +- *editcomponents*: + 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. + +- *editkeywords*: + 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. + +- *editusers*: + 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. + +- *tweakparams*: + This flag allows a user to change Bugzilla's Params + (using :file:`editparams.cgi`.) + +- *<productname>*: + This allows an administrator to specify the products + in which a user can see bugs. If you turn on the + ``makeproductgroups`` 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 ``editbugs`` + privilege to edit bugs in these products. + +.. _user-account-deletion: + +Deleting Users +-------------- + +If the ``allowuserdeletion`` parameter is turned on, see +:ref:`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! + +.. _impersonatingusers: + +Impersonating Users +------------------- + +There may be times when an administrator would like to do something as +another user. The :command:`sudo` feature may be used to do +this. + +.. note:: To use the sudo feature, you must be in the + *bz_sudoers* group. By default, all + administrators are in this group. + +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. + +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. + +.. warning:: 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. + +.. _classifications: + +Classifications +############### + +Classifications tend to be used in order to group several related +products into one distinct entity. + +The classifications layer is disabled by default; it can be turned +on or off using the useclassification parameter, +in the *Bug Fields* section of the edit parameters screen. + +Access to the administration of classifications is controlled using +the *editclassifications* system group, which defines +a privilege for creating, destroying, and editing classifications. + +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. + +.. _products: + +Products +######## + +Products typically represent real-world +shipping products. Products can be given +:ref:`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 +``Common`` 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"). + +Many of Bugzilla's settings are configurable on a per-product +basis. The number of ``votes`` available to +users is set per-product, as is the number of votes +required to move a bug automatically from the UNCONFIRMED +status to the CONFIRMED status. + +When creating or editing products the following options are +available: + +Product + The name of the product + +Description + A brief description of the product + +Default milestone + Select the default milestone for this product. + +Closed for bug entry + Select this box to prevent new bugs from being + entered against this product. + +Maximum votes per person + Maximum votes a user is allowed to give for this + product + +Maximum votes a person can put on a single bug + Maximum votes a user is allowed to give for this + product in a single bug + +Confirmation threshold + Number of votes needed to automatically remove any + bug against this product from the UNCONFIRMED state + +Version + Specify which version of the product bugs will be + entered against. + +Create chart datasets for this product + Select to make chart datasets available for this product. + +When editing a product there is also a link to edit Group Access Controls, +see :ref:`product-group-controls`. + +.. _create-product: + +Creating New Products +===================== + +To create a new product: + +#. Select ``Administration`` from the footer and then + choose ``Products`` from the main administration page. + +#. Select the ``Add`` link in the bottom right. + +#. Enter the name of the product and a description. The + Description field may contain HTML. + +#. 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 :ref:`components` for more + information. + +.. _edit-products: + +Editing Products +================ + +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. + +.. _comps-vers-miles-products: + +Adding or Editing Components, Versions and Target Milestones +============================================================ + +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. + +For more information on components, see :ref:`components`. + +For more information on versions, see :ref:`versions`. + +For more information on milestones, see :ref:`milestones`. + +.. _product-group-controls: + +Assigning Group Controls to Products +==================================== + +On the ``Edit Product`` page, there is a link called +``Edit Group Access Controls``. The settings on this page +control the relationship of the groups to the product being edited. + +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 :ref:`groups`. + +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. + +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 +:ref:`group-control-examples` for examples of +product and group relationships. + +.. note:: 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. + +If any group has *Entry* selected, then the +product will restrict bug entry to only those users +who are members of *all* the groups with +*Entry* selected. + +If any group has *Canedit* selected, +then the product will be read-only for any users +who are not members of *all* of the groups with +*Canedit* selected. *Only* users who +are members of all the *Canedit* 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. + +The following settings let you +choose privileges on a *per-product basis*. +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. + +Any group having *editcomponents* +selected allows users who are in this group to edit all +aspects of this product, including components, milestones +and versions. + +Any group having *canconfirm* selected +allows users who are in this group to confirm bugs +in this product. + +Any group having *editbugs* selected allows +users who are in this group to edit all fields of +bugs in this product. + +The *MemberControl* and +*OtherControl* 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. + +.. _group-control-examples: + +Common Applications of Group Controls +===================================== + +The use of groups is best explained by providing examples that illustrate +configurations for common use cases. The examples follow a common syntax: +*Group: Entry, MemberControl, OtherControl, CanEdit, +EditComponents, CanConfirm, EditBugs*. 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. + +Basic Product/Group Restriction +------------------------------- + +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: + +:: + + Product Bar: + foo: ENTRY, MANDATORY/MANDATORY, CANEDIT + +Perhaps such strict restrictions are not needed for product "Bar". A +more lenient way to configure product "Bar" and group "Foo" would be: + +:: + + Product Bar: + foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS + +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". + +General User Access With Security Group +--------------------------------------- + +To permit any user to file bugs against "Product A", +and to permit any user to submit those bugs into a +group called "Security": + +:: + + Product A: + security: SHOWN/SHOWN + +General User Access With A Security Product +------------------------------------------- + +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): + +:: + + Product Security: + securityworkers: DEFAULT/MANDATORY + +Product Isolation With a Common Group +------------------------------------- + +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: + +#. Support Group: Contains members of the support staff. + +#. AccessA Group: Contains users of product A and the Support group. + +#. AccessB Group: Contains users of product B and the Support group. + +Once these three groups are defined, the product group controls +can be set to: + +:: + + Product A: + AccessA: ENTRY, MANDATORY/MANDATORY + Product B: + AccessB: ENTRY, MANDATORY/MANDATORY + +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: + +:: + + 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 + +Make a Product Read Only +------------------------ + +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: + +:: + + Product A: + ReadOnly: ENTRY, NA/NA, CANEDIT + +.. note:: For more information on Groups outside of how they relate to products + see :ref:`groups`. + +.. _components: + +Components +########## + +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. + +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 +*default assignments*; +these can be changed on bug submission, or at any later point in +a bug's life. + +To create a new Component: + +#. Select the ``Edit components`` link + from the ``Edit product`` page + +#. Select the ``Add`` link in the bottom right. + +#. Fill out the ``Component`` field, a + short ``Description``, the + ``Default Assignee``, ``Default CC List`` + and ``Default QA Contact`` (if enabled). + The ``Component Description`` field may contain a + limited subset of HTML tags. The ``Default Assignee`` + field must be a login name already existing in the Bugzilla database. + +.. _versions: + +Versions +######## + +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. + +To create and edit Versions: + +#. From the "Edit product" screen, select "Edit Versions" + +#. You will notice that the product already has the default + version "undefined". Click the "Add" link in the bottom right. + +#. Enter the name of the Version. This field takes text only. + Then click the "Add" button. + +.. _milestones: + +Milestones +########## + +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. + +.. note:: Milestone options will only appear for a Product if you turned + on the "usetargetmilestone" parameter in the "Bug Fields" tab of the + "Parameters" page. + +To create new Milestones, and set Default Milestones: + +#. Select "Edit milestones" from the "Edit product" page. + +#. Select "Add" in the bottom right corner. + +#. 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". + +.. _flags-overview: + +Flags +##### + +Flags are a way to attach a specific status to a bug or attachment, +either ``+`` or ``-``. 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 ``?`` as a +request to another user that they look at the bug/attachment, and set +the flag to its correct status. + +.. _flags-simpleexample: + +A Simple Example +================ + +A developer might want to ask their manager, +``Should we fix this bug before we release version 2.0?`` +They might want to do this for a *lot* of bugs, +so it would be nice to streamline the process... + +In Bugzilla, it would work this way: + +#. The Bugzilla administrator creates a flag type called + ``blocking2.0`` that shows up on all bugs in + your product. + It shows up on the ``Show Bug`` screen + as the text ``blocking2.0`` with a drop-down box next + to it. The drop-down box contains four values: an empty space, + ``?``, ``-``, and ``+``. + +#. The developer sets the flag to ``?``. + +#. The manager sees the ``blocking2.0`` + flag with a ``?`` value. + +#. If the manager thinks the feature should go into the product + before version 2.0 can be released, he sets the flag to + ``+``. Otherwise, he sets it to ``-``. + +#. 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. + +.. _flags-about: + +About Flags +=========== + +.. _flag-values: + +Values +------ + +Flags can have three values: + +``?`` + A user is requesting that a status be set. (Think of it as 'A question is being asked'.) + +``-`` + The status has been set negatively. (The question has been answered ``no``.) + +``+`` + The status has been set positively. + (The question has been answered ``yes``.) + +Actually, there's a fourth value a flag can have -- +``unset`` -- 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. + +.. _flag-askto: + +Using flag requests +=================== + +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 ``?``. +This status indicates that someone (a.k.a. ``the requester``) is asking +someone else to set the flag to either ``+`` or ``-``. + +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. ``the requestee``) +will receive an email notifying them of the request, and pointing them +to the bug/attachment in question. + +If a flag has *not* 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 ``to the wind``. +A requester may ``ask the wind`` on any flag simply by leaving the text-box blank. + +.. _flag-types: + +Two Types of Flags +================== + +Flags can go in two places: on an attachment, or on a bug. + +.. _flag-type-attachment: + +Attachment Flags +---------------- + +Attachment flags are used to ask a question about a specific +attachment on a bug. + +Many Bugzilla installations use this to +request that one developer ``review`` 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 +``review`` to +``review?boss@domain.com``. +boss@domain.com is then notified by email that +he has to check out that attachment and approve it or deny it. + +For a Bugzilla user, attachment flags show up in three places: + +#. On the list of attachments in the ``Show Bug`` + 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). + +#. When you ``Edit`` an attachment, you can + see any settable flag, along with any flags that have + already been set. This ``Edit Attachment`` + screen is where you set flags to ?, -, +, or unset them. + +#. Requests are listed in the ``Request Queue``, which + is accessible from the ``My Requests`` link (if you are + logged in) or ``Requests`` link (if you are logged out) + visible in the footer of all pages. + +.. _flag-type-bug: + +Bug Flags +--------- + +Bug flags are used to set a status on the bug itself. You can +see Bug Flags in the ``Show Bug`` and ``Requests`` +screens, as described above. + +Only users with enough privileges (see below) may set flags on bugs. +This doesn't necessarily include the assignee, reporter, or users with the +``editbugs`` permission. + +.. _flags-admin: + +Administering Flags +=================== + +If you have the ``editcomponents`` permission, you can +edit Flag Types from the main administration page. Clicking the +``Flags`` link will bring you to the ``Administer +Flag Types`` page. Here, you can select whether you want +to create (or edit) a Bug flag, or an Attachment flag. + +No matter which you choose, the interface is the same, so we'll +just go over it once. + +.. _flags-edit: + +Editing a Flag +-------------- + +To edit a flag's properties, just click the flag's name. +That will take you to the same +form as described below (:ref:`flags-create`). + +.. _flags-create: + +Creating a Flag +--------------- + +When you click on the ``Create a Flag Type for...`` +link, you will be presented with a form. Here is what the fields in +the form mean: + +.. _flags-create-field-name: + +Name +~~~~ + +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. + +.. _flags-create-field-description: + +Description +~~~~~~~~~~~ + +The description describes the flag in more detail. It is visible +in a tooltip when hovering over a flag either in the ``Show Bug`` +or ``Edit Attachment`` pages. This field can be as +long as you like, and can contain any character you want. + +.. _flags-create-field-category: + +Category +~~~~~~~~ + +Default behaviour for a newly-created flag is to appear on +products and all components, which is why ``__Any__:__Any__`` +is already entered in the ``Inclusions`` 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 ``__Any__:__Any__`` from the Inclusions box +and define products/components specifically for this flag. + +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 ``__Any__`` for Product translates to, +``all the products in this Bugzilla``. +Selecting ``__Any__`` in the Component field means +``all components in the selected product.``) +Selections made, press ``Include``, and your +Product/Component pairing will show up in the ``Inclusions`` box on the right. + +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 +``Exclude``. The Product/Component pairing will show up in the +``Exclusions`` box on the right. + +This flag *will* and *can* be set for any +products/components that appearing in the ``Inclusions`` box +(or which fall under the appropriate ``__Any__``). +This flag *will not* appear (and therefore cannot be set) on +any products appearing in the ``Exclusions`` box. +*IMPORTANT: Exclusions override inclusions.* + +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. + +*Example:* Let's say you have a product called +``Jet Plane`` 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 ``fixInNext``. +But, there's one component in ``Jet Plane,`` +called ``Pilot.`` 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 ``Jet Plane:__Any__`` and you exclude +``Jet Plane:Pilot``. + +.. _flags-create-field-sortkey: + +Sort Key +~~~~~~~~ + +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. + +*Example:* 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. + +.. _flags-create-field-active: + +Active +~~~~~~ + +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 ``active``. 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. + +.. _flags-create-field-requestable: + +Requestable +~~~~~~~~~~~ + +New flags are, by default, ``requestable``, meaning that they +offer users the ``?`` option, as well as ``+`` +and ``-``. +To remove the ? option, uncheck ``requestable``. + +.. _flags-create-field-specific: + +Specifically Requestable +~~~~~~~~~~~~~~~~~~~~~~~~ + +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 ``to the wind.`` 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). + +.. _flags-create-field-multiplicable: + +Multiplicable +~~~~~~~~~~~~~ + +Any flag with ``Multiplicable`` 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 ``addl.`` (short for +``additional``) before the name. There is no limit to the number of +times a Multiplicable flags may be set on the same bug/attachment. + +.. _flags-create-field-cclist: + +CC List +~~~~~~~ + +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. + +.. _flags-create-grant-group: + +Grant Group +~~~~~~~~~~~ + +When this field is set to some given group, only users in the group +can set the flag to ``+`` and ``-``. This +field does not affect who can request or cancel the flag. For that, +see the ``Request Group`` 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. + +.. _flags-create-request-group: + +Request Group +~~~~~~~~~~~~~ + +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 ``grant group`` 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. + +.. COMMENT: flags-create + +.. _flags-delete: + +Deleting a Flag +--------------- + +When you are at the ``Administer Flag Types`` screen, +you will be presented with a list of Bug flags and a list of Attachment +Flags. + +To delete a flag, click on the ``Delete`` link next to +the flag description. + +.. warning:: Once you delete a flag, it is *gone* 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 ``active`` in the flag Edit form. + +.. COMMENT: flags-admin + +.. COMMENT: XXX We should add a "Uses of Flags" section, here, with examples. + +.. COMMENT: flags + +.. _keywords: + +Keywords +######## + +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. + +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 :ref:`sanitycheck` script. Currently keywords cannot +be marked obsolete to prevent future usage. + +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. + +.. _custom-fields: + +Custom Fields +############# + +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. + +.. tip:: Before adding a Custom Field, make sure that Bugzilla cannot 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. + +Administrators can manage Custom Fields using the +``Custom Fields`` 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". + +.. _add-custom-fields: + +Adding Custom Fields +==================== + +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. + +The following attributes must be set for each new custom field: + +- *Name:* + The name of the field in the database, used internally. This name + MUST begin with ``cf_`` to prevent confusion with + standard fields. If this string is omitted, it will + be automatically added to the name entered. + +- *Description:* + 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. + +- *Type:* + The type of field to create. There are + several types available: + + Bug ID: + A field where you can enter the ID of another bug from + the same Bugzilla installation. To point to a bug in a remote + installation, use the See Also field instead. + Large Text Box: + A multiple line box for entering free text. + Free Text: + A single line box for entering free text. + 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 + :ref:`edit-values-list` for information about + editing legal values. + 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 + :ref:`edit-values-list` for information about + editing legal values. + Date/Time: + A date field. This field appears with a + calendar widget for choosing the date. + +- *Sortkey:* + 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. + +- *Reverse Relationship Description:* + When the custom field is of type ``Bug ID``, you can + enter text here which will be used as label in the referenced + bug to list bugs which point to it. This gives you the ability + to have a mutual relationship between two bugs. + +- *Can be set on bug creation:* + 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 :ref:`bugreports` + for information about filing bugs. + +- *Displayed in bugmail for new bugs:* + 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. + +- *Is obsolete:* + Boolean that determines whether this field should + be displayed at all. Obsolete Custom Fields are hidden. + +- *Is mandatory:* + Boolean that determines whether this field must be set. + For single and multi-select fields, this means that a (non-default) + value must be selected, and for text and date fields, some text + must be entered. + +- *Field only appears when:* + A custom field can be made visible when some criteria is met. + For instance, when the bug belongs to one or more products, + or when the bug is of some given severity. If left empty, then + the custom field will always be visible, in all bugs. + +- *Field that controls the values that appear in this field:* + When the custom field is of type ``Drop Down`` or + ``Multiple-Selection Box``, you can restrict the + availability of the values of the custom field based on the + value of another field. This criteria is independent of the + criteria used in the ``Field only appears when`` + setting. For instance, you may decide that some given value + ``valueY`` is only available when the bug status + is RESOLVED while the value ``valueX`` should + always be listed. + Once you have selected the field which should control the + availability of the values of this custom field, you can + edit values of this custom field to set the criteria, see + :ref:`edit-values-list`. + +.. _edit-custom-fields: + +Editing Custom Fields +===================== + +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 :ref:`edit-values-list`. All +other attributes can be edited as described above. + +.. _delete-custom-fields: + +Deleting Custom Fields +====================== + +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 ``Action`` +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. + +.. _edit-values: + +Legal Values +############ + +Legal values for the operating system, platform, bug priority and +severity, custom fields of type ``Drop Down`` and +``Multiple-Selection Box`` (see :ref:`custom-fields`), +as well as the list of valid bug statuses and resolutions can be +customized from the same interface. You can add, edit, disable and +remove values which can be used with these fields. + +.. _edit-values-list: + +Viewing/Editing legal values +============================ + +Editing legal values requires ``admin`` privileges. +Select "Field 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. + +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. + +When the availability of the values of a custom field is controlled +by another field, you can select from here which value of the other field +must be set for the value of the custom field to appear. + +.. _edit-values-delete: + +Deleting legal values +===================== + +Legal values from Custom Fields can be deleted, but only if the +following two conditions are respected: + +#. The value is not used by default for the field. + +#. No bug is currently using this value. + +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. + +.. _bug_status_workflow: + +Bug Status Workflow +################### + +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. + +When the workflow is set, the "View Current Triggers" link below the table +lets you set which transitions require a comment from the user. + +.. _voting: + +Voting +###### + +All of the code for voting in Bugzilla has been moved into an +extension, called "Voting", in the :file:`extensions/Voting/` +directory. To enable it, you must remove the :file:`disabled` +file from that directory, and run :file:`checksetup.pl`. + +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 +"CONFIRMED", users of the bug system can help high-priority bugs garner +attention so they don't sit for a long time awaiting triage. + +To modify Voting settings: + +#. Navigate to the "Edit product" screen for the Product you + wish to modify + +#. *Maximum Votes per person*: + Setting this field to "0" disables voting. + +#. *Maximum Votes a person can put on a single + bug*: + 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. + +#. *Number of votes a bug in this product needs to + automatically get out of the UNCONFIRMED state*: + Setting this field to "0" disables the automatic move of + bugs from UNCONFIRMED to CONFIRMED. + +#. Once you have adjusted the values to your preference, click + "Update". + +.. _quips: + +Quips +##### + +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. + +Quip submission is controlled by the *quip_list_entry_control* +parameter. It has several possible values: open, moderated, or closed. +In order to enable quips approval you need to set this parameter to +"moderated". In this way, users are free to submit quips for addition +but an administrator must explicitly approve them before they are +actually used. + +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. + +Next to each quip 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. + +Also, there is a delete link next to each quip, +which can be used in order to permanently delete a quip. + +Display of quips is controlled by the *display_quips* +user preference. Possible values are "on" and "off". + +.. _groups: + +Groups and Group Security +######################### + +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. + +Groups and group behaviors are controlled in several places: + +#. 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. + +#. 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 :ref:`param-group-security`. + +#. 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 :ref:`product-group-controls`. + +#. Group access for users. See :ref:`users-and-groups` for + details on how users are assigned group access. + +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 *all* 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 :ref:`product-group-controls`. + +.. note:: 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 ``Users in the roles selected below...`` + and un-checking the box next to either 'Reporter' or 'CC List' (or both). + +.. _create-groups: + +Creating Groups +=============== + +To create a new group, follow the steps below: + +#. Select the ``Administration`` link in the page footer, + and then select the ``Groups`` link from the + Administration page. + +#. 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 + ``Add Group`` link under the table of existing groups. + +#. 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). + + .. note:: If ``User RegExp`` 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. + + .. warning:: 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. + +#. 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 :ref:`edit-groups`. + +.. _edit-groups: + +Editing Groups and Assigning Group Permissions +============================================== + +To access the "Edit Groups" page, select the +``Administration`` link in the page footer, +and then select the ``Groups`` 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. + +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. + +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 +:ref:`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 *inheritance*. +Each of the six permissions is described below. + +*Groups That Are a Member of This Group* + 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. + +*Groups That This Group Is a Member Of* + 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. + +*Groups That Can Grant Membership in This Group* + The members of any group selected here will be able add users + to this group, even if they themselves are not in this group. + +*Groups That This Group Can Grant Membership In* + Members of this group can add users to any group selected here, + even if they themselves are not in the selected groups. + +*Groups That Can See This Group* + 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 + :ref:`parameters` for information on configuring Bugzilla. + +*Groups That This Group Can See* + 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 + :ref:`parameters` for information on configuring Bugzilla. + +.. _users-and-groups: + +Assigning Users to Groups +========================= + +A User can become a member of a group in several ways: + +#. 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 :ref:`useradmin`. + +#. 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 :ref:`edit-groups` for details on group inheritance. + +#. 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 :ref:`create-groups` for details on + the regular expression option when creating groups. + +Assigning Group Controls to Products +==================================== + +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 :ref:`product-group-controls`. + +.. _sanitycheck: + +Checking and Maintaining Database Integrity +########################################### + +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. + +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 cannot +fix the problem it will require manual database administration or recovery. + +The "Sanity Check" script can also be run from the command line via the perl +script :file:`sanitycheck.pl`. The script can also be run as +a :command:`cron` job. Results will be delivered by email. + +The "Sanity Check" script should be run on a regular basis as a matter of +best practice. + +.. warning:: The "Sanity Check" script is no substitute for a competent database + administrator. It is only designed to check and repair basic database + problems. + + |