.. _license:
License
-######
+#######
Bugzilla is `free <http://www.gnu.org/philosophy/free-sw.html>`_ and
`open source <http://opensource.org/osd>`_ software, which means (among other
administering/users
administering/categorization
administering/flags
- administering/fields
+ administering/custom-fields
+ administering/field-values
administering/workflow
administering/groups
administering/keywords
Classifications, Products, Components, Versions and Milestones
==============================================================
+Bugs in Bugzilla are classified into one of a set of admin-defined Components.
+Components are themselves each part of a single Product. Optionally, Products
+can be part of a single Classification, adding a third level to the hierarchy.
+
Classifications
###############
-Classifications tend to be used in order to group several related
+Classifications are used in order to group several related
products into one distinct entity.
+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`` classification, containing products representing units of
+technology used in multiple games, and perhaps an ``Other`` classification
+containing a few special products that represent items that are not actually
+shipping products (for example, "Website", or "Administration").
+
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.
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.
+Products usually represent real-world shipping products.
+Many of Bugzilla's settings are configurable on a per-product basis.
When creating or editing products the following options are
available:
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
+Open for bug entry
+ Deselect 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
+Enable the UNCONFIRMED status in this product
+ Select this option if you want to use the UNCONFIRMED status
+ (see :ref:`workflow`)
-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
+Default milestone
+ Select the default milestone for this product.
Version
Specify which version of the product bugs will be
- entered against.
+ entered against. XXX is this the "default version" in any sense?
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`.
+It is compulsory to create at least one :ref:`component` in a product, and
+so you will be asked for the details of that too.
+
+When editing a product you can change all of the above, and there is also a
+link to edit Group Access Controls, see :ref:`product-group-controls`.
.. _create-product:
#. Select the ``Add`` link in the bottom right.
-#. Enter the name of the product and a description. The
- Description field may contain HTML.
+#. Enter the details as outlined above.
-#. 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.
+XXX This section is pointless; if it's not obvious, we should make it more obvious :-)
.. _edit-products:
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*;
+dictate the *default assignments*;
these can be changed on bug submission, or at any later point in
a bug's life.
-.. _fields:
-
-Fields
-######
-
.. _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
+Custom Fields are fields defined by the administrator, in addition to those
+which come with Bugzilla by default. 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.
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.
-
--- /dev/null
+.. _installed-extensions:
+
+Installed Extensions
+====================
+
+Bugzilla can be enhanced using extensions (see :ref:`extensions`). If an
+extension comes with documentation in the appropriate format, and you build
+your own copy of the Bugzilla documentation using :file:`makedocs.pl`, then
+the documentation for your installed extensions will show up here.
+
+Your Bugzilla installation has the following extensions available (as of the
+last time you compiled the documentation):
+
+.. toctree::
+ :maxdepth: 1
+ :glob:
+
+ ../extensions/*
--- /dev/null
+.. _field-values:
+
+Field 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 set as the 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.
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
+using the :ref:`sanitycheck` script. XXXDoes this mean changing the name of the keyword? Is it still true?
+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.
+itself and a brief description.
##########
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.
+from the "Parameters" link, which is found on the Administration page.
+The parameters are divided into several categories,
+accessed via the menu on the left.
-.. _param-requiredsettings:
+.. _param-required-settings:
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.
+here. :guilabel:`urlbase` is always required; the other parameters should be
+set, or it must be explicitly decided not to
+set them, before the new Bugzilla installation starts to be used.
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
+ the :guilabel:`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/`.
+ssl_redirect
+ If enabled, Bugzilla will force HTTPS (SSL) connections, by
+ automatically redirecting any users who try to use a non-SSL
+ connection. Also, when this is enabled, Bugzilla will send out links
+ using sslbase in emails instead of urlbase.
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
+ the :guilabel:`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
+ Defines a path, relative to the web document root, that Bugzilla
cookies will be restricted to. For example, if the
- :command:`urlbase` is set to
+ :guilabel:`urlbase` is set to
:file:`http://www.foo.com/bugzilla/`, the
- :command:`cookiepath` should be set to
+ :guilabel:`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.
+.. _param-general:
+
+General
+=======
+
+maintainer
+ Email address of the person
+ responsible for maintaining this Bugzilla installation.
+ The address need not be that of a valid Bugzilla account.
+
+docs_urlbase
+ The URL that is the common initial leading part of all Bugzilla documentation URLs. It may be an absolute URL, or a URL relative to the urlbase parameter. Leave this empty to suppress links to the documentation. ``%lang%`` will be replaced by user's preferred language (if documentation is available in that language).
+
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
+ Use UTF-8 (Unicode) encoding for all text in Bugzilla. Installations where
+ this parameter is set to "off" should set it to "on" only
after the data has been converted from existing legacy character
- encoding to UTF-8, using the
+ encodings to UTF-8, using the
:file:`contrib/recode.pl` script.
.. note:: If you turn this parameter from "off" to "on", you must
of site maintenance or outage situations.
.. note:: Although regular log-in capability is disabled
- while :command:`shutdownhtml`
+ while :guilabel:`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
log in, and your name/password will be accepted here (but nowhere
else).
+ XXX Is this still true?
+
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
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
"stable_branch_release" the most recent release on the branch
this installation is based on.
-.. _param-admin-policies:
+.. _param-administrative-policies:
Administrative Policies
=======================
Options include whether to allow the deletion of bugs and users,
and whether to allow users to change their email address.
+allowbugdeletion
+ The pages to edit products and components can delete all associated bugs when you delete a product (or component). Since that is a pretty scary idea, you have to turn on this option before any such deletions will ever happen.
+
+allowemailchange
+ Users can change their own email address through the preferences. Note that the change is validated by emailing both addresses, so switching this option on will not let users use an invalid address.
+
+allowuserdeletion
+ The user editing pages are capable of letting you delete user accounts. Bugzilla will issue a warning in case you'd run into inconsistencies when you're about to do so, but such deletions still remain scary. So, you have to turn on this option before any such deletions will ever happen.
+
+last_visit_keep_days
+ This option controls how many days Bugzilla will remember that users have visited specific bugs.
+
.. _param-user-authentication:
User Authentication
of authentication cookies, and the regular expression used to
validate email addresses. Some parameters are highlighted below.
+auth_env_id
+ Environment variable used by external authentication system to store a unique identifier for each user. Leave it blank if there isn't one or if this method of authentication is not being used.
+
+auth_env_email
+ Environment variable used by external authentication system to store each user's email address. This is a required field for environmental authentication. Leave it blank if you are not going to use this feature.
+
+auth_env_realname
+ Environment variable used by external authentication system to store the user's real name. Leave it blank if there isn't one or if this method of authentication is not being used.
+
+user_info_class
+ Mechanism(s) to be used for gathering a user's login information. More than one may be selected. If the first one returns nothing, the second is tried, and so on. The types are:
+
+ * CGI: asks for username and password via CGI form interface.
+ * Env: info for a pre-authenticated user is passed in system environment variables.
+
+user_verify_class
+ Mechanism(s) to be used for verifying (authenticating) information gathered by user_info_class. More than one may be selected. If the first one cannot find the user, the second is tried, and so on. The types are:
+
+ * DB: Bugzilla's built-in authentication. This is the most common choice.
+ * RADIUS: RADIUS authentication using a RADIUS server. Using this method requires additional parameters to be set. Please see :ref:`param-radius` for more information.
+ * LDAP: LDAP authentication using an LDAP server. Using this method requires additional parameters to be set. Please see :ref:`param-ldap` for more information.
+
+rememberlogin
+ Controls management of session cookies.
+
+ * on - Session cookies never expire (the user has to login only once per browser).
+ * off - Session cookies last until the users session ends (the user will have to login in each new browser session).
+ * defaulton/defaultoff - Default behavior as described above, but user can choose whether Bugzilla will remember their login or not.
+
+requirelogin
+ If this option is set, all access to the system beyond the front page will require a login. No anonymous users will be permitted.
+
+webservice_email_filter
+ Filter email addresses returned by the WebService API depending on if the user is logged in or not. This works similarly to how the web UI currently filters email addresses. If requirelogin is enabled, then this parameter has no effect as users must be logged in to use Bugzilla anyway.
+
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.
+ Another popular value to put here is ^[^@]+, which means 'local usernames, no @ allowed.'
+
+emailregexpdesc
+ This description is shown to the user to explain which email addresses are allowed by the emailregexp param.
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').
+ This is a string to append to any email addresses when actually sending mail to that address. It is useful if you have changed the emailregexp param to only allow local usernames, but you want the mail to be delivered to username@my.local.hostname.
+
+createemailregexp
+ This defines the (case-insensitive) regexp to use for email addresses that are permitted to self-register using a 'New Account' feature. The default (.*) permits any account matching the emailregexp to be created. If this parameter is left blank, no users will be permitted to create their own accounts and all accounts will have to be created by an administrator.
+
+password_complexity
+ Set the complexity required for passwords. In all cases must the passwords be at least 6 characters long.
+
+ * no_constraints - No complexity required.
+ * mixed_letters - Passwords must contain at least one UPPER and one lower case letter.
+ * letters_numbers - Passwords must contain at least one UPPER and one lower case letter and a number.
+ * letters_numbers_specialchars - Passwords must contain at least one letter, a number and a special character.
+
+password_check_on_login
+ If set, Bugzilla will check that the password meets the current complexity rules and minimum length requirements when the user logs into the Bugzilla web interface. If it doesn't, the user would not be able to log in, and will receive a message to reset their password.
.. _param-attachments:
regarding attachments to bugs. For example, control size limitations
and whether to allow pointing to external files via a URI.
+allow_attachment_display
+ If this option is on, users will be able to view attachments from their browser, if their browser supports the attachment's MIME type. If this option is off, users are forced to download attachments, even if the browser is able to display them.
+
+ If you do not trust your users (e.g. if your Bugzilla is public), you should either leave this option off, or configure and set the :guilabel:`attachment_base` parameter (see below). Untrusted users may upload attachments that could be potentially damaging if viewed directly in the browser.
+
+attachment_base
+ When the :guilabel:`allow_attachment_display` parameter is on, it is possible for a malicious attachment to steal your cookies or perform an attack on Bugzilla using your credentials.
+
+ If you would like additional security on attachments to avoid this, set this parameter to an alternate URL for your Bugzilla that is not the same as :guilabel:`urlbase` or :guilabel:`sslbase`. That is, a different domain name that resolves to this exact same Bugzilla installation.
+
+ Note that if you have set the :guilabel:`cookiedomain` parameter, you should set :guilabel:`attachment_base` to use a domain that would not be matched by :guilabel:`cookiedomain`.
+
+ For added security, you can insert ``%bugid%`` into the URL, which will be replaced with the ID of the current bug that the attachment is on, when you access an attachment. This will limit attachments to accessing only other attachments on the same bug. Remember, though, that all those possible domain names (such as 1234.your.domain.com) must point to this same Bugzilla instance.
+
+ XXX So this requires wildcard DNS? We should explain a bit about what is needed here.
+
+allow_attachment_deletion
+ If this option is on, administrators will be able to delete the content of attachments.
+
+ XXX Does the attachment itself still exist, it's just empty?
+
+maxattachmentsize
+ The maximum size (in kilobytes) of attachments to be stored in the database. If a file larger than this size is attached to a bug, Bugzilla will look at the maxlocalattachment parameter to determine if the file can be stored locally on the web server. If the file size exceeds both limits, then the attachment is rejected. Settings both parameters to 0 will prevent attaching files to bugs.
+
+ XXX Talk about MySQL max_allowed_packet
+
+maxlocalattachment
+ The maximum size (in megabytes) of attachments to be stored locally on the web server. If set to a value lower than the maxattachmentsize parameter, attachments will never be kept on the local filesystem.
+
+ XXX When should people use this feature?
+
.. _param-bug-change-policies:
Bug Change Policies
target milestone. Also allows for configuration of what changes
should require the user to make a comment, described below.
+duplicate_or_move_bug_status
+ When a bug is marked as a duplicate of another one, use this bug status.
+
+letsubmitterchoosepriority
+ If this is on, then people submitting bugs can choose an initial priority for that bug. If off, then all bugs initially have the default priority selected here.
+
+letsubmitterchoosemilestone
+ If this is on, then people submitting bugs can choose the Target Milestone for that bug. If off, then all bugs initially have the default milestone for the product being filed in.
+
+musthavemilestoneonaccept
+ If you are using Target Milestone, do you want to require that the milestone be set in order for a user to set a bug's status to IN_PROGRESS?
+
commenton*
All these fields allow you to dictate what changes can pass
without comment, and which must have a comment from the
certain fields are used. For example, choose whether to use the
"target milestone" field or the "status whiteboard" field.
+useclassification
+ If this is on, Bugzilla will associate each product with a specific classification. But you must have 'editclassification' permissions enabled in order to edit classifications.
+
+usetargetmilestone
+ Do you wish to use the Target Milestone 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
easily-searchable field for indexing some bugs that have some trait
in common.
-.. _param-bugmoving:
+use_see_also
+ Do you wish to use the See Also field? It allows you mark bugs in other bug tracker installations as being related. Disabling this field prevents addition of new relationships, but existing ones will continue to appear.
-Bug Moving
-==========
+defaultpriority
+ This is the priority that newly entered bugs are set to.
+
+defaultseverity
+ This is the severity that newly entered bugs are set to.
+
+defaultplatform
+ This is the platform that is preselected on the bug entry form.
+ You can leave this empty; Bugzilla will then use the platform that the browser is running on as the default.
-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.
+defaultopsys
+ This is the operating system that is preselected on the bug entry form.
+ You can leave this empty; Bugzilla will then use the operating system that the browser reports to be running on as the default.
+
+collapsed_comment_tags
+ A comma separated list of tags which, when applied to comments, will cause them to be collapsed by default.
.. _param-dependency-graphs:
-Dependency Graphs
-=================
+Graphs
+======
-This page has one parameter that sets the location of a Web Dot
+This page has a 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.
+webdotbase
+ It is possible to show graphs of dependent bugs. You may set this parameter to any of the following:
+
+ * A complete file path to :command:`dot` (part of GraphViz) will generate the graphs locally.
+ * A URL prefix pointing to an installation of the webdot package will generate the graphs remotely.
+ * A blank value will disable dependency graphing.
+
+ The default value is a publicly-accessible webdot server. If you change this value, make certain that the webdot server can read files from your webdot directory. On Apache you do this by editing the .htaccess file, for other systems the needed measures may vary. You can run checksetup.pl to recreate the .htaccess file if it has been lost.
+
+font_file
+ You can specify the full path to a TrueType font file which will be used to display text (labels, legends, ...) in charts and graphical reports. To support as many languages as possible, we recommend to specify a TrueType font such as Unifont which supports all printable characters in the Basic Multilingual Plane. If you leave this parameter empty, a default font will be used, but its support is limited to English characters only and so other characters will be displayed incorrectly.
+
.. _param-group-security:
Group Security
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`
+: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.
+ used for querying bugs. XXX This is spectacularly unclear.
+
+chartgroup
+ The name of the group of users who can use the 'New Charts' feature. Administrators should ensure that the public categories and series definitions do not divulge confidential information before enabling this for an untrusted population. If left blank, no users will be able to use New Charts.
+
+insidergroup
+ The name of the group of users who can see/change private comments and attachments.
+
+timetrackinggroup
+ The name of the group of users who can see/change time tracking information.
+
+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`.
+
+comment_taggers_group
+ The name of the group of users who can tag comment. Setting this to empty disables comment tagging.
+
+debug_group
+ The name of the group of users who can view the actual SQL query generated when viewing bug lists and reports. Do not expose this information to untrusted users.
usevisibilitygroups
If selected, user visibility will be restricted to members of
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`.
+or_groups
+ Define the visibility of a bug which is in multiple groups. If this is on (recommended), a user only needs to be a member of one of the bug's groups in order to view it. If it is off, a user needs to be a member of all the bug's groups. Note that in either case, if the user has a role on the bug (e.g. reporter) that may also affect their permissions.
-.. _bzldap:
+.. _param-ldap:
-LDAP Authentication
-===================
+LDAP
+====
LDAP authentication is a module for Bugzilla's plugin
authentication architecture. This page contains all the parameters
Parameters required to use LDAP Authentication:
-user_verify_class
+user_verify_class (in the Authentication section)
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
+ :file:`data/params` and set :guilabel:`user_verify_class` to
``DB``.
LDAPserver
``ldaps://ldap.company.com`` or LDAP over a UNIX
domain socket ``ldapi://%2fvar%2flib%2fldap_sock``.
-LDAPbinddn \[Optional]
+LDAPstarttls
+ Whether to require encrypted communication once a normal LDAP connection is achieved with the server.
+
+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 set the :guilabel:`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
+ 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
+ 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
+ The name of the
attribute which contains the email address your users will enter
into the Bugzilla login boxes.
Ex. ``mail``
-.. _bzradius:
+LDAPfilter
+ LDAP filter to AND with the LDAPuidattribute for filtering the list of valid users.
+
+.. _param-radius:
-RADIUS Authentication
-=====================
+RADIUS
+======
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.
+ authentication as well. See :ref:`param-ldap` for details.
Parameters required to use RADIUS Authentication:
-user_verify_class
+user_verify_class (in the Authentication section)
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
``DB``.
RADIUS_server
- This parameter should be set to the name (and optionally the
+ The name (and optionally the
port) of your RADIUS server.
RADIUS_secret
- This parameter should be set to the RADIUS server's secret.
+ The RADIUS server's secret.
+
+RADIUS_NAS_IP
+ The NAS-IP-Address attribute to be used when exchanging data with your RADIUS server. If unspecified, 127.0.0.1 will be used.
RADIUS_email_suffix
Bugzilla needs an e-mail address for each user account.
servers require mail to be from a valid email address, therefore
it is recommended to choose a valid email address here.
+use_mailer_queue
+ In a large Bugzilla installation, updating bugs can be very slow, because Bugzilla sends all email at once. If you enable this parameter, Bugzilla will queue all mail and then send it in the background. This requires that you have installed certain Perl modules (as listed by :file:`checksetup.pl` for this feature), and that you are running the :file:`jobqueue.pl` daemon (otherwise your mail won't get sent). This affects all mail sent by Bugzilla, not just bug updates.
+
smtpserver
- This is the SMTP server address, if the ``mail_delivery_method``
+ The SMTP server address, if the :guilabel:`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.
+ number if a non-default port is needed.
smtp_username
Username to use for SASL authentication to the SMTP server. Leave
smtp_password
Password to use for SASL authentication to the SMTP server. This
- parameter will be ignored if the ``smtp_username``
+ parameter will be ignored if the :guilabel:`smtp_username`
parameter is left empty.
smtp_ssl
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).
+ instructions, or set this value to "0" (never whine). XXXlink
-globalwatcher
+globalwatchers
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
+ receive notification each time any new bug in entered, or when
+ any existing bug changes, subject to the normal groupset
permissions. It may be useful for sending notifications to a
mailing-list, for instance.
to a CVS tree. LXR is a tool that can cross reference and index source
code.
+XXX Does anyone use this stuff any more?
+
+cvsroot
+ The CVS root that most users of your system will be using for 'cvs diff'. Used in Patch Viewer ('Diff' option on patches) to figure out where patches are rooted even if users did the 'cvs diff' from different places in the directory structure. (NOTE: if your CVS repository is remote and requires a password, you must either ensure the Bugzilla user has done a 'cvs login' or specify the password as part of the CVS root.) Leave this blank if you have no CVS repository.
+
+cvsroot_get
+ The CVS root Bugzilla will be using to get patches from. Some installations may want to mirror their CVS repository on the Bugzilla server or even have it on that same server, and thus the repository can be the local file system (and much faster). Make this the same as cvsroot if you don't understand what this is (if cvsroot is blank, make this blank too).
+
+bonsai_url
+ The URL to a Bonsai server containing information about your CVS repository. Patch Viewer will use this information to create links to bonsai's blame for each section of a patch (it will append '/cvsblame.cgi?...' to this url). Leave this blank if you don't understand what this is.
+
+lxr_url
+ The URL to an LXR server that indexes your CVS repository. Patch Viewer will use this information to create links to LXR for each file in a patch. Leave this blank if you don't understand what this is.
+
+lxr_root
+ Some LXR installations do not index the CVS repository from the root -- Mozilla's, for example, starts indexing under mozilla/. This means URLs are relative to that extra path under the root. Enter this if you have a similar situation. Leave it blank if you don't know what this is.
+
.. _param-querydefaults:
Query Defaults
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.
+quip_list_entry_control
+ Controls how easily users can add entries to the quip list.
+
+ * open - Users may freely add to the quip list, and their entries will immediately be available for viewing.
+ * moderated - quips can be entered, but need to be approved by a moderator before they will be shown.
+ * closed - no new additions to the quips list are allowed.
+
+mybugstemplate
+ This is the URL to use to bring up a simple 'all of my bugs' list for a user. %userid% will get replaced with the login name of a user. Special characters must be URL-encoded.
+
+defaultquery
+ This is the default query that initially comes up when you access the advanced query page. It's in URL parameter format.
+
+search_allow_no_criteria
+ When turned off, a query must have some criteria specified to limit the number of bugs returned to the user. When turned on, a user is allowed to run a query with no criteria and get all bugs in the entire installation that they can see. Turning this parameter on is not recommended on large installations.
+
+default_search_limit
+ By default, Bugzilla limits searches done in the web interface to returning only this many results, for performance reasons. (This only affects the HTML format of search results--CSV, XML, and other formats are exempted.) Users can click a link on the search result page to see all the results.
+
+ Usually you should not have to change this - the default value should be acceptable for most installations.
+
+max_search_results
+ The maximum number of bugs that a search can ever return. Tabular and graphical reports are exempted from this limit, however.
+
+
+
.. _param-shadowdatabase:
Shadow Database
Therefore, the limitations the Shadow Database feature was designed
to workaround no longer exist.
+XXX Do we need to document it, then? Or even still support it?
+
+.. _admin-memcached:
+
+Memcached
+=========
+
+memcached_servers
+ If this option is set, Bugzilla will integrate with XXXlink Memcached. Specify one of more server, separated by spaces, using hostname:port notation (for example: 127.0.0.1:11211).
+
+memcached_namespace
+ Specify a string to prefix to each key on Memcached.
+
.. _admin-usermatching:
User Matching
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
+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'.
+usemenuforusers
+ If this option is set, Bugzilla will offer you a list to select from (instead of a text entry field) where a user needs to be selected. This option should not be enabled on sites where there are a large number of users.
+
+ajax_user_autocompletion
+ If this option is set, typing characters in a certain user fields will display a list of matches that can be selected from. It is recommended to only turn this on if you are using mod_perl, because otherwise the response will be irritatingly slow.
+
+maxusermatches
+ Provide no more than this many matches when a user is searched for.
+ If set to '1', no users will be displayed on ambiguous matches. This is useful for user privacy purposes.
+ A value of zero means no limit.
+
+confirmuniqueusermatch
+ Whether a confirmation screen should be displayed when only one user matches a search entry.
+
+.. _admin-advanced:
+
+Advanced
+========
+
+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://bugzilla.example.com/``, setting this to
+ ``.example.com/`` will also allow
+ ``attachments.example.com/`` to access Bugzilla cookies.
+
+inbound_proxies
+ When inbound traffic to Bugzilla goes through a proxy, Bugzilla thinks that the IP address of the proxy is the IP address of every single user. If you enter a comma-separated list of IPs in this parameter, then Bugzilla will trust any X-Forwarded-For header sent from those IPs, and use the value of that header as the end user's IP address.
+
+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
+ :guilabel:`upgrade_notification` parameter. If the
+ proxy requires authentication, use the syntax:
+ :file:`http://user:pass@proxy_url/`.
+
+strict_transport_security
+ Enables the sending of the Strict-Transport-Security header along with HTTP responses on SSL connections. This adds greater security to your SSL connections by forcing the browser to always access your domain over SSL and never accept an invalid certificate. However, it should only be used if you have the :guilabel:`ssl_redirect` parameter turned on, Bugzilla is the only thing running on its domain (i.e., your urlbase is something like http://bugzilla.example.com/), and you never plan to stop supporting SSL.
+
+ * off - Don't send the Strict-Transport-Security header with requests.
+ * this_domain_only - Send the Strict-Transport-Security header with all requests, but only support it for the current domain.
+ * include_subdomains - Send the Strict-Transport-Security header along with the includeSubDomains flag, which will apply the security change to all subdomains. This is especially useful when combined with an :guilabel:`attachment_base` that exists as (a) subdomain(s) under the main Bugzilla domain.
Default Preferences
###################
+
+Each user of Bugzilla can set certain preferences about how they want
+Bugzilla to behave. Here, you can say whether or not each of the possible
+preferences is available to the user and, if it is, what the default value
+is.
+
.. _defaultuser:
-Creating the Default User
-=========================
+Creating Admin Users
+====================
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.
-
-.. note:: 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).
+password for the first admin user. If for some reason you delete
+all the admin users, re-running checksetup.pl will again prompt
+you for a username and password and make a new admin.
-.. _manageusers:
-
-Managing Other Users
-====================
+If you wish to add more administrative users, add them to the "admin" group.
.. _user-account-search:
-Searching for existing users
-----------------------------
+Searching For Users
+===================
If you have ``editusers`` privileges or if you are allowed
-to grant privileges for some groups, the ``Users`` link
+to grant privileges for some groups, the :guilabel:`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).
+of the email address if the :guilabel:`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),
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:
created. The user must still have the ``editbugs``
privilege to edit bugs in these products.
+.. _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:
+
+Administrator Registration
+--------------------------
+
+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.
+
.. _user-account-deletion:
Deleting Users
---------------
+==============
If the ``allowuserdeletion`` parameter is turned on, see
:ref:`parameters`, then you can also delete user accounts.
.. _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
+++ /dev/null
-.. _versions-and-milestones:
-
-Versions and Milestones
-#######################
-
Whining
#######
-XXX Link to the bit of the docs about setting up the cron job
+Whining is a feature in Bugzilla that can regularly annoy users at
+specified times. Using this feature, users can execute saved searches
+at specific times (i.e. the 15th of the month at midnight) or at
+regular intervals (i.e. every 15 minutes on Sundays). The results of the
+searches are sent to the user, either as a single email or as one email
+per bug, along with some descriptive text.
-XXX Explain about admin interface to whines here
+.. warning:: Throughout this section it will be assumed that all users are members
+ of the bz_canusewhines group, membership in which is required in order
+ to use the Whining system. You can easily make all users members of
+ the bz_canusewhines group by setting the User RegExp to ".*" (without
+ the quotes).
+
+ Also worth noting is the bz_canusewhineatothers group. Members of this
+ group can create whines for any user or group in Bugzilla using a
+ extended form of the whining interface. Features only available to
+ members of the bz_canusewhineatothers group will be noted in the
+ appropriate places.
+
+.. note:: For whining to work, a special Perl script must be executed at regular
+ intervals. More information on this is available in :ref:`installation-whining`.
+
+.. note:: This section does not cover the whineatnews.pl script.
+ See :ref:`installation-whining-cron` for more information on
+ The Whining Cron.
+
+.. _whining-overview:
+
+The Event
+=========
+
+The whining system defines an "Event" as one or more queries being
+executed at regular intervals, with the results of said queries (if
+there are any) being emailed to the user. Events are created by
+clicking on the "Add new event" button.
+
+Once a new event is created, the first thing to set is the "Email
+subject line". The contents of this field will be used in the subject
+line of every email generated by this event. In addition to setting a
+subject, space is provided to enter some descriptive text that will be
+included at the top of each message (to help you in understanding why
+you received the email in the first place).
+
+The next step is to specify when the Event is to be run (the Schedule)
+and what searches are to be performed (the Searches).
+
+.. _whining-schedule:
+
+Whining Schedule
+================
+
+Each whining event is associated with zero or more schedules. A
+schedule is used to specify when the search (specified below) is to be
+run. A new event starts out with no schedules (which means it will
+never run, as it is not scheduled to run). To add a schedule, press
+the "Add a new schedule" button.
+
+Each schedule includes an interval, which you use to tell Bugzilla
+when the event should be run. An event can be run on certain days of
+the week, certain days of the month, during weekdays (defined as
+Monday through Friday), or every day.
+
+.. warning:: Be careful if you set your event to run on the 29th, 30th, or 31st of
+ the month, as your event may not run exactly when expected. If you
+ want your event to run on the last day of the month, select "Last day
+ of the month" as the interval.
+
+Once you have specified the day(s) on which the event is to be run, you
+should now specify the time at which the event is to be run. You can
+have the event run at a certain hour on the specified day(s), or
+every hour, half-hour, or quarter-hour on the specified day(s).
+
+If a single schedule does not execute an event as many times as you
+would want, you can create another schedule for the same event. For
+example, if you want to run an event on days whose numbers are
+divisible by seven, you would need to add four schedules to the event,
+setting the schedules to run on the 7th, 14th, 21st, and 28th (one day
+per schedule) at whatever time (or times) you choose.
+
+.. note:: If you are a member of the bz_canusewhineatothers group, then you
+ will be presented with another option: "Mail to". Using this you
+ can control who will receive the emails generated by this event. You
+ can choose to send the emails to a single user (identified by email
+ address) or a single group (identified by group name). To send to
+ multiple users or groups, create a new schedule for each additional
+ user/group.
+
+.. _whining-query:
+
+Whining Searches
+================
+
+Each whining event is associated with zero or more searches. A search
+is any saved search to be run as part of the specified schedule (see
+above). You start out without any searches associated with the event
+(which means that the event will not run, as there will never be any
+results to return). To add a search, press the "Add a search" button.
+
+The first field to examine in your newly added search is the Sort field.
+Searches are run, and results included, in the order specified by the
+Sort field. Searches with smaller Sort values will run before searches
+with bigger Sort values.
+
+The next field to examine is the Search field. This is where you
+choose the actual search that is to be run. Instead of defining search
+parameters here, you are asked to choose from the list of saved
+searches (the same list that appears at the bottom of every Bugzilla
+page). You are only allowed to choose from searches that you have
+saved yourself (the default saved search, "My Bugs", is not a valid
+choice). If you do not have any saved searches, you can take this
+opportunity to create one (see :ref:`list`).
+
+.. note:: When running searches, the whining system acts as if you are the user
+ executing the search. This means that the whining system will ignore
+ bugs that match your search, but that you cannot access.
+
+Once you have chosen the saved search to be executed, give the search a
+descriptive title. This title will appear in the email, above the
+results of the search. If you choose "One message per bug", the search
+title will appear at the top of each email that contains a bug matching
+your search.
+
+Finally, decide if the results of the search should be sent in a single
+email, or if each bug should appear in its own email.
+
+.. warning:: Think carefully before checking the "One message per bug" box. If
+ you create a search that matches thousands of bugs, you will receive
+ thousands of emails!
+
+Saving Your Changes
+===================
+
+Once you have defined at least one schedule, and created at least one
+search, go ahead and "Update/Commit". This will save your Event and make
+it available for immediate execution.
+
+.. note:: If you ever feel like deleting your event, you may do so using the
+ "Remove Event" button in the upper-right corner of each Event. You
+ can also modify an existing event, so long as you "Update/Commit"
+ after completing your modifications.
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
+The bug status workflow - which statuses are valid transitions from which
+other statuses - can be customized.
+
+You need to begin by defining the statuses and resolutions you want to use
+(see :ref:`field-values`). By convention, these are capitalized.
+
+Only one bug status, UNCONFIRMED, can never be renamed nor deleted. However,
+it can be disabled entirely on a per-product basis (see :ref:`categorization`).
+One other status may be
+marked as undeletable, because it's the value of the
+:guilabel:`duplicate_or_move_bug_status` parameter. To make it deletable,
+simply set the value of that parameter to a different status.
+
+Aside from the empty value, two resolutions, DUPLICATE and FIXED, cannot be
+renamed or deleted. (FIXED could be if we fixed
+`bug 1007605 <https://bugzilla.mozilla.org/show_bug.cgi?id=1007605>`_.)
+
+Once you have defined your statuses, you can configure the workflow of
+how a bug moves between them. The workflow configuration
+page displays all existing bug statuses twice, first on the left for the
+starting status and on the top for the target status in the transition.
+If the checkbox is checked, then the transition from the left to the top
+status is legal; if it's unchecked, that transition is forbidden.
+
+The status used as the :guilabel:`duplicate_or_move_bug_status` parameter
+(normally RESOLVED or its equivalent) is required to be a legal transition
+from every other bug status, and so this is enforced on the page.
+
+The "View Comments Required on Status Transitions" link below the table
lets you set which transitions require a comment from the user.
#html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
-#html_show_copyright = True
+html_show_copyright = False
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
+++ /dev/null
-Extensions
-==========
-
-Your Bugzilla installation has the following extensions available (as of the
-last time you compiled the documentation):
-
-.. toctree::
- :maxdepth: 1
- :glob:
-
- extensions/*
+:orphan:
+
.. _email:
Email
+:orphan:
+
.. _http-iis:
Microsoft IIS
oracle
sqlite
-.. _config-webserver:
-
.. _localconfig:
localconfig
Mac OS X
########
-`https://wiki.mozilla.org/Bugzilla:Mac_OS_X_installation`_ is what we have
+`<https://wiki.mozilla.org/Bugzilla:Mac_OS_X_installation>`_ is what we have
right now...
*Mac OS X*
Whining
-------
-As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy
+Users can configure Bugzilla to regularly annoy
them at regular intervals, by having Bugzilla execute saved searches
at certain times and emailing the results to the user. This is known
as "Whining". The process of configuring Whining is described
+:orphan:
+
Download Code from Git
======================
+:orphan:
+
The procedure to switch to Git is as follows. The idea is to switch version
control systems without changing the exact version of Bugzilla you are using,
to minimise the risk of conflict or problems. Any major upgrade can then
+:orphan:
+
Save Any Local Customizations
=============================
+++ /dev/null
-.. _upgrading-with-a-tarball:
-
-Upgrading with a Tarball
-########################
-
-If you are unable (or unwilling) to use Bzr, another option that's
-always available is to obtain the latest tarball from the `Download Page <http://www.bugzilla.org/download/>`_ 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 :file:`/var/www/html`
-directory (or its equivalent, if you use something else) and
-omit the first three lines of the example.
-
-::
-
- $ cd /var/www/html
- $ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2.1.tar.gz
- ...
- $ tar xzvf bugzilla-4.2.1.tar.gz
- bugzilla-4.2.1/
- bugzilla-4.2.1/colchange.cgi
- ...
- $ cd bugzilla-4.2.1
- $ cp ../bugzilla/localconfig* .
- $ cp -r ../bugzilla/data .
- $ cd ..
- $ mv bugzilla bugzilla.old
- $ mv bugzilla-4.2.1 bugzilla
-
-.. warning:: The :command:`cp` commands both end with periods which
- is a very important detail--it means that the destination
- directory is the current working directory.
-
-.. warning:: If you have some extensions installed, you will have to copy them
- to the new bugzilla directory too. Extensions are located in :file:`bugzilla/extensions/`.
- Only copy those you
- installed, not those managed by the Bugzilla team.
-
-This upgrade method will give you a clean install of Bugzilla.
-That's fine if you don't have any local customizations that you
-want to maintain. If you do have customizations, then you will
-need to reapply them by hand to the appropriate files.
+++ /dev/null
-The procedure to switch to Git is as follows. The idea is to switch version
-control systems without changing the exact version of Bugzilla you are using,
-to minimise the risk of conflict or problems. Any major upgrade can then
-happen as a separate step.
-
-Update Bugzilla To The Latest Point Release
-===========================================
-
-It is recommended that you switch while using the latest
-point release for your major version. You can update to the latest point
-release using bzr.
-
-First, you need to find what version of Bugzilla you are using. It should be
-in the top right corner of the front page but, if not, open the file
-:file:`Bugzilla/Constants.pm` in your Bugzilla directory and search for
-:code:`BUGZILLA_VERSION`.
-
-Then, you need to find out what the latest point release for that major
-version of Bugzilla is. The
-`Bugzilla download page <http://www.bugzilla.org/download/>`_
-should tell you that for supported versions. For versions out of support, here
-is a list of the final point releases:
-
-* 3.6.13
-* 3.4.14
-* 3.2.10
-* 3.0.11
-
-XXX Do we need below here? Are these versions in bzr? Will anyone be running
-them from a bzr install?
-
-* 2.22.7
-* 2.20.7
-* 2.18.6
-* 2.16.11
-* 2.14.5
-
-If you are not currently running the latest point release, you should use the
-following update command:
-
-|updatecommand|
-
-Where you replace $VERSION by the version number of the latest point release.
-Then run checksetup to upgrade your database:
-
-:command:`./checksetup.pl`
-
-You should then test your Bugzilla carefully, or just use it for a day or two,
-to make sure it's all still working fine.
-
-Download Code from Git
-======================
-
-Download a copy of your current version of Bugzilla from the git repository
-into a separate directory alongside your existing Bugzilla installation
-(which we will assume is in a directory called :file:`bugzilla`).
-
-You will need a copy of the git program. All Linux installations have it;
-search your package manager for "git". On Windows or Mac OS X, you can
-`download the official build <http://www.git-scm.com/downloads>`_.
-
-Once git is installed, run these commands to pull a copy of Bugzilla:
-
-:command:`git clone https://git.mozilla.org/bugzilla/bugzilla bugzilla-new`
-
-:command:`cd bugzilla-new`
-
-:command:`git checkout $VERSION`
-
-Replace $VERSION with the two-digit version number of your current Bugzilla, e.g.
-4.2. These command will automatically change your version to the latest
-point release of version $VERSION.
-
-Save Any Local Customizations
-=============================
-
-Go into your original Bugzilla directory and run this command:
-
-|diffcommand|
-
-If you have made customizations to your Bugzilla, and you made them by
-changing the Bugzilla code itself (rather than using the Extension system),
-then :file:`patch.diff` will have non-zero size. You will want to keep a copy
-of those changes by keeping a copy of this file. If the file has zero size,
-you haven't made any local customizations.
-
-Shut Down Bugzilla
-==================
-
-At this point, you should shut down Bugzilla to make sure nothing changes
-while you make the switch. Go into the administrative interface and put an
-appropriate message into the :guilabel:`shutdownhtml` parameter, which is in the
-"General" section of the administration parameters. As the name implies, HTML
-is allowed.
-
-This would be a good time to make :ref:`backups`. We shouldn't be affecting
-the database, but you can't be too careful.
-
-Copy Across Data and Modules
-============================
-
-Copy the contents of the following directories from your current installation
-of Bugzilla into the corresponding directory in :file:`bugzilla-new/`:
-
-.. code-block:: none
-
- lib/
- data/
-
-You also need to copy an extensions you have written or installed, which are
-in the :file:`extensions/` directory. In the Bugzilla directory, run this
-command:
-
-|extstatuscommand|
-
-If any directories are listed as "unknown", copy those across.
-
-Then, copy the following file from your current installation of Bugzilla
-into the corresponding place in :file:`bugzilla-new/`:
-
-.. code-block:: none
-
- localconfig
-
-This file contains your database password and access details. Because your
-two versions of Bugzilla are the same, this should all work fine.
-
-Reapply Local Customizations
-============================
-
-If your :file:`patch.diff` file was zero sized, you can
-jump to the next step. Otherwise, you have to apply the patch to your new
-installation. If you are on Windows and you don’t have the :command:`patch`
-program, you can download it from
-`GNUWin <http://gnuwin32.sourceforge.net/packages/patch.htm>`_. Once
-downloaded, you must copy patch.exe into the Windows directory.
-
-Copy :file:`patch.diff` into the :file:`bugzilla-new` directory and then do:
-
-:command:`patch -p0 --dry-run < patch.diff`
-
-The patch should apply cleanly because you have exactly the same version of
-Bugzilla in both directories. If it does, remove the :command:`--dry-run` and
-rerun the command to apply it for real. If it does not apply cleanly, it is
-likely that you have managed to get a Bugzilla version mismatch between the
-two directories.
-
-Swap The New Version In
-=======================
-
-Now we swap the directories over, and run checksetup.pl to confirm that all
-is well. From the directory containing the :file:`bugzilla` and
-:file:`bugzilla-git` directories, run:
-
-:command:`mv bugzilla bugzilla-old`
-
-:command:`mv bugzilla-new bugzilla`
-
-:command:`cd bugzilla`
-
-:command:`./checksetup.pl`
-
-Running :file:`checksetup.pl` should not result in any changes to your database at
-the end of the run. If it does, then it's most likely that the two versions
-of Bugzilla you have are not, in fact, the same.
-
-Re-enable Bugzilla
-==================
-
-Go into the administrative interface and clear the contents of the
-:guilabel:`shutdownhtml` parameter.
-
-Test Bugzilla
-=============
-
-Use your Bugzilla for several days to check that the switch has had no
-detrimental effects. Then, if necessary, follow the instructions in
-:ref:`upgrading-with-git` to upgrade to the latest version of Bugzilla.
-
-Rolling Back
-============
-
-If something goes wrong at any stage of the switching process (e.g. your
-patch doesn't apply, or checksetup doesn't complete), you can always just
-switch the directories back (if you've got that far) and re-enable Bugzilla
-(if you disabled it) and then seek help. Even if you have re-enabled Bugzilla,
-and find a problem a little while down the road, you are still using the same
-version so there would be few side effects to switching the directories back
-a day or three later.
==============
.. toctree::
- :maxdepth: 2
+ :maxdepth: 1
using/creating-an-account
using/filing
using/understanding
using/editing
using/finding
+ using/reports-and-charts
using/tips
using/preferences
-
-
-.. _using-intro:
-
-Introduction
-############
-
-This section contains information for end-users of Bugzilla. There
-is a machine with many Bugzilla test installations, called
-`Landfill <http://landfill.bugzilla.org/>`_, which you are
-welcome to play with (if it's up). However, not all of the Bugzilla
-installations there will necessarily have all Bugzilla features enabled,
-and different installations run different versions, so some things may not
-quite work as this document describes.
-
-Frequently Asked Questions (FAQ) are available and answered on
-`wiki.mozilla.org <http://wiki.mozilla.org/Bugzilla:FAQ>`_.
-They may cover some questions you have which are left unanswered.
-
-.. _myaccount:
-
-Create a Bugzilla Account
-#########################
-
-If you want to use Bugzilla, first you need to create an account.
-Consult with the administrator responsible for your installation of
-Bugzilla for the URL you should use to access it. If you're
-test-driving Bugzilla, use an installation on
-`Landfill <http://landfill.bugzilla.org/>`_.
-
-#. On the home page :file:`index.cgi`, click the
- ``Open a new Bugzilla account`` link, or the
- ``New Account`` link available in the footer of pages.
- Now enter your email address, then click the ``Send``
- button.
-
- .. note:: If none of these links is available, this means that the
- administrator of the installation has disabled self-registration.
- This means that only an administrator can create accounts
- for other users. One reason could be that this installation is
- private.
-
- .. note:: Also, if only some users are allowed to create an account on
- the installation, you may see these links but your registration
- may fail if your email address doesn't match the ones accepted
- by the installation. This is another way to restrict who can
- access and edit bugs in this installation.
-
-#. Within moments, and if your registration is accepted, you should
- receive an email to the address you provided, which contains your
- login name (generally the same as the email address), and two URLs
- with a token (a random string generated by the installation) to
- confirm, respectively cancel, your registration. This is a way to
- prevent users from abusing the generation of user accounts, for
- instance by entering inexistent email addresses, or email addresses
- which do not belong to them.
-
-#. By default, you have 3 days to confirm your registration. Past this
- timeframe, the token is invalidated and the registration is
- automatically canceled. You can also cancel this registration sooner
- by using the appropriate URL in the email you got.
-
-#. If you confirm your registration, Bugzilla will ask you your real name
- (optional, but recommended) and your password, which must be between
- 3 and 16 characters long.
-
-#. Now all you need to do is to click the ``Log In``
- link in the footer at the bottom of the page in your browser,
- enter your email address and password you just chose into the
- login form, and click the ``Log in`` button.
-
-You are now logged in. Bugzilla uses cookies to remember you are
-logged in so, unless you have cookies disabled or your IP address changes,
-you should not have to log in again during your session.
-
-.. _bug_page:
-
-Anatomy of a Bug
-################
-
-The core of Bugzilla is the screen which displays a particular
-bug. It's a good place to explain some Bugzilla concepts.
-`Bug 1 on Landfill <http://landfill.bugzilla.org/bugzilla-tip/show_bug.cgi?id=1>`_
-is a good example. Note that the labels for most fields are hyperlinks;
-clicking them will take you to context-sensitive help on that
-particular field. Fields marked * may not be present on every
-installation of Bugzilla.
-
-#. *Product and Component*:
- Bugs are divided up by Product and Component, with a Product
- having one or more Components in it. For example,
- bugzilla.mozilla.org's "Bugzilla" Product is composed of several
- Components:
-
- Administration:
- Administration of a Bugzilla installation.
- Bugzilla-General:
- Anything that doesn't fit in the other components, or spans
- multiple components.
- Creating/Changing Bugs:
- Creating, changing, and viewing bugs.
- Documentation:
- The Bugzilla documentation, including The Bugzilla Guide.
- Email:
- Anything to do with email sent by Bugzilla.
- Installation:
- The installation process of Bugzilla.
- Query/Buglist:
- Anything to do with searching for bugs and viewing the
- buglists.
- Reporting/Charting:
- Getting reports from Bugzilla.
- User Accounts:
- Anything about managing a user account from the user's perspective.
- Saved queries, creating accounts, changing passwords, logging in,
- etc.
- User Interface:
- General issues having to do with the user interface cosmetics (not
- functionality) including cosmetic issues, HTML templates,
- etc.
-
-#. *Status and Resolution:*
- These define exactly what state the bug is in - from not even
- being confirmed as a bug, through to being fixed and the fix
- confirmed by Quality Assurance. The different possible values for
- Status and Resolution on your installation should be documented in the
- context-sensitive help for those items.
-
-#. *Assigned To:*
- The person responsible for fixing the bug.
-
-#. *\*QA Contact:*
- The person responsible for quality assurance on this bug.
-
-#. *\*URL:*
- A URL associated with the bug, if any.
-
-#. *Summary:*
- A one-sentence summary of the problem.
-
-#. *\*Status Whiteboard:*
- (a.k.a. Whiteboard) A free-form text area for adding short notes
- and tags to a bug.
-
-#. *\*Keywords:*
- The administrator can define keywords which you can use to tag and
- categorise bugs - e.g. The Mozilla Project has keywords like crash
- and regression.
-
-#. *Platform and OS:*
- These indicate the computing environment where the bug was
- found.
-
-#. *Version:*
- The "Version" field is usually used for versions of a product which
- have been released, and is set to indicate which versions of a
- Component have the particular problem the bug report is
- about.
-
-#. *Priority:*
- The bug assignee uses this field to prioritize his or her bugs.
- It's a good idea not to change this on other people's bugs.
-
-#. *Severity:*
- This indicates how severe the problem is - from blocker
- ("application unusable") to trivial ("minor cosmetic issue"). You
- can also use this field to indicate whether a bug is an enhancement
- request.
-
-#. *\*Target:*
- (a.k.a. Target Milestone) A future version by which the bug is to
- be fixed. e.g. The Bugzilla Project's milestones for future
- Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are not
- restricted to numbers, thought - you can use any text strings, such
- as dates.
-
-#. *Reporter:*
- The person who filed the bug.
-
-#. *CC list:*
- A list of people who get mail when the bug changes.
-
-#. *\*Time Tracking:*
- This form can be used for time tracking.
- To use this feature, you have to be blessed group membership
- specified by the ``timetrackinggroup`` parameter.
-
- Orig. Est.:
- This field shows the original estimated time.
- Current Est.:
- This field shows the current estimated time.
- This number is calculated from ``Hours Worked``
- and ``Hours Left``.
- Hours Worked:
- This field shows the number of hours worked.
- Hours Left:
- This field shows the ``Current Est.`` -
- ``Hours Worked``.
- This value + ``Hours Worked`` will become the
- new Current Est.
- %Complete:
- This field shows what percentage of the task is complete.
- Gain:
- This field shows the number of hours that the bug is ahead of the
- ``Orig. Est.``.
- Deadline:
- This field shows the deadline for this bug.
-
-#. *Attachments:*
- You can attach files (e.g. testcases or patches) to bugs. If there
- are any attachments, they are listed in this section.
-
-#. *\*Dependencies:*
- If this bug cannot be fixed unless other bugs are fixed (depends
- on), or this bug stops other bugs being fixed (blocks), their
- numbers are recorded here.
-
-#. *\*Votes:*
- Whether this bug has any votes.
-
-#. *Additional Comments:*
- You can add your two cents to the bug discussion here, if you have
- something worthwhile to say.
-
-.. _lifecycle:
-
-Life Cycle of a Bug
-###################
-
-The life cycle of a bug, also known as workflow, is customizable to match
-the needs of your organization, see :ref:`bug_status_workflow`.
-:ref:`lifecycle-image` contains a graphical representation of
-the default workflow using the default bug statuses. If you wish to
-customize this image for your site, the
-`diagram file <../images/bzLifecycle.xml>`_
-is available in `Dia's <http://www.gnome.org/projects/dia>`_
-native XML format.
-
-.. _lifecycle-image:
-
-Lifecycle of a Bugzilla Bug
-===========================
-
-.. image:: ../images/bzLifecycle.png
-
-.. _query:
-
-Searching for Bugs
-##################
-
-The Bugzilla Search page is the interface where you can find
-any bug report, comment, or patch currently in the Bugzilla system.
-`You can play with it on
-Landfill <http://landfill.bugzilla.org/bugzilla-tip/query.cgi?format=advanced>`_.
-
-The Search page has controls for selecting different possible
-values for all of the fields in a bug, as described above. For some
-fields, multiple values can be selected. In those cases, Bugzilla
-returns bugs where the content of the field matches any one of the selected
-values. If none is selected, then the field can take any value.
-
-After a search is run, you can save it as a Saved Search, which
-will appear in the page footer. If you are in the group defined
-by the "querysharegroup" parameter, you may share your queries
-with other users, see :ref:`savedsearches` for more details.
-
-.. _boolean:
-
-Boolean Charts
-==============
-
-Highly advanced querying is done using Boolean Charts.
-
-The boolean charts further restrict the set of results
-returned by a query. It is possible to search for bugs
-based on elaborate combinations of criteria.
-
-The simplest boolean searches have only one term. These searches
-permit the selected left *field*
-to be compared using a
-selectable *operator* to a
-specified *value.*
-Using the "And," "Or," and "Add Another Boolean Chart" buttons,
-additional terms can be included in the query, further
-altering the list of bugs returned by the query.
-
-There are three fields in each row of a boolean search.
-
-- *Field:*
- the items being searched
-
-- *Operator:*
- the comparison operator
-
-- *Value:*
- the value to which the field is being compared
-
-.. _pronouns:
-
-Pronoun Substitution
---------------------
-
-Sometimes, a query needs to compare a user-related field
-(such as ReportedBy) with a role-specific user (such as the
-user running the query or the user to whom each bug is assigned).
-When the operator is either "equals" or "notequals", the value
-can be "%reporter%", "%assignee%", "%qacontact%", or "%user%".
-The user pronoun
-refers to the user who is executing the query or, in the case
-of whining reports, the user who will be the recipient
-of the report. The reporter, assignee, and qacontact
-pronouns refer to the corresponding fields in the bug.
-
-Boolean charts also let you type a group name in any user-related
-field if the operator is either "equals", "notequals" or "anyexact".
-This will let you query for any member belonging (or not) to the
-specified group. The group name must be entered following the
-"%group.foo%" syntax, where "foo" is the group name.
-So if you are looking for bugs reported by any user being in the
-"editbugs" group, then you can type "%group.editbugs%".
-
-.. _negation:
-
-Negation
---------
-
-At first glance, negation seems redundant. Rather than
-searching for
-
- NOT("summary" "contains the string" "foo"),
-
-one could search for
-
- ("summary" "does not contain the string" "foo").
-
-However, the search
-
- ("CC" "does not contain the string" "@mozilla.org")
-
-would find every bug where anyone on the CC list did not contain
-"@mozilla.org" while
-
- NOT("CC" "contains the string" "@mozilla.org")
-
-would find every bug where there was nobody on the CC list who
-did contain the string. Similarly, the use of negation also permits
-complex expressions to be built using terms OR'd together and then
-negated. Negation permits queries such as
-
- NOT(("product" "equals" "update") OR
- ("component" "equals" "Documentation"))
-
-to find bugs that are neither
-in the update product or in the documentation component or
-
- NOT(("commenter" "equals" "%assignee%") OR
- ("component" "equals" "Documentation"))
-
-to find non-documentation
-bugs on which the assignee has never commented.
-
-.. _multiplecharts:
-
-Multiple Charts
----------------
-
-The terms within a single row of a boolean chart are all
-constraints on a single piece of data. If you are looking for
-a bug that has two different people cc'd on it, then you need
-to use two boolean charts. A search for
-
- ("cc" "contains the string" "foo@") AND
- ("cc" "contains the string" "@mozilla.org")
-
-would return only bugs with "foo@mozilla.org" on the cc list.
-If you wanted bugs where there is someone on the cc list
-containing "foo@" and someone else containing "@mozilla.org",
-then you would need two boolean charts.
-
- First chart: ("cc" "contains the string" "foo@")
- Second chart: ("cc" "contains the string" "@mozilla.org")
-
-The bugs listed will be only the bugs where ALL the charts are true.
-
-.. _quicksearch:
-
-Quicksearch
-===========
-
-Quicksearch is a single-text-box query tool which uses
-metacharacters to indicate what is to be searched. For example, typing
-"``foo|bar``"
-into Quicksearch would search for "foo" or "bar" in the
-summary and status whiteboard of a bug; adding
-"``:BazProduct``" would
-search only in that product.
-You can use it to find a bug by its number or its alias, too.
-
-You'll find the Quicksearch box in Bugzilla's footer area.
-On Bugzilla's front page, there is an additional
-`Help <../../page.cgi?id=quicksearch.html>`_
-link which details how to use it.
-
-.. _casesensitivity:
-
-Case Sensitivity in Searches
-============================
-
-Bugzilla queries are case-insensitive and accent-insensitive, when
-used with either MySQL or Oracle databases. When using Bugzilla with
-PostgreSQL, however, some queries are case-sensitive. This is due to
-the way PostgreSQL handles case and accent sensitivity.
-
-.. _list:
-
-Bug Lists
-=========
-
-If you run a search, a list of matching bugs will be returned.
-
-The format of the list is configurable. For example, it can be
-sorted by clicking the column headings. Other useful features can be
-accessed using the links at the bottom of the list:
-
-Long Format:
- this gives you a large page with a non-editable summary of the fields
- of each bug.
-
-XML:
- get the buglist in the XML format.
-
-CSV:
- get the buglist as comma-separated values, for import into e.g.
- a spreadsheet.
-
-Feed:
- get the buglist as an Atom feed. Copy this link into your
- favorite feed reader. If you are using Firefox, you can also
- save the list as a live bookmark by clicking the live bookmark
- icon in the status bar. To limit the number of bugs in the feed,
- add a limit=n parameter to the URL.
-
-iCalendar:
- Get the buglist as an iCalendar file. Each bug is represented as a
- to-do item in the imported calendar.
-
-Change Columns:
- change the bug attributes which appear in the list.
-
-Change several bugs at once:
- If your account is sufficiently empowered, and more than one bug
- appear in the bug list, this link is displayed which lets you make
- the same change to all the bugs in the list - for example, changing
- their assignee.
-
-Send mail to bug assignees:
- If more than one bug appear in the bug list and there are at least
- two distinct bug assignees, this links is displayed which lets you
- easily send a mail to the assignees of all bugs on the list.
-
-Edit Search:
- If you didn't get exactly the results you were looking for, you can
- return to the Query page through this link and make small revisions
- to the query you just made so you get more accurate results.
-
-Remember Search As:
- You can give a search a name and remember it; a link will appear
- in your page footer giving you quick access to run it again later.
-
-.. _individual-buglists:
-
-Adding/removing tags to/from bugs
-=================================
-
-You can add and remove tags from individual bugs, which let you find and
-manage bugs more easily. Tags are per-user and so are only visible and editable
-by the user who created them. You can then run queries using tags as a criteria,
-either by using the Advanced Search form, or simply by typing "tag:my_tag_name"
-in the QuickSearch box at the top (or bottom) of the page. Tags can also be
-displayed in buglists.
-
-This feature is useful when you want to keep track of several bugs, but
-for different reasons. Instead of adding yourself to the CC list of all
-these bugs and mixing all these reasons, you can now store these bugs in
-separate lists, e.g. ``Keep in mind``, ``Interesting bugs``,
-or ``Triage``. One big advantage of this way to manage bugs
-is that you can easily add or remove tags from bugs one by one.
-
-.. _bugreports:
-
-Filing Bugs
-###########
-
-.. _fillingbugs:
-
-Reporting a New Bug
-===================
-
-Years of bug writing experience has been distilled for your
-reading pleasure into the
-`Bug Writing Guidelines <http://landfill.bugzilla.org/bugzilla-tip/page.cgi?id=bug-writing.html>`_.
-While some of the advice is Mozilla-specific, the basic principles of
-reporting Reproducible, Specific bugs, isolating the Product you are
-using, the Version of the Product, the Component which failed, the
-Hardware Platform, and Operating System you were using at the time of
-the failure go a long way toward ensuring accurate, responsible fixes
-for the bug that bit you.
-
-The procedure for filing a bug is as follows:
-
-#. Click the ``New`` link available in the footer
- of pages, or the ``Enter a new bug report`` link
- displayed on the home page of the Bugzilla installation.
-
- .. note:: If you want to file a test bug to see how Bugzilla works,
- you can do it on one of our test installations on
- `Landfill <http://landfill.bugzilla.org/>`_.
-
-#. You first have to select the product in which you found a bug.
-
-#. You now see a form where you can specify the component (part of
- the product which is affected by the bug you discovered; if you have
- no idea, just select ``General`` if such a component exists),
- the version of the program you were using, the Operating System and
- platform your program is running on and the severity of the bug (if the
- bug you found crashes the program, it's probably a major or a critical
- bug; if it's a typo somewhere, that's something pretty minor; if it's
- something you would like to see implemented, then that's an enhancement).
-
-#. You now have to give a short but descriptive summary of the bug you found.
- ``My program is crashing all the time`` is a very poor summary
- and doesn't help developers at all. Try something more meaningful or
- your bug will probably be ignored due to a lack of precision.
- The next step is to give a very detailed list of steps to reproduce
- the problem you encountered. Try to limit these steps to a minimum set
- required to reproduce the problem. This will make the life of
- developers easier, and the probability that they consider your bug in
- a reasonable timeframe will be much higher.
-
- .. note:: Try to make sure that everything in the summary is also in the first
- comment. Summaries are often updated and this will ensure your original
- information is easily accessible.
-
-#. As you file the bug, you can also attach a document (testcase, patch,
- or screenshot of the problem).
-
-#. Depending on the Bugzilla installation you are using and the product in
- which you are filing the bug, you can also request developers to consider
- your bug in different ways (such as requesting review for the patch you
- just attached, requesting your bug to block the next release of the
- product, and many other product specific requests).
-
-#. Now is a good time to read your bug report again. Remove all misspellings,
- otherwise your bug may not be found by developers running queries for some
- specific words, and so your bug would not get any attention.
- Also make sure you didn't forget any important information developers
- should know in order to reproduce the problem, and make sure your
- description of the problem is explicit and clear enough.
- When you think your bug report is ready to go, the last step is to
- click the ``Commit`` button to add your report into the database.
-
-You do not need to put "any" or similar strings in the URL field.
-If there is no specific URL associated with the bug, leave this
-field blank.
-
-If you feel a bug you filed was incorrectly marked as a
-DUPLICATE of another, please question it in your bug, not
-the bug it was duped to. Feel free to CC the person who duped it
-if they are not already CCed.
-
-.. _cloningbugs:
-
-Clone an Existing Bug
-=====================
-
-Starting with version 2.20, Bugzilla has a feature that allows you
-to clone an existing bug. The newly created bug will inherit
-most settings from the old bug. This allows you to track more
-easily similar concerns in a new bug. To use this, go to the bug
-that you want to clone, then click the ``Clone This Bug``
-link on the bug page. This will take you to the ``Enter Bug``
-page that is filled with the values that the old bug has.
-You can change those values and/or texts if needed.
-
-.. _attachments:
-
-Attachments
-###########
-
-You should use attachments, rather than comments, for large chunks of ASCII
-data, such as trace, debugging output files, or log files. That way, it
-doesn't bloat the bug for everyone who wants to read it, and cause people to
-receive fat, useless mails.
-
-You should make sure to trim screenshots. There's no need to show the
-whole screen if you are pointing out a single-pixel problem.
-
-Bugzilla stores and uses a Content-Type for each attachment
-(e.g. text/html). To download an attachment as a different
-Content-Type (e.g. application/xhtml+xml), you can override this
-using a 'content_type' parameter on the URL, e.g.
-:file:`&content_type=text/plain`.
-
-Also, you can enter the URL pointing to the attachment instead of
-uploading the attachment itself. For example, this is useful if you want to
-point to an external application, a website or a very large file. Note that
-there is no guarantee that the source file will always be available, nor
-that its content will remain unchanged.
-
-Another way to attach data is to paste text directly in the text field,
-and Bugzilla will convert it into an attachment. This is pretty useful
-when you do copy and paste, and you don't want to put the text in a temporary
-file first.
-
-.. _patchviewer:
-
-Patch Viewer
-============
-
-Viewing and reviewing patches in Bugzilla is often difficult due to
-lack of context, improper format and the inherent readability issues that
-raw patches present. Patch Viewer is an enhancement to Bugzilla designed
-to fix that by offering increased context, linking to sections, and
-integrating with Bonsai, LXR and CVS.
-
-Patch viewer allows you to:
-
-+ View patches in color, with side-by-side view rather than trying
- to interpret the contents of the patch.
-
-+ See the difference between two patches.
-
-+ Get more context in a patch.
-
-+ Collapse and expand sections of a patch for easy
- reading.
-
-+ Link to a particular section of a patch for discussion or
- review
-
-+ Go to Bonsai or LXR to see more context, blame, and
- cross-references for the part of the patch you are looking at
-
-+ Create a rawtext unified format diff out of any patch, no
- matter what format it came from
-
-.. _patchviewer_view:
-
-Viewing Patches in Patch Viewer
--------------------------------
-
-The main way to view a patch in patch viewer is to click on the
-"Diff" link next to a patch in the Attachments list on a bug. You may
-also do this within the edit window by clicking the "View Attachment As
-Diff" button in the Edit Attachment screen.
-
-.. _patchviewer_diff:
-
-Seeing the Difference Between Two Patches
------------------------------------------
-
-To see the difference between two patches, you must first view the
-newer patch in Patch Viewer. Then select the older patch from the
-dropdown at the top of the page ("Differences between \[dropdown] and
-this patch") and click the "Diff" button. This will show you what
-is new or changed in the newer patch.
-
-.. _patchviewer_context:
-
-Getting More Context in a Patch
--------------------------------
-
-To get more context in a patch, you put a number in the textbox at
-the top of Patch Viewer ("Patch / File / \[textbox]") and hit enter.
-This will give you that many lines of context before and after each
-change. Alternatively, you can click on the "File" link there and it
-will show each change in the full context of the file. This feature only
-works against files that were diffed using "cvs diff".
-
-.. _patchviewer_collapse:
-
-Collapsing and Expanding Sections of a Patch
---------------------------------------------
-
-To view only a certain set of files in a patch (for example, if a
-patch is absolutely huge and you want to only review part of it at a
-time), you can click the "(+)" and "(-)" links next to each file (to
-expand it or collapse it). If you want to collapse all files or expand
-all files, you can click the "Collapse All" and "Expand All" links at the
-top of the page.
-
-.. _patchviewer_link:
-
-Linking to a Section of a Patch
--------------------------------
-
-To link to a section of a patch (for example, if you want to be
-able to give someone a URL to show them which part you are talking
-about) you simply click the "Link Here" link on the section header. The
-resulting URL can be copied and used in discussion.
-
-.. _patchviewer_bonsai_lxr:
-
-Going to Bonsai and LXR
------------------------
-
-To go to Bonsai to get blame for the lines you are interested in,
-you can click the "Lines XX-YY" link on the section header you are
-interested in. This works even if the patch is against an old
-version of the file, since Bonsai stores all versions of the file.
-
-To go to LXR, you click on the filename on the file header
-(unfortunately, since LXR only does the most recent version, line
-numbers are likely to rot).
-
-.. _patchviewer_unified_diff:
-
-Creating a Unified Diff
------------------------
-
-If the patch is not in a format that you like, you can turn it
-into a unified diff format by clicking the "Raw Unified" link at the top
-of the page.
-
-.. _hintsandtips:
-
-Hints and Tips
-##############
-
-This section distills some Bugzilla tips and best practices
-that have been developed.
-
-Autolinkification
-=================
-
-Bugzilla comments are plain text - so typing <U> will
-produce less-than, U, greater-than rather than underlined text.
-However, Bugzilla will automatically make hyperlinks out of certain
-sorts of text in comments. For example, the text
-"http://www.bugzilla.org" will be turned into a link:
-`<http://www.bugzilla.org>`_.
-Other strings which get linkified in the obvious manner are:
-
-+ bug 12345
-
-+ comment 7
-
-+ bug 23456, comment 53
-
-+ attachment 4321
-
-+ mailto:george@example.com
-
-+ george@example.com
-
-+ ftp://ftp.mozilla.org
-
-+ Most other sorts of URL
-
-A corollary here is that if you type a bug number in a comment,
-you should put the word "bug" before it, so it gets autolinkified
-for the convenience of others.
-
-.. _commenting:
-
-Comments
-========
-
-If you are changing the fields on a bug, only comment if
-either you have something pertinent to say, or Bugzilla requires it.
-Otherwise, you may spam people unnecessarily with bug mail.
-To take an example: a user can set up their account to filter out messages
-where someone just adds themselves to the CC field of a bug
-(which happens a lot.) If you come along, add yourself to the CC field,
-and add a comment saying "Adding self to CC", then that person
-gets a pointless piece of mail they would otherwise have avoided.
-
-Don't use sigs in comments. Signing your name ("Bill") is acceptable,
-if you do it out of habit, but full mail/news-style
-four line ASCII art creations are not.
-
-.. _comment-wrapping:
-
-Server-Side Comment Wrapping
-============================
-
-Bugzilla stores comments unwrapped and wraps them at display time. This
-ensures proper wrapping in all browsers. Lines beginning with the ">"
-character are assumed to be quotes, and are not wrapped.
-
-.. _dependencytree:
-
-Dependency Tree
-===============
-
-On the ``Dependency tree`` page linked from each bug
-page, you can see the dependency relationship from the bug as a
-tree structure.
-
-You can change how much depth to show, and you can hide resolved bugs
-from this page. You can also collaps/expand dependencies for
-each bug on the tree view, using the \[-]/\[+] buttons that appear
-before its summary. This option is not available for terminal
-bugs in the tree (that don't have further dependencies).
-
-.. _timetracking:
-
-Time Tracking Information
-#########################
-
-Users who belong to the group specified by the ``timetrackinggroup``
-parameter have access to time-related fields. Developers can see
-deadlines and estimated times to fix bugs, and can provide time spent
-on these bugs. Users who do not belong to this group can only see the deadline,
-but not edit it. Other time-related fields remain invisible to them.
-
-At any time, a summary of the time spent by developers on bugs is
-accessible either from bug lists when clicking the ``Time Summary``
-button or from individual bugs when clicking the ``Summarize time``
-link in the time tracking table. The :file:`summarize_time.cgi`
-page lets you view this information either per developer or per bug,
-and can be split on a month basis to have greater details on how time
-is spent by developers.
-
-As soon as a bug is marked as RESOLVED, the remaining time expected
-to fix the bug is set to zero. This lets QA people set it again for
-their own usage, and it will be set to zero again when the bug will
-be marked as CLOSED.
-
-.. _userpreferences:
-
-User Preferences
-################
-
-Once logged in, you can customize various aspects of
-Bugzilla via the "Preferences" link in the page footer.
-The preferences are split into five tabs:
-
-.. _generalpreferences:
-
-General Preferences
-===================
-
-This tab allows you to change several default settings of Bugzilla.
-
-- Bugzilla's general appearance (skin) - select which skin to use.
- Bugzilla supports adding custom skins.
-
-- Quote the associated comment when you click on its reply link - sets
- the behavior of the comment "Reply" link. Options include quoting the
- full comment, just reference the comment number, or turn the link off.
-
-- Language used in email - select which language email will be sent in,
- from the list of available languages.
-
-- After changing a bug - This controls what page is displayed after
- changes to a bug are submitted. The options include to show the bug
- just modified, to show the next bug in your list, or to do nothing.
-
-- Enable tags for bugs - turn bug tagging on or off.
-
-- Zoom textareas large when in use (requires JavaScript) - enable or
- disable the automatic expanding of text areas when text is being
- entered into them.
-
-- Field separator character for CSV files -
- Select between a comma and semi-colon for exported CSV bug lists.
-
-- Automatically add me to the CC list of bugs I change - set default
- behavior of CC list. Options include "Always", "Never", and "Only
- if I have no role on them".
-
-- When viewing a bug, show comments in this order -
- controls the order of comments. Options include "Oldest
- to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the
- bug description at the top".
-
-- Show a quip at the top of each bug list - controls
- whether a quip will be shown on the Bug list page.
-
-.. _emailpreferences:
-
-Email Preferences
-=================
-
-This tab allows you to enable or disable email notification on
-specific events.
-
-In general, users have almost complete control over how much (or
-how little) email Bugzilla sends them. If you want to receive the
-maximum amount of email possible, click the ``Enable All
-Mail`` button. If you don't want to receive any email from
-Bugzilla at all, click the ``Disable All Mail`` button.
-
-.. note:: A Bugzilla administrator can stop a user from receiving
- bugmail by clicking the ``Bugmail Disabled`` checkbox
- when editing the user account. This is a drastic step
- best taken only for disabled accounts, as it overrides
- the user's individual mail preferences.
-
-There are two global options -- ``Email me when someone
-asks me to set a flag`` and ``Email me when someone
-sets a flag I asked for``. These define how you want to
-receive bugmail with regards to flags. Their use is quite
-straightforward; enable the checkboxes if you want Bugzilla to
-send you mail under either of the above conditions.
-
-If you'd like to set your bugmail to something besides
-'Completely ON' and 'Completely OFF', the
-``Field/recipient specific options`` table
-allows you to do just that. The rows of the table
-define events that can happen to a bug -- things like
-attachments being added, new comments being made, the
-priority changing, etc. The columns in the table define
-your relationship with the bug:
-
-- Reporter - Where you are the person who initially
- reported the bug. Your name/account appears in the
- ``Reporter:`` field.
-
-- Assignee - Where you are the person who has been
- designated as the one responsible for the bug. Your
- name/account appears in the ``Assigned To:``
- field of the bug.
-
-- QA Contact - You are one of the designated
- QA Contacts for the bug. Your account appears in the
- ``QA Contact:`` text-box of the bug.
-
-- CC - You are on the list CC List for the bug.
- Your account appears in the ``CC:`` text box
- of the bug.
-
-- Voter - You have placed one or more votes for the bug.
- Your account appears only if someone clicks on the
- ``Show votes for this bug`` link on the bug.
-
-.. note:: Some columns may not be visible for your installation, depending
- on your site's configuration.
-
-To fine-tune your bugmail, decide the events for which you want
-to receive bugmail; then decide if you want to receive it all
-the time (enable the checkbox for every column), or only when
-you have a certain relationship with a bug (enable the checkbox
-only for those columns). For example: if you didn't want to
-receive mail when someone added themselves to the CC list, you
-could uncheck all the boxes in the ``CC Field Changes``
-line. As another example, if you never wanted to receive email
-on bugs you reported unless the bug was resolved, you would
-un-check all boxes in the ``Reporter`` column
-except for the one on the ``The bug is resolved or
-verified`` row.
-
-.. note:: Bugzilla adds the ``X-Bugzilla-Reason`` header to
- all bugmail it sends, describing the recipient's relationship
- (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug.
- This header can be used to do further client-side filtering.
-
-Bugzilla has a feature called ``Users Watching``.
-When you enter one or more comma-delineated user accounts (usually email
-addresses) into the text entry box, you will receive a copy of all the
-bugmail those users are sent (security settings permitting).
-This powerful functionality enables seamless transitions as developers
-change projects or users go on holiday.
-
-.. note:: The ability to watch other users may not be available in all
- Bugzilla installations. If you don't see this feature, and feel
- that you need it, speak to your administrator.
-
-Each user listed in the ``Users watching you`` field
-has you listed in their ``Users to watch`` list
-and can get bugmail according to your relationship to the bug and
-their ``Field/recipient specific options`` setting.
-
-.. _savedsearches:
-
-Saved Searches
-==============
-
-On this tab you can view and run any Saved Searches that you have
-created, and also any Saved Searches that other members of the group
-defined in the "querysharegroup" parameter have shared.
-Saved Searches can be added to the page footer from this screen.
-If somebody is sharing a Search with a group she or he is allowed to
-:ref:`assign users to <groups>`, the sharer may opt to have
-the Search show up in the footer of the group's direct members by default.
-
-.. _accountpreferences:
-
-Account Information
-===================
-
-On this tab, you can change your basic account information,
-including your password, email address and real name. For security
-reasons, in order to change anything on this page you must type your
-*current* password into the ``Password``
-field at the top of the page.
-If you attempt to change your email address, a confirmation
-email is sent to both the old and new addresses, with a link to use to
-confirm the change. This helps to prevent account hijacking.
-
-.. _permissionsettings:
-
-Permissions
-===========
-
-This is a purely informative page which outlines your current
-permissions on this installation of Bugzilla.
-
-A complete list of permissions is below. Only users with
-*editusers* privileges can change the permissions
-of other users.
-
-admin
- Indicates user is an Administrator.
-
-bz_canusewhineatothers
- Indicates user can configure whine reports for other users.
-
-bz_canusewhines
- Indicates user can configure whine reports for self.
-
-bz_quip_moderators
- Indicates user can moderate quips.
-
-bz_sudoers
- Indicates user can perform actions as other users.
-
-bz_sudo_protect
- Indicates user cannot be impersonated by other users.
-
-canconfirm
- Indicates user can confirm a bug or mark it a duplicate.
-
-creategroups
- Indicates user can create and destroy groups.
-
-editbugs
- Indicates user can edit all bug fields.
-
-editclassifications
- Indicates user can create, destroy, and edit classifications.
-
-editcomponents
- Indicates user can create, destroy, and edit components.
-
-editkeywords
- Indicates user can create, destroy, and edit keywords.
-
-editusers
- Indicates user can edit or disable users.
-
-tweakparams
- Indicates user can change Parameters.
-
-.. note:: For more information on how permissions work in Bugzilla (i.e. who can
- change what), see :ref:`cust-change-permissions`.
-
-.. _reporting:
-
-Reports and Charts
-##################
-
-As well as the standard buglist, Bugzilla has two more ways of
-viewing sets of bugs. These are the reports (which give different
-views of the current state of the database) and charts (which plot
-the changes in particular sets of bugs over time.)
-
-.. _reports:
-
-Reports
-=======
-
-A report is a view of the current state of the bug database.
-
-You can run either an HTML-table-based report, or a graphical
-line/pie/bar-chart-based one. The two have different pages to
-define them, but are close cousins - once you've defined and
-viewed a report, you can switch between any of the different
-views of the data at will.
-
-Both report types are based on the idea of defining a set of bugs
-using the standard search interface, and then choosing some
-aspect of that set to plot on the horizontal and/or vertical axes.
-You can also get a form of 3-dimensional report by choosing to have
-multiple images or tables.
-
-So, for example, you could use the search form to choose "all
-bugs in the WorldControl product", and then plot their severity
-against their component to see which component had had the largest
-number of bad bugs reported against it.
-
-Once you've defined your parameters and hit "Generate Report",
-you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie
-is only available if you didn't define a vertical axis, as pie
-charts don't have one.) The other controls are fairly self-explanatory;
-you can change the size of the image if you find text is overwriting
-other text, or the bars are too thin to see.
-
-.. _charts:
-
-Charts
-======
-
-A chart is a view of the state of the bug database over time.
-
-Bugzilla currently has two charting systems - Old Charts and New
-Charts. Old Charts have been part of Bugzilla for a long time; they
-chart each status and resolution for each product, and that's all.
-They are deprecated, and going away soon - we won't say any more
-about them.
-New Charts are the future - they allow you to chart anything you
-can define as a search.
-
-.. note:: Both charting forms require the administrator to set up the
- data-gathering script. If you can't see any charts, ask them whether
- they have done so.
-
-An individual line on a chart is called a data set.
-All data sets are organised into categories and subcategories. The
-data sets that Bugzilla defines automatically use the Product name
-as a Category and Component names as Subcategories, but there is no
-need for you to follow that naming scheme with your own charts if
-you don't want to.
-
-Data sets may be public or private. Everyone sees public data sets in
-the list, but only their creator sees private data sets. Only
-administrators can make data sets public.
-No two data sets, even two private ones, can have the same set of
-category, subcategory and name. So if you are creating private data
-sets, one idea is to have the Category be your username.
-
-Creating Charts
----------------
-
-You create a chart by selecting a number of data sets from the
-list, and pressing Add To List for each. In the List Of Data Sets
-To Plot, you can define the label that data set will have in the
-chart's legend, and also ask Bugzilla to Sum a number of data sets
-(e.g. you could Sum data sets representing RESOLVED, VERIFIED and
-CLOSED in a particular product to get a data set representing all
-the resolved bugs in that product.)
-
-If you've erroneously added a data set to the list, select it
-using the checkbox and click Remove. Once you add more than one
-data set, a "Grand Total" line
-automatically appears at the bottom of the list. If you don't want
-this, simply remove it as you would remove any other line.
-
-You may also choose to plot only over a certain date range, and
-to cumulate the results - that is, to plot each one using the
-previous one as a baseline, so the top line gives a sum of all
-the data sets. It's easier to try than to explain :-)
-
-Once a data set is in the list, one can also perform certain
-actions on it. For example, one can edit the
-data set's parameters (name, frequency etc.) if it's one you
-created or if you are an administrator.
-
-Once you are happy, click Chart This List to see the chart.
-
-.. _charts-new-series:
-
-Creating New Data Sets
-----------------------
-
-You may also create new data sets of your own. To do this,
-click the "create a new data set" link on the Create Chart page.
-This takes you to a search-like interface where you can define
-the search that Bugzilla will plot. At the bottom of the page,
-you choose the category, sub-category and name of your new
-data set.
-
-If you have sufficient permissions, you can make the data set public,
-and reduce the frequency of data collection to less than the default
-seven days.
-
-.. _flags:
-
-Flags
-#####
-
-A flag is a kind of status that can be set on bugs or attachments
-to indicate that the bugs/attachments are in a certain state.
-Each installation can define its own set of flags that can be set
-on bugs or attachments.
-
-If your installation has defined a flag, you can set or unset that flag,
-and if your administrator has enabled requesting of flags, you can submit
-a request for another user to set the flag.
-
-To set a flag, select either "+" or "-" from the drop-down menu next to
-the name of the flag in the "Flags" list. The meaning of these values are
-flag-specific and thus cannot be described in this documentation,
-but by way of example, setting a flag named "review" to "+" may indicate
-that the bug/attachment has passed review, while setting it to "-"
-may indicate that the bug/attachment has failed review.
-
-To unset a flag, click its drop-down menu and select the blank value.
-Note that marking an attachment as obsolete automatically cancels all
-pending requests for the attachment.
-
-If your administrator has enabled requests for a flag, request a flag
-by selecting "?" from the drop-down menu and then entering the username
-of the user you want to set the flag in the text field next to the menu.
-
-A set flag appears in bug reports and on "edit attachment" pages with the
-abbreviated username of the user who set the flag prepended to the
-flag name. For example, if Jack sets a "review" flag to "+", it appears
-as Jack: review [ + ]
-
-A requested flag appears with the user who requested the flag prepended
-to the flag name and the user who has been requested to set the flag
-appended to the flag name within parentheses. For example, if Jack
-asks Jill for review, it appears as Jack: review [ ? ] (Jill).
-
-You can browse through open requests made of you and by you by selecting
-'My Requests' from the footer. You can also look at open requests limited
-by other requesters, requestees, products, components, and flag names from
-this page. Note that you can use '-' for requestee to specify flags with
-'no requestee' set.
-
-.. _whining:
-
-Whining
-#######
-
-Whining is a feature in Bugzilla that can regularly annoy users at
-specified times. Using this feature, users can execute saved searches
-at specific times (i.e. the 15th of the month at midnight) or at
-regular intervals (i.e. every 15 minutes on Sundays). The results of the
-searches are sent to the user, either as a single email or as one email
-per bug, along with some descriptive text.
-
-.. warning:: Throughout this section it will be assumed that all users are members
- of the bz_canusewhines group, membership in which is required in order
- to use the Whining system. You can easily make all users members of
- the bz_canusewhines group by setting the User RegExp to ".*" (without
- the quotes).
-
- Also worth noting is the bz_canusewhineatothers group. Members of this
- group can create whines for any user or group in Bugzilla using a
- extended form of the whining interface. Features only available to
- members of the bz_canusewhineatothers group will be noted in the
- appropriate places.
-
-.. note:: For whining to work, a special Perl script must be executed at regular
- intervals. More information on this is available in :ref:`installation-whining`.
-
-.. note:: This section does not cover the whineatnews.pl script.
- See :ref:`installation-whining-cron` for more information on
- The Whining Cron.
-
-.. _whining-overview:
-
-The Event
-=========
-
-The whining system defines an "Event" as one or more queries being
-executed at regular intervals, with the results of said queries (if
-there are any) being emailed to the user. Events are created by
-clicking on the "Add new event" button.
-
-Once a new event is created, the first thing to set is the "Email
-subject line". The contents of this field will be used in the subject
-line of every email generated by this event. In addition to setting a
-subject, space is provided to enter some descriptive text that will be
-included at the top of each message (to help you in understanding why
-you received the email in the first place).
-
-The next step is to specify when the Event is to be run (the Schedule)
-and what searches are to be performed (the Searches).
-
-.. _whining-schedule:
-
-Whining Schedule
-================
-
-Each whining event is associated with zero or more schedules. A
-schedule is used to specify when the search (specified below) is to be
-run. A new event starts out with no schedules (which means it will
-never run, as it is not scheduled to run). To add a schedule, press
-the "Add a new schedule" button.
-
-Each schedule includes an interval, which you use to tell Bugzilla
-when the event should be run. An event can be run on certain days of
-the week, certain days of the month, during weekdays (defined as
-Monday through Friday), or every day.
-
-.. warning:: Be careful if you set your event to run on the 29th, 30th, or 31st of
- the month, as your event may not run exactly when expected. If you
- want your event to run on the last day of the month, select "Last day
- of the month" as the interval.
-
-Once you have specified the day(s) on which the event is to be run, you
-should now specify the time at which the event is to be run. You can
-have the event run at a certain hour on the specified day(s), or
-every hour, half-hour, or quarter-hour on the specified day(s).
-
-If a single schedule does not execute an event as many times as you
-would want, you can create another schedule for the same event. For
-example, if you want to run an event on days whose numbers are
-divisible by seven, you would need to add four schedules to the event,
-setting the schedules to run on the 7th, 14th, 21st, and 28th (one day
-per schedule) at whatever time (or times) you choose.
-
-.. note:: If you are a member of the bz_canusewhineatothers group, then you
- will be presented with another option: "Mail to". Using this you
- can control who will receive the emails generated by this event. You
- can choose to send the emails to a single user (identified by email
- address) or a single group (identified by group name). To send to
- multiple users or groups, create a new schedule for each additional
- user/group.
-
-.. _whining-query:
-
-Whining Searches
-================
-
-Each whining event is associated with zero or more searches. A search
-is any saved search to be run as part of the specified schedule (see
-above). You start out without any searches associated with the event
-(which means that the event will not run, as there will never be any
-results to return). To add a search, press the "Add a search" button.
-
-The first field to examine in your newly added search is the Sort field.
-Searches are run, and results included, in the order specified by the
-Sort field. Searches with smaller Sort values will run before searches
-with bigger Sort values.
-
-The next field to examine is the Search field. This is where you
-choose the actual search that is to be run. Instead of defining search
-parameters here, you are asked to choose from the list of saved
-searches (the same list that appears at the bottom of every Bugzilla
-page). You are only allowed to choose from searches that you have
-saved yourself (the default saved search, "My Bugs", is not a valid
-choice). If you do not have any saved searches, you can take this
-opportunity to create one (see :ref:`list`).
-
-.. note:: When running searches, the whining system acts as if you are the user
- executing the search. This means that the whining system will ignore
- bugs that match your search, but that you cannot access.
-
-Once you have chosen the saved search to be executed, give the search a
-descriptive title. This title will appear in the email, above the
-results of the search. If you choose "One message per bug", the search
-title will appear at the top of each email that contains a bug matching
-your search.
-
-Finally, decide if the results of the search should be sent in a single
-email, or if each bug should appear in its own email.
-
-.. warning:: Think carefully before checking the "One message per bug" box. If
- you create a search that matches thousands of bugs, you will receive
- thousands of emails!
-
-Saving Your Changes
-===================
-
-Once you have defined at least one schedule, and created at least one
-search, go ahead and "Update/Commit". This will save your Event and make
-it available for immediate execution.
-
-.. note:: If you ever feel like deleting your event, you may do so using the
- "Remove Event" button in the upper-right corner of each Event. You
- can also modify an existing event, so long as you "Update/Commit"
- after completing your modifications.
-
+.. _creating-an-account:
+
+Creating an Account
+###################
+
+If you want to use a particular installation of Bugzilla, first you need to
+create an account. Ask the administrator responsible for your installation
+for the URL you should use to access it. If you're test-driving Bugzilla,
+you can use one of the installations on
+`Landfill <http://landfill.bugzilla.org/>`_.
+
+The process of creating an account is similar to many other websites.
+
+#. On the home page, click the :guilabel:`New Account` link in the header.
+ Enter your email address, then click the ``Send``
+ button.
+
+ .. note:: If the :guilabel:`New Account` link is not available, this means that the
+ administrator of the installation has disabled self-registration.
+ Speak to the administrator to find out how to get an account.
+
+#. Within moments, you should
+ receive an email to the address you provided, which contains your
+ login name (generally the same as the email address), and a URL to
+ click to confirm your registration.
+
+#. Once you confirm your registration, Bugzilla will ask you your real name
+ (optional, but recommended) and ask you to choose a password. Depending
+ on how your Bugzilla is configured, there may be minimum complexity
+ requirements for the password.
+
+#. Now all you need to do is to click the :guilabel:`Log In`
+ link in the header or footer,
+ enter your email address and the password you just chose into the
+ login form, and click the :guilabel:`Log in` button.
+
+You are now logged in. Bugzilla uses cookies to remember you are
+logged in so, unless you have cookies disabled or your IP address changes,
+you should not have to log in again during your session.
+.. _editing:
+
+Editing a Bug
+#############
+
+.. _attachments:
+
+Attachments
+===========
+
+You should use attachments, rather than comments, for large chunks of ASCII
+data, such as trace, debugging output files, or log files. That way, it
+doesn't bloat the bug for everyone who wants to read it, and cause people to
+receive fat, useless mails.
+
+You should make sure to trim screenshots. There's no need to show the
+whole screen if you are pointing out a single-pixel problem.
+
+Bugzilla stores and uses a Content-Type for each attachment
+(e.g. text/html). To download an attachment as a different
+Content-Type (e.g. application/xhtml+xml), you can override this
+using a 'content_type' parameter on the URL, e.g.
+:file:`&content_type=text/plain`.
+
+Also, you can enter the URL pointing to the attachment instead of
+uploading the attachment itself. For example, this is useful if you want to
+point to an external application, a website or a very large file.
+
+It's also possible to create an attachment by pasting text directly in a text
+field; Bugzilla will convert it into an attachment. This is pretty useful
+when you are copying and pasting, to avoid the extra step of saving the text
+in a temporary file.
+
+.. _flags:
+
+Flags
+=====
+
+A flag is a kind of status that can be set on bugs or attachments
+to indicate that the bugs/attachments are in a certain state.
+Each installation can define its own set of flags that can be set
+on bugs or attachments.
+
+If your installation has defined a flag, you can set or unset that flag,
+and if your administrator has enabled requesting of flags, you can submit
+a request for another user to set the flag.
+
+To set a flag, select either "+" or "-" from the drop-down menu next to
+the name of the flag in the "Flags" list. The meaning of these values are
+flag-specific and thus cannot be described in this documentation,
+but by way of example, setting a flag named "review" to "+" may indicate
+that the bug/attachment has passed review, while setting it to "-"
+may indicate that the bug/attachment has failed review.
+
+To unset a flag, click its drop-down menu and select the blank value.
+Note that marking an attachment as obsolete automatically cancels all
+pending requests for the attachment.
+
+If your administrator has enabled requests for a flag, request a flag
+by selecting "?" from the drop-down menu and then entering the username
+of the user you want to set the flag in the text field next to the menu.
+
+A set flag appears in bug reports and on "edit attachment" pages with the
+abbreviated username of the user who set the flag prepended to the
+flag name. For example, if Jack sets a "review" flag to "+", it appears
+as Jack: review [ + ]
+
+A requested flag appears with the user who requested the flag prepended
+to the flag name and the user who has been requested to set the flag
+appended to the flag name within parentheses. For example, if Jack
+asks Jill for review, it appears as Jack: review [ ? ] (Jill).
+
+You can browse through open requests made of you and by you by selecting
+'My Requests' from the footer. You can also look at open requests limited
+by other requesters, requestees, products, components, and flag names from
+this page. Note that you can use '-' for requestee to specify flags with
+'no requestee' set.
+
+.. _time-tracking:
+
+Time Tracking
+=============
+
+Users who belong to the group specified by the ``timetrackinggroup``
+parameter have access to time-related fields. Developers can see
+deadlines and estimated times to fix bugs, and can provide time spent
+on these bugs. Users who do not belong to this group can only see the deadline,
+but not edit it. Other time-related fields remain invisible to them.
+
+At any time, a summary of the time spent by developers on bugs is
+accessible either from bug lists when clicking the ``Time Summary``
+button or from individual bugs when clicking the ``Summarize time``
+link in the time tracking table. The :file:`summarize_time.cgi`
+page lets you view this information either per developer or per bug,
+and can be split on a month basis to have greater details on how time
+is spent by developers.
+
+As soon as a bug is marked as RESOLVED, the remaining time expected
+to fix the bug is set to zero. This lets QA people set it again for
+their own usage, and it will be set to zero again when the bug will
+be marked as CLOSED.
+
+.. _lifecycle:
+
+Life Cycle of a Bug
+===================
+
+The life cycle of a bug, also known as workflow, is customizable to match
+the needs of your organization (see :ref:`workflow`).
+The image below contains a graphical representation of
+the default workflow using the default bug statuses. If you wish to
+customize this image for your site, the
+`diagram file <../../images/bzLifecycle.xml>`_
+is available in `Dia's <http://www.gnome.org/projects/dia>`_
+native XML format.
+
+.. image:: ../../images/bzLifecycle.png
+.. _filing:
+
+Filing a Bug
+############
+
+Reporting a New Bug
+===================
+
+Years of bug writing experience has been distilled for your
+reading pleasure into the
+`Bug Writing Guidelines <http://landfill.bugzilla.org/bugzilla-tip/page.cgi?id=bug-writing.html>`_.
+While some of the advice is Mozilla-specific, the basic principles of
+reporting Reproducible, Specific bugs, isolating the Product you are
+using, the Version of the Product, the Component which failed, the
+Hardware Platform, and Operating System you were using at the time of
+the failure go a long way toward ensuring accurate, responsible fixes
+for the bug that bit you.
+
+.. note:: If you want to file a test bug to see how Bugzilla works,
+ you can do it on one of our test installations on
+ `Landfill <http://landfill.bugzilla.org/>`_. Please don't do it on anyone's
+ production Bugzilla installation.
+
+The procedure for filing a bug is as follows:
+
+#. Click the ``New`` link available in the header or footer
+ of pages, or the ``File a Bug`` link on the home page.
+
+#. First, you have to select the product in which you found a bug.
+
+#. You now see a form where you can specify the component (part of
+ the product which is affected by the bug you discovered; if you have
+ no idea, just select ``General`` if such a component exists),
+ the version of the program you were using, the operating system and
+ platform your program is running on and the severity of the bug (if the
+ bug you found crashes the program, it's probably a major or a critical
+ bug; if it's a typo somewhere, that's something pretty minor; if it's
+ something you would like to see implemented, then that's an enhancement).
+
+#. You also need to provide a short but descriptive summary of the bug you found.
+ ``My program is crashing all the time`` is a very poor summary
+ and doesn't help developers at all. Try something more meaningful or
+ your bug will probably be ignored due to a lack of precision.
+ In the Description, give a detailed list of steps to reproduce
+ the problem you encountered. Try to limit these steps to a minimum set
+ required to reproduce the problem. This will make the life of
+ developers easier, and the probability that they consider your bug in
+ a reasonable timeframe will be much higher.
+
+ .. note:: Try to make sure that everything in the Summary is also in the
+ Description. Summaries are often updated and this will ensure your original
+ information is easily accessible.
+
+#. As you file the bug, you can also attach a document (testcase, patch,
+ or screenshot of the problem).
+
+#. Depending on the Bugzilla installation you are using and the product in
+ which you are filing the bug, you can also request developers to consider
+ your bug in different ways (such as requesting review for the patch you
+ just attached, requesting your bug to block the next release of the
+ product, and many other product specific requests).
+
+#. Now is a good time to read your bug report again. Remove all mis-spellings,
+ otherwise your bug may not be found by developers running queries for some
+ specific words, and so your bug would not get any attention.
+ Also make sure you didn't forget any important information developers
+ should know in order to reproduce the problem, and make sure your
+ description of the problem is explicit and clear enough.
+ When you think your bug report is ready to go, the last step is to
+ click the ``Submit Bug`` button to add your report into the database.
+
+.. _cloning-a-bug:
+
+Clone an Existing Bug
+=====================
+
+Bugzilla allows you to 'clone' an existing bug. The newly created bug will
+inherit most settings from the old bug. This allows you to track similar
+concerns which require different handling in a new bug. To use this, go to
+the bug that you want to clone, then click the ``Clone This Bug``
+link on the bug page. This will take you to the ``Enter Bug``
+page that is filled with the values that the old bug has.
+You can then change the values and/or text if needed.
+.. _finding:
+
+Finding Bugs
+############
+
+Bugzilla has a number of different search options.
+
+.. note:: Bugzilla queries are case-insensitive and accent-insensitive, when
+ used with either MySQL or Oracle databases. When using Bugzilla with
+ PostgreSQL, however, some queries are case-sensitive. This is due to
+ the way PostgreSQL handles case and accent sensitivity.
+
+.. _quicksearch:
+
+Quicksearch
+===========
+
+Quicksearch is a single-text-box query tool. You'll find it in
+Bugzilla's header or footer.
+
+Quicksearch uses
+metacharacters to indicate what is to be searched. For example, typing
+
+ ``foo|bar``
+
+into Quicksearch would search for "foo" or "bar" in the
+summary and status whiteboard of a bug; adding
+
+ ``:BazProduct``
+
+would search only in that product.
+
+You can also use it to go directly to a bug by entering its number or its
+alias.
+
+Simple Search
+=============
+
+Simple Search is good for finding one particular bug. It works like internet
+search engines - just enter some keywords and off you go.
+
+Advanced Search
+===============
+
+The Advanced Search page is used to produce a list of all bugs fitting
+exactly-defined criteria. `You can play with it on
+Landfill <http://landfill.bugzilla.org/bugzilla-tip/query.cgi?format=advanced>`_.
+
+Advanced Search has controls for selecting different possible
+values for all of the fields in a bug, as described above. For some
+fields, multiple values can be selected. In those cases, Bugzilla
+returns bugs where the content of the field matches any one of the selected
+values. If none is selected, then the field can take any value.
+
+After a search is run, you can save it as a Saved Search, which
+will appear in the page footer. If you are in the group defined
+by the "querysharegroup" parameter, you may share your queries
+with other users, see :ref:`savedsearches` for more details.
+
+.. _custom-search:
+
+Custom Search
+=============
+
+Highly advanced querying is done using the Custom Search feature of the
+Advanced Search page.
+
+The search criteria here further restrict the set of results
+returned by a query over and above those defined in the fields at the top
+of the page. It is thereby possible to search for bugs
+based on elaborate combinations of criteria.
+
+The simplest boolean searches have only one term. These searches
+permit the selected *field*
+to be compared using a
+selectable *operator* to a
+specified *value.* Much of this could be reproduced using the standard
+fields. However, you can then combine terms using "Match ANY" or "Match ALL",
+using parentheses for combining and priority, in order to construct searches
+of almost arbitrary complexity.
+
+There are three fields in each row of a boolean search.
+
+- *Field:*
+ the items being searched
+
+- *Operator:*
+ the comparison operator
+
+- *Value:*
+ the value to which the field is being compared
+
+.. _negation:
+
+.. _multiplecharts:
+
+Multiple Charts
+---------------
+
+XXX This needs rewriting for the new UI.
+
+The terms within a single row of a boolean chart are all
+constraints on a single piece of data. If you are looking for
+a bug that has two different people cc'd on it, then you need
+to use two boolean charts. A search for
+
+ ("cc" "contains the string" "foo@") AND
+ ("cc" "contains the string" "@mozilla.org")
+
+would return only bugs with "foo@mozilla.org" on the cc list.
+If you wanted bugs where there is someone on the cc list
+containing "foo@" and someone else containing "@mozilla.org",
+then you would need two boolean charts.
+
+ First chart: ("cc" "contains the string" "foo@")
+ Second chart: ("cc" "contains the string" "@mozilla.org")
+
+The bugs listed will be only the bugs where ALL the charts are true.
+
+Negation
+--------
+
+At first glance, negation seems redundant. Rather than
+searching for
+
+ NOT("summary" "contains the string" "foo"),
+
+one could search for
+
+ ("summary" "does not contain the string" "foo").
+
+However, the search
+
+ ("CC" "does not contain the string" "@mozilla.org")
+
+would find every bug where anyone on the CC list did not contain
+"@mozilla.org" while
+
+ NOT("CC" "contains the string" "@mozilla.org")
+
+would find every bug where there was nobody on the CC list who
+did contain the string. Similarly, the use of negation also permits
+complex expressions to be built using terms OR'd together and then
+negated. Negation permits queries such as
+
+ NOT(("product" "equals" "update") OR
+ ("component" "equals" "Documentation"))
+
+to find bugs that are neither
+in the update product or in the documentation component or
+
+ NOT(("commenter" "equals" "%assignee%") OR
+ ("component" "equals" "Documentation"))
+
+to find non-documentation
+bugs on which the assignee has never commented.
+
+.. _pronouns:
+
+Pronoun Substitution
+--------------------
+
+Sometimes, a query needs to compare a user-related field
+(such as Reporter) with a role-specific user (such as the
+user running the query or the user to whom each bug is assigned). For
+example, you may want to find all bugs which are assigned to the person
+who reported them.
+
+When the Custom Search operator is either "equals" or "notequals", the value
+can be "%reporter%", "%assignee%", "%qacontact%", or "%user%".
+The user pronoun
+refers to the user who is executing the query or, in the case
+of whining reports, the user who will be the recipient
+of the report. The reporter, assignee, and qacontact
+pronouns refer to the corresponding fields in the bug.
+
+Boolean charts also let you type a group name in any user-related
+field if the operator is either "equals", "notequals" or "anyexact".
+This will let you query for any member belonging (or not) to the
+specified group. The group name must be entered following the
+"%group.foo%" syntax, where "foo" is the group name.
+So if you are looking for bugs reported by any user being in the
+"editbugs" group, then you can type "%group.editbugs%".
+
+.. _list:
+
+Bug Lists
+=========
+
+The result of a search is a list of matching bugs.
+
+The format of the list is configurable. For example, it can be
+sorted by clicking the column headings. Other useful features can be
+accessed using the links at the bottom of the list:
+
+Long Format:
+ this gives you a large page with a non-editable summary of the fields
+ of each bug.
+
+XML:
+ get the buglist in the XML format.
+
+CSV:
+ get the buglist as comma-separated values, for import into e.g.
+ a spreadsheet.
+
+Feed:
+ get the buglist as an Atom feed. Copy this link into your
+ favorite feed reader. If you are using Firefox, you can also
+ save the list as a live bookmark by clicking the live bookmark
+ icon in the status bar. To limit the number of bugs in the feed,
+ add a limit=n parameter to the URL.
+
+iCalendar:
+ Get the buglist as an iCalendar file. Each bug is represented as a
+ to-do item in the imported calendar.
+
+Change Columns:
+ change the bug attributes which appear in the list.
+
+Change several bugs at once:
+ If your account is sufficiently empowered, and more than one bug
+ appear in the bug list, this link is displayed which lets you make
+ the same change to all the bugs in the list - for example, changing
+ their assignee.
+
+Send mail to bug assignees:
+ If more than one bug appear in the bug list and there are at least
+ two distinct bug assignees, this links is displayed which lets you
+ easily send a mail to the assignees of all bugs on the list.
+
+Edit Search:
+ If you didn't get exactly the results you were looking for, you can
+ return to the Query page through this link and make small revisions
+ to the query you just made so you get more accurate results.
+
+Remember Search As:
+ You can give a search a name and remember it; a link will appear
+ in your page footer giving you quick access to run it again later.
+
+.. _individual-buglists:
+
+Adding and Removing Tags on Bugs
+================================
+
+XXX Looks like you can no longer do this from search results; is that right?
+
+You can add and remove tags from individual bugs, which let you find and
+manage bugs more easily. Tags are per-user and so are only visible and editable
+by the user who created them. You can then run queries using tags as a criteria,
+either by using the Advanced Search form, or simply by typing "tag\:my_tag_name"
+in the QuickSearch box at the top (or bottom) of the page. Tags can also be
+displayed in buglists.
+
+This feature is useful when you want to keep track of several bugs, but
+for different reasons. Instead of adding yourself to the CC list of all
+these bugs and mixing all these reasons, you can now store these bugs in
+separate lists, e.g. ``Keep in mind``, ``Interesting bugs``,
+or ``Triage``. One big advantage of this way to manage bugs
+is that you can easily add or remove tags from bugs one by one.
+.. _user-preferences:
+
+User Preferences
+################
+
+Once logged in, you can customize various aspects of
+Bugzilla via the "Preferences" link in the page footer.
+The preferences are split into a number of tabs:
+
+.. _generalpreferences:
+
+General Preferences
+===================
+
+This tab allows you to change several default settings of Bugzilla.
+Administrators have the power to remove preferences from this list, so you
+may not see all the preferences available.
+
+Each preference should be self-explanatory.
+
+.. _emailpreferences:
+
+Email Preferences
+=================
+
+This tab allows you to enable or disable email notification on
+specific events.
+
+In general, users have almost complete control over how much (or
+how little) email Bugzilla sends them. If you want to receive the
+maximum amount of email possible, click the ``Enable All
+Mail`` button. If you don't want to receive any email from
+Bugzilla at all, click the ``Disable All Mail`` button.
+
+.. note:: A Bugzilla administrator can stop a user from receiving
+ bugmail by clicking the ``Bugmail Disabled`` checkbox
+ when editing the user account. This is a drastic step
+ best taken only for disabled accounts, as it overrides
+ the user's individual mail preferences.
+
+There are two global options -- ``Email me when someone
+asks me to set a flag`` and ``Email me when someone
+sets a flag I asked for``. These define how you want to
+receive bugmail with regards to flags. Their use is quite
+straightforward; enable the checkboxes if you want Bugzilla to
+send you mail under either of the above conditions.
+
+If you'd like to set your bugmail to something besides
+'Completely ON' and 'Completely OFF', the
+``Field/recipient specific options`` table
+allows you to do just that. The rows of the table
+define events that can happen to a bug -- things like
+attachments being added, new comments being made, the
+priority changing, etc. The columns in the table define
+your relationship with the bug - reporter, assignee, QA contact (if enabled)
+or CC list member.
+
+To fine-tune your bugmail, decide the events for which you want
+to receive bugmail; then decide if you want to receive it all
+the time (enable the checkbox for every column), or only when
+you have a certain relationship with a bug (enable the checkbox
+only for those columns). For example: if you didn't want to
+receive mail when someone added themselves to the CC list, you
+could uncheck all the boxes in the ``CC Field Changes``
+line. As another example, if you never wanted to receive email
+on bugs you reported unless the bug was resolved, you would
+un-check all boxes in the ``Reporter`` column
+except for the one on the ``The bug is resolved or
+verified`` row.
+
+.. note:: Bugzilla adds the ``X-Bugzilla-Reason`` header to
+ all bugmail it sends, describing the recipient's relationship
+ (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug.
+ This header can be used to do further client-side filtering.
+
+Bugzilla has a feature called ``User Watching``.
+When you enter one or more comma-delineated user accounts (usually email
+addresses) into the text entry box, you will receive a copy of all the
+bugmail those users are sent (security settings permitting).
+This powerful functionality enables seamless transitions as developers
+change projects or users go on holiday.
+
+Each user listed in the ``Users watching you`` field
+has you listed in their ``Users to watch`` list
+and can get bugmail according to your relationship to the bug and
+their ``Field/recipient specific options`` setting.
+
+Lastly, you can define a list of bugs on which you no longer wish to receive
+any email, ever. (You can also add bugs to this list individually by checking
+the "Ignore Bug Mail" checkbox on the bug page for that bug.) This is useful
+for ignoring bugs where you are the reporter, as that's a role it's not
+possible to stop having.
+
+.. _saved-searches:
+
+Saved Searches
+==============
+
+On this tab you can view and run any Saved Searches that you have
+created, and also any Saved Searches that other members of the group
+defined in the :guilabel:`querysharegroup` parameter have shared.
+Saved Searches can be added to the page footer from this screen.
+If somebody is sharing a Search with a group she or he is allowed to
+:ref:`assign users to <groups>`, the sharer may opt to have
+the Search show up in the footer of the group's direct members by default.
+
+.. _account-information:
+
+Account Information
+===================
+
+On this tab, you can change your basic account information,
+including your password, email address and real name. For security
+reasons, in order to change anything on this page you must type your
+*current* password into the ``Password``
+field at the top of the page.
+If you attempt to change your email address, a confirmation
+email is sent to both the old and new addresses, with a link to use to
+confirm the change. This helps to prevent account hijacking.
+
+.. _api-keys:
+
+API Keys
+========
+
+API Keys allow you to give a "token" to a web service so it can log in to
+Bugzilla as you without knowing your password. You can then revoke that token
+if you stop using the web service.
+
+.. _permissions:
+
+Permissions
+===========
+
+This is a purely informative page which outlines your current
+permissions on this installation of Bugzilla.
+
+A complete list of permissions in a default install of Bugzilla is below.
+Your administrator may have defined other permissions. Only users with
+*editusers* privileges can change the permissions of other users.
+
+admin
+ Indicates user is an Administrator.
+
+bz_canusewhineatothers
+ Indicates user can configure whine reports for other users.
+
+bz_canusewhines
+ Indicates user can configure whine reports for self.
+
+bz_quip_moderators
+ Indicates user can moderate quips.
+
+bz_sudoers
+ Indicates user can perform actions as other users.
+
+bz_sudo_protect
+ Indicates user cannot be impersonated by other users.
+
+canconfirm
+ Indicates user can confirm a bug or mark it a duplicate.
+
+creategroups
+ Indicates user can create and destroy groups.
+
+editbugs
+ Indicates user can edit all bug fields.
+
+editclassifications
+ Indicates user can create, destroy, and edit classifications.
+
+editcomponents
+ Indicates user can create, destroy, and edit products, components,
+ versions, milestones and flag types.
+
+editkeywords
+ Indicates user can create, destroy, and edit keywords.
+
+editusers
+ Indicates user can create, disable and edit users.
+
+tweakparams
+ Indicates user can change :ref:`Parameters <parameters>`.
--- /dev/null
+.. _reports-and-charts:
+
+Reports and Charts
+##################
+
+As well as the standard buglist, Bugzilla has two more ways of
+viewing sets of bugs. These are the reports (which give different
+views of the current state of the database) and charts (which plot
+the changes in particular sets of bugs over time.)
+
+.. _reports:
+
+Reports
+=======
+
+A report is a view of the current state of the bug database.
+
+You can run either an HTML-table-based report, or a graphical
+line/pie/bar-chart-based one. The two have different pages to
+define them, but are close cousins - once you've defined and
+viewed a report, you can switch between any of the different
+views of the data at will.
+
+Both report types are based on the idea of defining a set of bugs
+using the standard search interface, and then choosing some
+aspect of that set to plot on the horizontal and/or vertical axes.
+You can also get a form of 3-dimensional report by choosing to have
+multiple images or tables.
+
+So, for example, you could use the search form to choose "all
+bugs in the WorldControl product", and then plot their severity
+against their component to see which component had had the largest
+number of bad bugs reported against it.
+
+Once you've defined your parameters and hit "Generate Report",
+you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie
+is only available if you didn't define a vertical axis, as pie
+charts don't have one.) The other controls are fairly self-explanatory;
+you can change the size of the image if you find text is overwriting
+other text, or the bars are too thin to see.
+
+.. _charts:
+
+Charts
+======
+
+A chart is a view of the state of the bug database over time.
+
+Bugzilla currently has two charting systems - Old Charts and New
+Charts. Old Charts have been part of Bugzilla for a long time; they
+chart each status and resolution for each product, and that's all.
+They are deprecated, and going away soon - we won't say any more
+about them.
+New Charts are the future - they allow you to chart anything you
+can define as a search.
+
+.. note:: Both charting forms require the administrator to set up the
+ data-gathering script. If you can't see any charts, ask them whether
+ they have done so.
+
+An individual line on a chart is called a data set.
+All data sets are organised into categories and subcategories. The
+data sets that Bugzilla defines automatically use the Product name
+as a Category and Component names as Subcategories, but there is no
+need for you to follow that naming scheme with your own charts if
+you don't want to.
+
+Data sets may be public or private. Everyone sees public data sets in
+the list, but only their creator sees private data sets. Only
+administrators can make data sets public.
+No two data sets, even two private ones, can have the same set of
+category, subcategory and name. So if you are creating private data
+sets, one idea is to have the Category be your username.
+
+Creating Charts
+---------------
+
+You create a chart by selecting a number of data sets from the
+list, and pressing Add To List for each. In the List Of Data Sets
+To Plot, you can define the label that data set will have in the
+chart's legend, and also ask Bugzilla to Sum a number of data sets
+(e.g. you could Sum data sets representing RESOLVED, VERIFIED and
+CLOSED in a particular product to get a data set representing all
+the resolved bugs in that product.)
+
+If you've erroneously added a data set to the list, select it
+using the checkbox and click Remove. Once you add more than one
+data set, a "Grand Total" line
+automatically appears at the bottom of the list. If you don't want
+this, simply remove it as you would remove any other line.
+
+You may also choose to plot only over a certain date range, and
+to cumulate the results - that is, to plot each one using the
+previous one as a baseline, so the top line gives a sum of all
+the data sets. It's easier to try than to explain :-)
+
+Once a data set is in the list, one can also perform certain
+actions on it. For example, one can edit the
+data set's parameters (name, frequency etc.) if it's one you
+created or if you are an administrator.
+
+Once you are happy, click Chart This List to see the chart.
+
+.. _charts-new-series:
+
+Creating New Data Sets
+----------------------
+
+You may also create new data sets of your own. To do this,
+click the "create a new data set" link on the Create Chart page.
+This takes you to a search-like interface where you can define
+the search that Bugzilla will plot. At the bottom of the page,
+you choose the category, sub-category and name of your new
+data set.
+
+If you have sufficient permissions, you can make the data set public,
+and reduce the frequency of data collection to less than the default
+seven days.
+
+.. _pro-tips:
+
+Pro Tips
+########
+
+This section distills some Bugzilla tips and best practices
+that have been developed.
+
+Autolinkification
+=================
+
+Bugzilla comments are plain text - so typing <U> will
+produce less-than, U, greater-than rather than underlined text.
+However, Bugzilla will automatically make hyperlinks out of certain
+sorts of text in comments. For example, the text
+"http://www.bugzilla.org" will be turned into a link:
+`<http://www.bugzilla.org>`_.
+Other strings which get linkified in the obvious manner are:
+
++ bug 12345
+
++ comment 7
+
++ bug 23456, comment 53
+
++ attachment 4321
+
++ mailto\:george\@example.com
+
++ george\@example.com
+
++ ftp\://ftp.mozilla.org
+
++ Most other sorts of URL
+
+A corollary here is that if you type a bug number in a comment,
+you should put the word "bug" before it, so it gets autolinkified
+for the convenience of others.
+
+.. _commenting:
+
+Comments
+========
+
+If you are changing the fields on a bug, only comment if
+either you have something pertinent to say, or Bugzilla requires it.
+Otherwise, you may spam people unnecessarily with bug mail.
+To take an example: a user can set up their account to filter out messages
+where someone just adds themselves to the CC field of a bug
+(which happens a lot.) If you come along, add yourself to the CC field,
+and add a comment saying "Adding self to CC", then that person
+gets a pointless piece of mail they would otherwise have avoided.
+
+Don't use sigs in comments. Signing your name ("Bill") is acceptable,
+if you do it out of habit, but full mail/news-style
+four line ASCII art creations are not.
+
+If you feel a bug you filed was incorrectly marked as a
+DUPLICATE of another, please question it in your bug, not
+the bug it was duped to. Feel free to CC the person who duped it
+if they are not already CCed.
+.. _understanding:
+
+Understanding a Bug
+###################
+
+The core of Bugzilla is the screen which displays a particular
+bug. Note that the labels for most fields are hyperlinks;
+clicking them will take you to context-sensitive help on that
+particular field. Fields marked * may not be present on every
+installation of Bugzilla.
+
+*Summary:*
+ A one-sentence summary of the problem, displayed in the header next to
+ the bug number.
+
+*Status (and Resolution):*
+ These define exactly what state the bug is in - from not even
+ being confirmed as a bug, through to being fixed and the fix
+ confirmed by Quality Assurance. The different possible values for
+ Status and Resolution on your installation should be documented in the
+ context-sensitive help for those items.
+
+*Alias:*
+ A unique short text name for the bug, which can be used instead of the
+ bug number.
+
+*Product and Component*:
+ Bugs are divided up by Product and Component, with a Product
+ having one or more Components in it.
+
+*Version:*
+ The "Version" field is usually used for versions of a product which
+ have been released, and is set to indicate which versions of a
+ Component have the particular problem the bug report is
+ about.
+
+*Hardware (Platform and OS):*
+ These indicate the computing environment where the bug was
+ found.
+
+*Importance (Priority and Severity):*
+ The bug assignee uses the Priority field to prioritize his or her bugs.
+ It's a good idea not to change this on other people's bugs. The default
+ values are P1 to P5.
+
+ The Severity field indicates how severe the problem is - from blocker
+ ("application unusable") to trivial ("minor cosmetic issue"). You
+ can also use this field to indicate whether a bug is an enhancement
+ request.
+
+*\*Target Milestone:*
+ A future version by which the bug is to
+ be fixed. e.g. The Bugzilla Project's milestones for future
+ Bugzilla versions are 4.4, 5.0, 6.0, etc. Milestones are not
+ restricted to numbers, though - you can use any text strings, such
+ as dates.
+
+*Assigned To:*
+ The person responsible for fixing the bug.
+
+*\*QA Contact:*
+ The person responsible for quality assurance on this bug.
+
+*URL:*
+ A URL associated with the bug, if any.
+
+*\*Whiteboard:*
+ A free-form text area for adding short notes and tags to a bug.
+
+*Keywords:*
+ The administrator can define keywords which you can use to tag and
+ categorise bugs - e.g. ``crash`` or ``regression``.
+
+*Personal Tags:*
+ Unlike Keywords which are global and visible by all users, Personal Tags
+ are personal and can only be viewed and edited by their author. Editing
+ them won't send any notification to other users. Use them to tag and keep
+ track of bugs.
+
+*Dependencies (Depends On and Blocks):*
+ If this bug cannot be fixed unless other bugs are fixed (depends
+ on), or this bug stops other bugs being fixed (blocks), their
+ numbers are recorded here.
+
+ Clicking the ``Dependency tree`` link shows
+ the dependency relationships of the bug as a tree structure.
+ You can change how much depth to show, and you can hide resolved bugs
+ from this page. You can also collaps/expand dependencies for
+ each non-terminal bug on the tree view, using the [-]/[+] buttons that
+ appear before the summary.
+
+*Reported:*
+ The person who filed the bug, and the date and time they did it.
+
+*Modified:*
+ The date and time the bug was last changed.
+
+*CC List:*
+ A list of people who get mail when the bug changes.
+
+*Ignore Bug Mail:*
+ Set this if you want never to get bug mail from this bug again.
+
+*\*See Also:*
+ Bugs, in this Bugzilla or other Bugzillas or bug trackers, which are
+ related to this one.
+
+*Flags:*
+ A flag is a kind of status that can be set on bugs or attachments
+ to indicate that the bugs/attachments are in a certain state.
+ Each installation can define its own set of flags that can be set
+ on bugs or attachments. See :ref:`flags`.
+
+*\*Time Tracking:*
+ This form can be used for time tracking.
+ To use this feature, you have to be blessed group membership
+ specified by the ``timetrackinggroup`` parameter. See :ref:`time-tracking`
+ for more information.
+
+ Orig. Est.:
+ This field shows the original estimated time.
+ Current Est.:
+ This field shows the current estimated time.
+ This number is calculated from ``Hours Worked``
+ and ``Hours Left``.
+ Hours Worked:
+ This field shows the number of hours worked.
+ Hours Left:
+ This field shows the ``Current Est.`` -
+ ``Hours Worked``.
+ This value + ``Hours Worked`` will become the
+ new Current Est.
+ %Complete:
+ This field shows what percentage of the task is complete.
+ Gain:
+ This field shows the number of hours that the bug is ahead of the
+ ``Orig. Est.``.
+ Deadline:
+ This field shows the deadline for this bug.
+
+*Attachments:*
+ You can attach files (e.g. testcases or patches) to bugs. If there
+ are any attachments, they are listed in this section. See
+ :ref:`attachments` for more information.
+
+*Additional Comments:*
+ You can add your two cents to the bug discussion here, if you have
+ something worthwhile to say.
projects / thirdparty / bugzilla.git / commitdiff
