From 8ab64629d3a091a0ccb6af52c48ee7bb9fd8834d Mon Sep 17 00:00:00 2001 From: "lpsolit%gmail.com" <> Date: Fri, 4 Apr 2008 00:05:36 +0000 Subject: Bug 182975: Bugzilla directory structure to be adopted to l10n needs - Patch by A.A. Shimono (himorin) r=LpSolit r=mkanat a=LpSolit --- docs/en/xml/administration.xml | 3448 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 3448 insertions(+) create mode 100644 docs/en/xml/administration.xml (limited to 'docs/en/xml/administration.xml') diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml new file mode 100644 index 000000000..7a75604de --- /dev/null +++ b/docs/en/xml/administration.xml @@ -0,0 +1,3448 @@ + + + Administering Bugzilla + +
+ 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. + + +
+ 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. + + + + checklist + + + + + + + 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 + http://www.foo.com/bugzilla/query.cgi, + the urlbase should be set + to 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 + http://www.foo.com/bugzilla/docs/html/parameters.html, + set the docs_urlbase + to 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 + https://www.foo.com/bugzilla/index.cgi, + the sslbase should be set + to https://www.foo.com/bugzilla/. + + + + + + + ssl + + + + Determines when Bugzilla will force HTTPS (SSL) connections, using + the URL defined in sslbase. + Options include "always", "never", and "authenticated sessions". + + + + + + + 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 + https://www.foo.com/, setting this to + .foo.com/ will also allow + 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 + urlbase is set to + http://www.foo.com/bugzilla/, the + cookiepath should be set to + /bugzilla/. Setting it to "/" will allow all sites + served by this web server or virtual host to read Bugzilla cookies. + + + + + + + timezone + + + + Timezone of server. The timezone is displayed with timestamps. If + this parameter is left blank, the timezone is not displayed. + + + + + + + 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 + contrib/recode.pl script. + + + + If you turn this parameter from "off" to "on", you must re-run + 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. + + + + Although regular log-in capability is disabled while + shutdownhtml + is enabled, safeguards are in place to protect the unfortunate + admin who loses connection to Bugzilla. Should this happen to you, + go directly to the 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 + upgrade_notification parameter (below). If the + proxy requires authentication, use the syntax: + 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. + + + + + + +
+ +
+ Administrative Policies + + This page contains parameters for basic administrative functions. + Options include whether to allow the deletion of bugs and users, whether + to allow users to change their email address, and whether to allow + user watching (one user receiving all notifications of a selected + other user). + + + + + + + supportwatchers + + + + Turning on this option allows users to ask to receive copies + of bug mail sent to another user. Watching a user with + different group permissions is not a way to 'get around' the + system; copied emails are still subject to the normal groupset + permissions of a bug, and watchers will only be + copied on emails from bugs they would normally be allowed to view. + + + + + + +
+ +
+ 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'). Some + Bugzilla installations allow only local user names (i.e 'user' + instead of 'user@example.com'). In that case, the + emailsuffix 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 emailregexp has been set to allow + local usernames, + then this parameter would contain the email domain for all users + (i.e. '@example.com'). + + + + + + +
+ +
+ 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. + +
+ +
+ 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. + + + + + 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. + + + + + + +
+ +
+ 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. + + + + + + +
+ +
+ 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. + + +
+ +
+ 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 .dot graphic description files. If + no Web Dot server or binary is specified, then dependency graphs will + be disabled. + +
+ +
+ 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 + + + + + + + + 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. + + + + + + + useentrygroupdefault + + + + Bugzilla products can have a group associated with them, so that + certain users can only see bugs in certain products. When this + parameter is set to on, this + causes the initial group controls on newly created products + to place all newly-created bugs in the group + having the same name as the product immediately. + After a product is initially created, the group controls + can be further adjusted without interference by + this mechanism. + + + + + + + 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 . + + + + + + + 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 . + + + + + + +
+ +
+ 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. + + + + 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 bugzilla_ldapsync.rb + script in the + + contrib + directory. Another possible solution is fixing + bug + 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 + 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. + + Ex. 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. + + Ex. ldap://ldap.company.com, + ldaps://ldap.company.com or + 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 + + + + +
+ +
+ 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. + + + + Most caveats that apply to LDAP authentication apply to RADIUS + authentication as well. See 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 + 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 + Bugzilla/Auth/Verify/RADIUS.pm to match your + requirements. + + + + + +
+ +
+ 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 + 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. + + + + + + + sendmailnow + + + + 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). + + + + + + + whinedays + + + + 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). + + + + + + + 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. + + + + + + +
+ +
+ 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. + +
+ +
+ 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. + +
+ +
+ 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. + + + + + 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. + + + +
+ +
+ 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. + + +
+ +
+ +
+ User Administration + +
+ 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. + + + 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). + + +
+ +
+ Managing Other Users + + + +
+ Creating new users + +
+ 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 + . + +
+ +
+ 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". + + + 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. + + + +
+
+ +
+ 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. + + + + 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. + + + + + 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. + + + + + + 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 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. + + +
+ +
+ Deleting Users + + If the allowuserdeletion parameter is turned on, see + , 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! + +
+ +
+ Impersonating Users + + + There may be times when an administrator would like to do something as + another user. The sudo feature may be used to do + this. + + + + + 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. + + + + 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 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 typically represent real-world + shipping products. Products can be given + . + 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 NEW status. + + + + When creating or editing products the following options are + available: + + + + + + + Product + + + + The name of the product + + + + + + + Description + + + + A brief description of the product + + + + + + + URL describing milestones for this product + + + + If there is reference URL, provide it here + + + + + + + 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 . + + +
+ 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 for more + information. + + + + +
+ +
+ 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. + + +
+ +
+ 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 . + + + For more information on versions, see . + + + For more information on milestones, see . + +
+ +
+ 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 . + + + + 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 + for examples of + product and group relationships. + + + + + 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. + + +
+ 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 + + + + + For more information on Groups outside of how they relate to products + see . + + + +
+ +
+ +
+ +
+ 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 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 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. + + + Milestone options will only appear for a Product if you turned + on the "usetargetmilestone" Param in the "Edit Parameters" screen. + + + + To create new Milestones, set Default Milestones, and set + Milestone URL: + + + + Select "Edit milestones" from the "Edit product" page. + + + + Select "Add" in the bottom right corner. + text + + + + 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". + + + + From the Edit product screen, you can enter the URL of a + page which gives information about your milestones and what + they mean. + + +
+ +
+ 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. + + +
+ 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. + + + + + +
+ +
+ About Flags + +
+ 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. + +
+
+ +
+ 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. + +
+ +
+ Two Types of Flags + + + Flags can go in two places: on an attachment, or on a bug. + + +
+ 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. + + + + + +
+ +
+ 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. + +
+ +
+ +
+ 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. + + +
+ Editing a Flag + + To edit a flag's properties, just click on the Edit + link next to the flag's description. That will take you to the same + form as described below (). + +
+ +
+ 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: + + +
+ 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. + +
+ +
+ 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. + +
+ +
+ 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. + +
+ +
+ 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. + +
+ +
+ 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. + +
+ +
+ Requestable + + New flags are, by default, requestable, meaning that they + offer users the ? option, as well as + + and -. + To remove the ? option, uncheck requestable. + +
+ +
+ 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). + +
+ +
+ 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. + +
+ +
+ 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. + +
+ +
+ 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. + +
+ +
+ 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. + +
+
+ +
+ 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. + + + + 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. + + +
+ +
+ + + +
+ +
+ 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 script. Currently keywords can not + 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 + + + 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. + + + + 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. + + + + 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". + + +
+ 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: + + + 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 + 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 + 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. + + + + + + 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 + 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. + + + + +
+ +
+ 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 . All + other attributes can be edited as described above. + +
+ +
+ Deleting Custom Fields + + + It is only possible to delete obsolete Custom Fields + if the field has never been used in the database. + To remove a field which already has content, + mark it as obsolete. + +
+
+ +
+ Legal Values + + + 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 + localconfig. 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. + + +
+ Viewing/Editing legal values + + Editing legal values requires admin 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. + + + 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. + +
+ +
+ 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 + + + 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 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. + + 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 NEW. + + + + + Once you have adjusted the values to your preference, click + "Update". + + +
+ +
+ 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. + + + + Quips are controlled by the enablequips 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. + + + + 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 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. + + + + Also, there is a delete link next to each quip, + which can be used in order to permanently delete a quip. + +
+ +
+ Groups and Group Security + + + Groups allow for separating bugs into logical divisions. + Groups are typically used to + 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 . + + + + + + + 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 . + + + + + + Group access for users. See 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 . + + + + + 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). + + + +
+ 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). + + + + 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. + + + + + 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 . + + + + +
+ +
+ 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 + ) 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 + 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 + for information on configuring Bugzilla. + + + + + + + +
+ +
+ 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 . + + + + + + 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 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 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 . + + +
+ +
+ +
+ 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 can not + 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 sanitycheck.pl. The script can also be run as + a 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. + + + + The "Sanity Check" script is no substitute for a competent database + administrator. It is only designed to check and repair basic database + problems. + + + +
+ +
+ Upgrading to New Releases + + + Upgrading Bugzilla is something we all want to do from time to time, + be it to get new features or pick up the latest security fix. How easy + it is to update depends on a few factors: + + + + + + If the new version is a revision or a new point release + + + + + How many local changes (if any) have been made + + + + +
+ Version Definitions + + + Bugzilla displays the version you are using at the top of the home + page index.cgi. It looks something like + '2.20.3', '2.22.1' or '3.0rc1'. The first number in this series is + the Major Version. This does not change very often; + Bugzilla was 1.x.x when it was first created, and went to 2.x.x + when it was re-written in perl in Sept 1998. The major version + 3.x.x, released in early 2007, is pretty far from what the 2.x.x + series looked like, both about its UI and its code. + + + + The second number in the version is called the 'minor number', and + a release that changes the minor number is called a 'point release'. + An even number in this position (2.18, 2.20, 2.22, 3.0, 3.2, etc.) + represents a stable version, while an odd number (2.19, 2.21, 2.23, etc.) + represents a development version. In the past, stable point releases + were feature-based, coming when certain enhancements had been + completed, or the Bugzilla development team felt that enough + progress had been made overall. As of version 2.18, however, + Bugzilla has moved to a time-based release schedule; current plans + are to create a stable point release every 6 months or so after + 2.18 is deployed. + + + + The third number in the Bugzilla version represents a bugfix version. + Bugfix Revisions are released only to address security vulnerabilities + and, for a limited period, bug fixes. Once enough of these + bugfixes have accumulated (or a new security vulnerability is + identified and closed), a bugfix release is made. As an + example, 2.20.3 was a bugfix release, and improved on 2.20.2. + + + + + When reading version numbers, everything separated by a point ('.') + should be read as a single number. It is not + the same as decimal. 2.22 is newer than 2.8 because minor version + 22 is greater than minor version 8. The now unsupported release 2.16.11 + was newer than 2.16.9 (because bugfix 11 is greater than bugfix 9. This is + confusing to some people who aren't used to dealing with software. + + +
+ +
+ Upgrading - Notifications + + + Bugzilla 3.0 introduces the ability to automatically notify + administrators when new releases are available, based on the + upgrade_notification parameter, see + . Administrators will see these + notifications when they access the index.cgi + page, i.e. generally when logging in. Bugzilla will check once per + day for new releases, unless the parameter is set to + disabled. If you are behind a proxy, you may have to set + the proxy_url parameter accordingly. If the proxy + requires authentication, use the + http://user:pass@proxy_url/ syntax. + +
+ +
+ Upgrading - Methods and Procedure + + There are three different ways to upgrade your installation. + + + + + + Using CVS () + + + + + Downloading a new tarball () + + + + + Applying the relevant patches () + + + + + + Each of these options has its own pros and cons; the one that's + right for you depends on how long it has been since you last + installed, the degree to which you have customized your installation, + and/or your network configuration. (Some discussion of the various + methods of updating compared with degree and methods of local + customization can be found in .) + + + + The larger the jump you are trying to make, the more difficult it + is going to be to upgrade if you have made local customizations. + Upgrading from 2.22 to 2.22.1 should be fairly painless even if + you are heavily customized, but going from 2.18 to 3.0 is going + to mean a fair bit of work re-writing your local changes to use + the new files, logic, templates, etc. If you have done no local + changes at all, however, then upgrading should be approximately + the same amount of work regardless of how long it has been since + your version was released. + + + + + Upgrading is a one-way process. You should backup your database + and current Bugzilla directory before attempting the upgrade. If + you wish to revert to the old Bugzilla version for any reason, you + will have to restore from these backups. + + + + + The examples in the following sections are written as though the + user were updating to version 2.22.1, but the procedures are the + same regardless of whether one is updating to a new point release + or simply trying to obtain a new bugfix release. Also, in the + examples the user's Bugzilla installation is found at + /var/www/html/bugzilla. If that is not the + same as the location of your Bugzilla installation, simply + substitute the proper paths where appropriate. + + +
+ Upgrading using CVS + + + Every release of Bugzilla, whether it is a point release or a bugfix, + is tagged in CVS. Also, every tarball that has been distributed since + version 2.12 has been created in such a way that it can be used with + CVS once it is unpacked. Doing so, however, requires that you are able + to access cvs-mirror.mozilla.org on port 2401, which may not be an + option or a possibility for some users, especially those behind a + highly restrictive firewall. + + + + + If you can, updating using CVS is probably the most painless + method, especially if you have a lot of local changes. + + + + + The following shows the sequence of commands needed to update a + Bugzilla installation via CVS, and a typical series of results. + + + +bash$ cd /var/www/html/bugzilla +bash$ cvs login +Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot +CVS password: ('anonymous', or just leave it blank) +bash$ cvs -q update -r BUGZILLA-2_22_1 -dP +P checksetup.pl +P collectstats.pl +P docs/rel_notes.txt +P template/en/default/list/quips.html.tmpl +(etc.) + + + + + If a line in the output from cvs update begins + with a C, then that represents a + file with local changes that CVS was unable to properly merge. You + need to resolve these conflicts manually before Bugzilla (or at + least the portion using that file) will be usable. + + +
+ +
+ Upgrading using the tarball + + + If you are unable (or unwilling) to use CVS, another option that's + always available is to obtain the latest tarball from the Download Page and + create a new Bugzilla installation from that. + + + + This sequence of commands shows how to get the tarball from the + command-line; it is also possible to download it from the site + directly in a web browser. If you go that route, save the file + to the /var/www/html + directory (or its equivalent, if you use something else) and + omit the first three lines of the example. + + + +bash$ cd /var/www/html +bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22.1.tar.gz +(Output omitted) +bash$ tar xzvf bugzilla-2.22.1.tar.gz +bugzilla-2.22.1/ +bugzilla-2.22.1/.cvsignore +(Output truncated) +bash$ cd bugzilla-2.22.1 +bash$ cp ../bugzilla/localconfig* . +bash$ cp -r ../bugzilla/data . +bash$ cd .. +bash$ mv bugzilla bugzilla.old +bash$ mv bugzilla-2.22.1 bugzilla + + + + + The cp commands both end with periods which + is a very important detail, it tells the shell that the destination + directory is the current working directory. + + + + + This upgrade method will give you a clean install of Bugzilla with the + same version as the tarball. That's fine if you don't have any local + customizations that you want to maintain, but if you do then you will + need to reapply them by hand to the appropriate files. + + + + It's worth noting that since 2.12, the Bugzilla tarballs come + CVS-ready, so if you decide at a later date that you'd rather use + CVS as an upgrade method, your code will already be set up for it. + +
+ +
+ Upgrading using patches + + + If you are doing a bugfix upgrade -- that is, one where only the + last number of the revision changes, such as from 2.22 to 2.22.1 + -- then you have the option of obtaining and applying a patch file + from the Download Page. + This file is made available by the Bugzilla + Development Team, and is a collection of all the bug fixes + and security patches that have been made since the last bugfix + release. If you are planning to upgrade via patches, it is safer + to grab this developer-made patch file than to read the patch + notes and apply all (or even just some of) the patches oneself, + as sometimes patches on bugs get changed before they get checked in. + + + + As above, this example starts with obtaining the file via the + command line. If you have already downloaded it, you can omit the + first two commands. + + + +bash$ cd /var/www/html/bugzilla +bash$ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.22-to-2.22.1.diff.gz +(Output omitted) +bash$ gunzip bugzilla-2.22-to-2.22.1.diff.gz +bash$ patch -p1 < bugzilla-2.22-to-2.22.1.diff +patching file checksetup.pl +patching file collectstats.pl +(etc.) + + + + + Be aware that upgrading from a patch file does not change the + entries in your CVS directory. + This could make it more difficult to upgrade using CVS + () in the future. + + + +
+
+ +
+ Completing Your Upgrade + + + Regardless of which upgrade method you choose, you will need to + run ./checksetup.pl before your Bugzilla + upgrade will be complete. + + + +bash$ cd bugzilla +bash$ ./checksetup.pl + + + + + The period at the beginning of the command + ./checksetup.pl is important and can not + be omitted. + + + + + If you have done a lot of local modifications, it wouldn't hurt + to run the Bugzilla Testing suite. This is not a required step, + but it isn't going to hurt anything, and might help point out + some areas that could be improved. (More information on the + test suite can be had by following this link to the appropriate + section in the Developers' + Guide.) + + +
+
+ + + + + -- cgit v1.2.3-24-g4f1b