WIP
git-svn-id: svn://10.0.0.236/trunk@265704 18797224-902f-48f8-a5cc-f745e15eee43
This commit is contained in:
bzrmirror%bugzilla.org
parent
d297965d24
commit
13affbeced
@ -1 +1 @@
|
||||
9233
|
||||
9234
|
||||
@ -1 +1 @@
|
||||
715ec3d7af9693f40aa578391900b093c8c078bb
|
||||
db9c0d544dea0560294304116ae3ec53573043bc
|
||||
File diff suppressed because it is too large
Load Diff
@ -0,0 +1,431 @@
|
||||
.. _categorization:
|
||||
|
||||
==============================================================
|
||||
Classifications, Products, Components, Versions and Milestones
|
||||
==============================================================
|
||||
|
||||
Classifications
|
||||
###############
|
||||
|
||||
Classifications tend to be used in order to group several related
|
||||
products into one distinct entity.
|
||||
|
||||
The classifications layer is disabled by default; it can be turned
|
||||
on or off using the useclassification parameter,
|
||||
in the *Bug Fields* section of the edit parameters screen.
|
||||
|
||||
Access to the administration of classifications is controlled using
|
||||
the *editclassifications* system group, which defines
|
||||
a privilege for creating, destroying, and editing classifications.
|
||||
|
||||
When activated, classifications will introduce an additional
|
||||
step when filling bugs (dedicated to classification selection), and they
|
||||
will also appear in the advanced search form.
|
||||
|
||||
.. _products:
|
||||
|
||||
Products
|
||||
########
|
||||
|
||||
Products typically represent real-world
|
||||
shipping products. Products can be given
|
||||
:ref:`classifications`.
|
||||
For example, if a company makes computer games,
|
||||
they could have a classification of "Games", and a separate
|
||||
product for each game. This company might also have a
|
||||
``Common`` product for units of technology used
|
||||
in multiple games, and perhaps a few special products that
|
||||
represent items that are not actually shipping products
|
||||
(for example, "Website", or "Administration").
|
||||
|
||||
Many of Bugzilla's settings are configurable on a per-product
|
||||
basis. The number of ``votes`` available to
|
||||
users is set per-product, as is the number of votes
|
||||
required to move a bug automatically from the UNCONFIRMED
|
||||
status to the CONFIRMED status.
|
||||
|
||||
When creating or editing products the following options are
|
||||
available:
|
||||
|
||||
Product
|
||||
The name of the product
|
||||
|
||||
Description
|
||||
A brief description of the product
|
||||
|
||||
Default milestone
|
||||
Select the default milestone for this product.
|
||||
|
||||
Closed for bug entry
|
||||
Select this box to prevent new bugs from being
|
||||
entered against this product.
|
||||
|
||||
Maximum votes per person
|
||||
Maximum votes a user is allowed to give for this
|
||||
product
|
||||
|
||||
Maximum votes a person can put on a single bug
|
||||
Maximum votes a user is allowed to give for this
|
||||
product in a single bug
|
||||
|
||||
Confirmation threshold
|
||||
Number of votes needed to automatically remove any
|
||||
bug against this product from the UNCONFIRMED state
|
||||
|
||||
Version
|
||||
Specify which version of the product bugs will be
|
||||
entered against.
|
||||
|
||||
Create chart datasets for this product
|
||||
Select to make chart datasets available for this product.
|
||||
|
||||
When editing a product there is also a link to edit Group Access Controls,
|
||||
see :ref:`product-group-controls`.
|
||||
|
||||
.. _create-product:
|
||||
|
||||
Creating New Products
|
||||
=====================
|
||||
|
||||
To create a new product:
|
||||
|
||||
#. Select ``Administration`` from the footer and then
|
||||
choose ``Products`` from the main administration page.
|
||||
|
||||
#. Select the ``Add`` link in the bottom right.
|
||||
|
||||
#. Enter the name of the product and a description. The
|
||||
Description field may contain HTML.
|
||||
|
||||
#. When the product is created, Bugzilla will give a message
|
||||
stating that a component must be created before any bugs can
|
||||
be entered against the new product. Follow the link to create
|
||||
a new component. See :ref:`components` for more
|
||||
information.
|
||||
|
||||
.. _edit-products:
|
||||
|
||||
Editing Products
|
||||
================
|
||||
|
||||
To edit an existing product, click the "Products" link from the
|
||||
"Administration" page. If the 'useclassification' parameter is
|
||||
turned on, a table of existing classifications is displayed,
|
||||
including an "Unclassified" category. The table indicates how many products
|
||||
are in each classification. Click on the classification name to see its
|
||||
products. If the 'useclassification' parameter is not in use, the table
|
||||
lists all products directly. The product table summarizes the information
|
||||
about the product defined
|
||||
when the product was created. Click on the product name to edit these
|
||||
properties, and to access links to other product attributes such as the
|
||||
product's components, versions, milestones, and group access controls.
|
||||
|
||||
.. _comps-vers-miles-products:
|
||||
|
||||
Adding or Editing Components, Versions and Target Milestones
|
||||
============================================================
|
||||
|
||||
To edit existing, or add new, Components, Versions or Target Milestones
|
||||
to a Product, select the "Edit Components", "Edit Versions" or "Edit
|
||||
Milestones" links from the "Edit Product" page. A table of existing
|
||||
Components, Versions or Milestones is displayed. Click on a item name
|
||||
to edit the properties of that item. Below the table is a link to add
|
||||
a new Component, Version or Milestone.
|
||||
|
||||
For more information on components, see :ref:`components`.
|
||||
|
||||
For more information on versions, see :ref:`versions`.
|
||||
|
||||
For more information on milestones, see :ref:`milestones`.
|
||||
|
||||
.. _product-group-controls:
|
||||
|
||||
Assigning Group Controls to Products
|
||||
====================================
|
||||
|
||||
On the ``Edit Product`` page, there is a link called
|
||||
``Edit Group Access Controls``. The settings on this page
|
||||
control the relationship of the groups to the product being edited.
|
||||
|
||||
Group Access Controls are an important aspect of using groups for
|
||||
isolating products and restricting access to bugs filed against those
|
||||
products. For more information on groups, including how to create, edit
|
||||
add users to, and alter permission of, see :ref:`groups`.
|
||||
|
||||
After selecting the "Edit Group Access Controls" link from the "Edit
|
||||
Product" page, a table containing all user-defined groups for this
|
||||
Bugzilla installation is displayed. The system groups that are created
|
||||
when Bugzilla is installed are not applicable to Group Access Controls.
|
||||
Below is description of what each of these fields means.
|
||||
|
||||
Groups may be applicable (e.g bugs in this product can be associated
|
||||
with this group) , default (e.g. bugs in this product are in this group
|
||||
by default), and mandatory (e.g. bugs in this product must be associated
|
||||
with this group) for each product. Groups can also control access
|
||||
to bugs for a given product, or be used to make bugs for a product
|
||||
totally read-only unless the group restrictions are met. The best way to
|
||||
understand these relationships is by example. See
|
||||
:ref:`group-control-examples` for examples of
|
||||
product and group relationships.
|
||||
|
||||
.. note:: Products and Groups are not limited to a one-to-one relationship.
|
||||
Multiple groups can be associated with the same product, and groups
|
||||
can be associated with more than one product.
|
||||
|
||||
If any group has *Entry* selected, then the
|
||||
product will restrict bug entry to only those users
|
||||
who are members of *all* the groups with
|
||||
*Entry* selected.
|
||||
|
||||
If any group has *Canedit* selected,
|
||||
then the product will be read-only for any users
|
||||
who are not members of *all* of the groups with
|
||||
*Canedit* selected. *Only* users who
|
||||
are members of all the *Canedit* groups
|
||||
will be able to edit bugs for this product. This is an additional
|
||||
restriction that enables finer-grained control over products rather
|
||||
than just all-or-nothing access levels.
|
||||
|
||||
The following settings let you
|
||||
choose privileges on a *per-product basis*.
|
||||
This is a convenient way to give privileges to
|
||||
some users for some products only, without having
|
||||
to give them global privileges which would affect
|
||||
all products.
|
||||
|
||||
Any group having *editcomponents*
|
||||
selected allows users who are in this group to edit all
|
||||
aspects of this product, including components, milestones
|
||||
and versions.
|
||||
|
||||
Any group having *canconfirm* selected
|
||||
allows users who are in this group to confirm bugs
|
||||
in this product.
|
||||
|
||||
Any group having *editbugs* selected allows
|
||||
users who are in this group to edit all fields of
|
||||
bugs in this product.
|
||||
|
||||
The *MemberControl* and
|
||||
*OtherControl* are used in tandem to determine which
|
||||
bugs will be placed in this group. The only allowable combinations of
|
||||
these two parameters are listed in a table on the "Edit Group Access Controls"
|
||||
page. Consult this table for details on how these fields can be used.
|
||||
Examples of different uses are described below.
|
||||
|
||||
.. _group-control-examples:
|
||||
|
||||
Common Applications of Group Controls
|
||||
=====================================
|
||||
|
||||
The use of groups is best explained by providing examples that illustrate
|
||||
configurations for common use cases. The examples follow a common syntax:
|
||||
*Group: Entry, MemberControl, OtherControl, CanEdit,
|
||||
EditComponents, CanConfirm, EditBugs*. Where "Group" is the name
|
||||
of the group being edited for this product. The other fields all
|
||||
correspond to the table on the "Edit Group Access Controls" page. If any
|
||||
of these options are not listed, it means they are not checked.
|
||||
|
||||
Basic Product/Group Restriction
|
||||
-------------------------------
|
||||
|
||||
Suppose there is a product called "Bar". The
|
||||
"Bar" product can only have bugs entered against it by users in the
|
||||
group "Foo". Additionally, bugs filed against product "Bar" must stay
|
||||
restricted to users to "Foo" at all times. Furthermore, only members
|
||||
of group "Foo" can edit bugs filed against product "Bar", even if other
|
||||
users could see the bug. This arrangement would achieved by the
|
||||
following:
|
||||
|
||||
::
|
||||
|
||||
Product Bar:
|
||||
foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
|
||||
|
||||
Perhaps such strict restrictions are not needed for product "Bar". A
|
||||
more lenient way to configure product "Bar" and group "Foo" would be:
|
||||
|
||||
::
|
||||
|
||||
Product Bar:
|
||||
foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS
|
||||
|
||||
The above indicates that for product "Bar", members of group "Foo" can
|
||||
enter bugs. Any one with permission to edit a bug against product "Bar"
|
||||
can put the bug
|
||||
in group "Foo", even if they themselves are not in "Foo". Anyone in group
|
||||
"Foo" can edit all aspects of the components of product "Bar", can confirm
|
||||
bugs against product "Bar", and can edit all fields of any bug against
|
||||
product "Bar".
|
||||
|
||||
General User Access With Security Group
|
||||
---------------------------------------
|
||||
|
||||
To permit any user to file bugs against "Product A",
|
||||
and to permit any user to submit those bugs into a
|
||||
group called "Security":
|
||||
|
||||
::
|
||||
|
||||
Product A:
|
||||
security: SHOWN/SHOWN
|
||||
|
||||
General User Access With A Security Product
|
||||
-------------------------------------------
|
||||
|
||||
To permit any user to file bugs against product called "Security"
|
||||
while keeping those bugs from becoming visible to anyone
|
||||
outside the group "SecurityWorkers" (unless a member of the
|
||||
"SecurityWorkers" group removes that restriction):
|
||||
|
||||
::
|
||||
|
||||
Product Security:
|
||||
securityworkers: DEFAULT/MANDATORY
|
||||
|
||||
Product Isolation With a Common Group
|
||||
-------------------------------------
|
||||
|
||||
To permit users of "Product A" to access the bugs for
|
||||
"Product A", users of "Product B" to access the bugs for
|
||||
"Product B", and support staff, who are members of the "Support
|
||||
Group" to access both, three groups are needed:
|
||||
|
||||
#. Support Group: Contains members of the support staff.
|
||||
|
||||
#. AccessA Group: Contains users of product A and the Support group.
|
||||
|
||||
#. AccessB Group: Contains users of product B and the Support group.
|
||||
|
||||
Once these three groups are defined, the product group controls
|
||||
can be set to:
|
||||
|
||||
::
|
||||
|
||||
Product A:
|
||||
AccessA: ENTRY, MANDATORY/MANDATORY
|
||||
Product B:
|
||||
AccessB: ENTRY, MANDATORY/MANDATORY
|
||||
|
||||
Perhaps the "Support Group" wants more control. For example,
|
||||
the "Support Group" could be permitted to make bugs inaccessible to
|
||||
users of both groups "AccessA" and "AccessB".
|
||||
Then, the "Support Group" could be permitted to publish
|
||||
bugs relevant to all users in a third product (let's call it
|
||||
"Product Common") that is read-only
|
||||
to anyone outside the "Support Group". In this way the "Support Group"
|
||||
could control bugs that should be seen by both groups.
|
||||
That configuration would be:
|
||||
|
||||
::
|
||||
|
||||
Product A:
|
||||
AccessA: ENTRY, MANDATORY/MANDATORY
|
||||
Support: SHOWN/NA
|
||||
Product B:
|
||||
AccessB: ENTRY, MANDATORY/MANDATORY
|
||||
Support: SHOWN/NA
|
||||
Product Common:
|
||||
Support: ENTRY, DEFAULT/MANDATORY, CANEDIT
|
||||
|
||||
Make a Product Read Only
|
||||
------------------------
|
||||
|
||||
Sometimes a product is retired and should no longer have
|
||||
new bugs filed against it (for example, an older version of a software
|
||||
product that is no longer supported). A product can be made read-only
|
||||
by creating a group called "readonly" and adding products to the
|
||||
group as needed:
|
||||
|
||||
::
|
||||
|
||||
Product A:
|
||||
ReadOnly: ENTRY, NA/NA, CANEDIT
|
||||
|
||||
.. note:: For more information on Groups outside of how they relate to products
|
||||
see :ref:`groups`.
|
||||
|
||||
.. _components:
|
||||
|
||||
Components
|
||||
##########
|
||||
|
||||
Components are subsections of a Product. E.g. the computer game
|
||||
you are designing may have a "UI"
|
||||
component, an "API" component, a "Sound System" component, and a
|
||||
"Plugins" component, each overseen by a different programmer. It
|
||||
often makes sense to divide Components in Bugzilla according to the
|
||||
natural divisions of responsibility within your Product or
|
||||
company.
|
||||
|
||||
Each component has a default assignee and (if you turned it on in the parameters),
|
||||
a QA Contact. The default assignee should be the primary person who fixes bugs in
|
||||
that component. The QA Contact should be the person who will ensure
|
||||
these bugs are completely fixed. The Assignee, QA Contact, and Reporter
|
||||
will get email when new bugs are created in this Component and when
|
||||
these bugs change. Default Assignee and Default QA Contact fields only
|
||||
dictate the
|
||||
*default assignments*;
|
||||
these can be changed on bug submission, or at any later point in
|
||||
a bug's life.
|
||||
|
||||
To create a new Component:
|
||||
|
||||
#. Select the ``Edit components`` link
|
||||
from the ``Edit product`` page
|
||||
|
||||
#. Select the ``Add`` link in the bottom right.
|
||||
|
||||
#. Fill out the ``Component`` field, a
|
||||
short ``Description``, the
|
||||
``Default Assignee``, ``Default CC List``
|
||||
and ``Default QA Contact`` (if enabled).
|
||||
The ``Component Description`` field may contain a
|
||||
limited subset of HTML tags. The ``Default Assignee``
|
||||
field must be a login name already existing in the Bugzilla database.
|
||||
|
||||
.. _versions:
|
||||
|
||||
Versions
|
||||
########
|
||||
|
||||
Versions are the revisions of the product, such as "Flinders
|
||||
3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select
|
||||
field; the usual practice is to select the earliest version known to have
|
||||
the bug.
|
||||
|
||||
To create and edit Versions:
|
||||
|
||||
#. From the "Edit product" screen, select "Edit Versions"
|
||||
|
||||
#. You will notice that the product already has the default
|
||||
version "undefined". Click the "Add" link in the bottom right.
|
||||
|
||||
#. Enter the name of the Version. This field takes text only.
|
||||
Then click the "Add" button.
|
||||
|
||||
.. _milestones:
|
||||
|
||||
Milestones
|
||||
##########
|
||||
|
||||
Milestones are "targets" that you plan to get a bug fixed by. For
|
||||
example, you have a bug that you plan to fix for your 3.0 release, it
|
||||
would be assigned the milestone of 3.0.
|
||||
|
||||
.. note:: Milestone options will only appear for a Product if you turned
|
||||
on the "usetargetmilestone" parameter in the "Bug Fields" tab of the
|
||||
"Parameters" page.
|
||||
|
||||
To create new Milestones, and set Default Milestones:
|
||||
|
||||
#. Select "Edit milestones" from the "Edit product" page.
|
||||
|
||||
#. Select "Add" in the bottom right corner.
|
||||
|
||||
#. Enter the name of the Milestone in the "Milestone" field. You
|
||||
can optionally set the "sortkey", which is a positive or negative
|
||||
number (-32768 to 32767) that defines where in the list this particular
|
||||
milestone appears. This is because milestones often do not
|
||||
occur in alphanumeric order For example, "Future" might be
|
||||
after "Release 1.2". Select "Add".
|
||||
198
mozilla/webtools/bugzilla/docs/en/rst/administering/fields.rst
Normal file
198
mozilla/webtools/bugzilla/docs/en/rst/administering/fields.rst
Normal file
@ -0,0 +1,198 @@
|
||||
.. _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
|
||||
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.
|
||||
|
||||
.. note:: Before adding a Custom Field, make sure that Bugzilla cannot already
|
||||
do the desired behavior. Many Bugzilla options are not enabled by
|
||||
default, and many times Administrators find that simply enabling
|
||||
certain options that already exist is sufficient.
|
||||
|
||||
Administrators can manage Custom Fields using the
|
||||
``Custom Fields`` link on the Administration page. The Custom
|
||||
Fields administration page displays a list of Custom Fields, if any exist,
|
||||
and a link to "Add a new custom field".
|
||||
|
||||
.. _add-custom-fields:
|
||||
|
||||
Adding Custom Fields
|
||||
====================
|
||||
|
||||
To add a new Custom Field, click the "Add a new custom field" link. This
|
||||
page displays several options for the new field, described below.
|
||||
|
||||
The following attributes must be set for each new custom field:
|
||||
|
||||
- *Name:*
|
||||
The name of the field in the database, used internally. This name
|
||||
MUST begin with ``cf_`` to prevent confusion with
|
||||
standard fields. If this string is omitted, it will
|
||||
be automatically added to the name entered.
|
||||
|
||||
- *Description:*
|
||||
A brief string which is used as the label for this Custom Field.
|
||||
That is the string that users will see, and should be
|
||||
short and explicit.
|
||||
|
||||
- *Type:*
|
||||
The type of field to create. There are
|
||||
several types available:
|
||||
|
||||
Bug ID:
|
||||
A field where you can enter the ID of another bug from
|
||||
the same Bugzilla installation. To point to a bug in a remote
|
||||
installation, use the See Also field instead.
|
||||
Large Text Box:
|
||||
A multiple line box for entering free text.
|
||||
Free Text:
|
||||
A single line box for entering free text.
|
||||
Multiple-Selection Box:
|
||||
A list box where multiple options
|
||||
can be selected. After creating this field, it must be edited
|
||||
to add the selection options. See
|
||||
:ref:`edit-values-list` for information about
|
||||
editing legal values.
|
||||
Drop Down:
|
||||
A list box where only one option can be selected.
|
||||
After creating this field, it must be edited to add the
|
||||
selection options. See
|
||||
:ref:`edit-values-list` for information about
|
||||
editing legal values.
|
||||
Date/Time:
|
||||
A date field. This field appears with a
|
||||
calendar widget for choosing the date.
|
||||
|
||||
- *Sortkey:*
|
||||
Integer that determines in which order Custom Fields are
|
||||
displayed in the User Interface, especially when viewing a bug.
|
||||
Fields with lower values are displayed first.
|
||||
|
||||
- *Reverse Relationship Description:*
|
||||
When the custom field is of type ``Bug ID``, you can
|
||||
enter text here which will be used as label in the referenced
|
||||
bug to list bugs which point to it. This gives you the ability
|
||||
to have a mutual relationship between two bugs.
|
||||
|
||||
- *Can be set on bug creation:*
|
||||
Boolean that determines whether this field can be set on
|
||||
bug creation. If not selected, then a bug must be created
|
||||
before this field can be set. See :ref:`bugreports`
|
||||
for information about filing bugs.
|
||||
|
||||
- *Displayed in bugmail for new bugs:*
|
||||
Boolean that determines whether the value set on this field
|
||||
should appear in bugmail when the bug is filed. This attribute
|
||||
has no effect if the field cannot be set on bug creation.
|
||||
|
||||
- *Is obsolete:*
|
||||
Boolean that determines whether this field should
|
||||
be displayed at all. Obsolete Custom Fields are hidden.
|
||||
|
||||
- *Is mandatory:*
|
||||
Boolean that determines whether this field must be set.
|
||||
For single and multi-select fields, this means that a (non-default)
|
||||
value must be selected, and for text and date fields, some text
|
||||
must be entered.
|
||||
|
||||
- *Field only appears when:*
|
||||
A custom field can be made visible when some criteria is met.
|
||||
For instance, when the bug belongs to one or more products,
|
||||
or when the bug is of some given severity. If left empty, then
|
||||
the custom field will always be visible, in all bugs.
|
||||
|
||||
- *Field that controls the values that appear in this field:*
|
||||
When the custom field is of type ``Drop Down`` or
|
||||
``Multiple-Selection Box``, you can restrict the
|
||||
availability of the values of the custom field based on the
|
||||
value of another field. This criteria is independent of the
|
||||
criteria used in the ``Field only appears when``
|
||||
setting. For instance, you may decide that some given value
|
||||
``valueY`` is only available when the bug status
|
||||
is RESOLVED while the value ``valueX`` should
|
||||
always be listed.
|
||||
Once you have selected the field which should control the
|
||||
availability of the values of this custom field, you can
|
||||
edit values of this custom field to set the criteria, see
|
||||
:ref:`edit-values-list`.
|
||||
|
||||
.. _edit-custom-fields:
|
||||
|
||||
Editing Custom Fields
|
||||
=====================
|
||||
|
||||
As soon as a Custom Field is created, its name and type cannot be
|
||||
changed. If this field is a drop down menu, its legal values can
|
||||
be set as described in :ref:`edit-values-list`. All
|
||||
other attributes can be edited as described above.
|
||||
|
||||
.. _delete-custom-fields:
|
||||
|
||||
Deleting Custom Fields
|
||||
======================
|
||||
|
||||
Only custom fields which are marked as obsolete, and which never
|
||||
have been used, can be deleted completely (else the integrity
|
||||
of the bug history would be compromised). For custom fields marked
|
||||
as obsolete, a "Delete" link will appear in the ``Action``
|
||||
column. If the custom field has been used in the past, the deletion
|
||||
will be rejected. But marking the field as obsolete is sufficient
|
||||
to hide it from the user interface entirely.
|
||||
|
||||
.. _edit-values:
|
||||
|
||||
Legal Values
|
||||
############
|
||||
|
||||
Legal values for the operating system, platform, bug priority and
|
||||
severity, custom fields of type ``Drop Down`` and
|
||||
``Multiple-Selection Box`` (see :ref:`custom-fields`),
|
||||
as well as the list of valid bug statuses and resolutions can be
|
||||
customized from the same interface. You can add, edit, disable and
|
||||
remove values which can be used with these fields.
|
||||
|
||||
.. _edit-values-list:
|
||||
|
||||
Viewing/Editing legal values
|
||||
============================
|
||||
|
||||
Editing legal values requires ``admin`` privileges.
|
||||
Select "Field Values" from the Administration page. A list of all
|
||||
fields, both system fields and Custom Fields, for which legal values
|
||||
can be edited appears. Click a field name to edit its legal values.
|
||||
|
||||
There is no limit to how many values a field can have, but each value
|
||||
must be unique to that field. The sortkey is important to display these
|
||||
values in the desired order.
|
||||
|
||||
When the availability of the values of a custom field is controlled
|
||||
by another field, you can select from here which value of the other field
|
||||
must be set for the value of the custom field to appear.
|
||||
|
||||
.. _edit-values-delete:
|
||||
|
||||
Deleting legal values
|
||||
=====================
|
||||
|
||||
Legal values from Custom Fields can be deleted, but only if the
|
||||
following two conditions are respected:
|
||||
|
||||
#. The value is not used by default for the field.
|
||||
|
||||
#. No bug is currently using this value.
|
||||
|
||||
If any of these conditions is not respected, the value cannot be deleted.
|
||||
The only way to delete these values is to reassign bugs to another value
|
||||
and to set another value as default for the field.
|
||||
|
||||
@ -0,0 +1,371 @@
|
||||
.. _flags:
|
||||
|
||||
Flags
|
||||
#####
|
||||
|
||||
Flags are a way to attach a specific status to a bug or attachment,
|
||||
either ``+`` or ``-``. The meaning of these symbols depends on the text
|
||||
the flag itself, but contextually they could mean pass/fail,
|
||||
accept/reject, approved/denied, or even a simple yes/no. If your site
|
||||
allows requestable flags, then users may set a flag to ``?`` as a
|
||||
request to another user that they look at the bug/attachment, and set
|
||||
the flag to its correct status.
|
||||
|
||||
.. _flags-simpleexample:
|
||||
|
||||
A Simple Example
|
||||
================
|
||||
|
||||
A developer might want to ask their manager,
|
||||
``Should we fix this bug before we release version 2.0?``
|
||||
They might want to do this for a *lot* of bugs,
|
||||
so it would be nice to streamline the process...
|
||||
|
||||
In Bugzilla, it would work this way:
|
||||
|
||||
#. The Bugzilla administrator creates a flag type called
|
||||
``blocking2.0`` that shows up on all bugs in
|
||||
your product.
|
||||
It shows up on the ``Show Bug`` screen
|
||||
as the text ``blocking2.0`` with a drop-down box next
|
||||
to it. The drop-down box contains four values: an empty space,
|
||||
``?``, ``-``, and ``+``.
|
||||
|
||||
#. The developer sets the flag to ``?``.
|
||||
|
||||
#. The manager sees the ``blocking2.0``
|
||||
flag with a ``?`` value.
|
||||
|
||||
#. If the manager thinks the feature should go into the product
|
||||
before version 2.0 can be released, he sets the flag to
|
||||
``+``. Otherwise, he sets it to ``-``.
|
||||
|
||||
#. Now, every Bugzilla user who looks at the bug knows whether or
|
||||
not the bug needs to be fixed before release of version 2.0.
|
||||
|
||||
.. _flags-about:
|
||||
|
||||
About Flags
|
||||
===========
|
||||
|
||||
.. _flag-values:
|
||||
|
||||
Values
|
||||
------
|
||||
|
||||
Flags can have three values:
|
||||
|
||||
``?``
|
||||
A user is requesting that a status be set. (Think of it as 'A question is being asked'.)
|
||||
|
||||
``-``
|
||||
The status has been set negatively. (The question has been answered ``no``.)
|
||||
|
||||
``+``
|
||||
The status has been set positively.
|
||||
(The question has been answered ``yes``.)
|
||||
|
||||
Actually, there's a fourth value a flag can have --
|
||||
``unset`` -- which shows up as a blank space. This
|
||||
just means that nobody has expressed an opinion (or asked
|
||||
someone else to express an opinion) about this bug or attachment.
|
||||
|
||||
.. _flag-askto:
|
||||
|
||||
Using flag requests
|
||||
===================
|
||||
|
||||
If a flag has been defined as 'requestable', and a user has enough privileges
|
||||
to request it (see below), the user can set the flag's status to ``?``.
|
||||
This status indicates that someone (a.k.a. ``the requester``) is asking
|
||||
someone else to set the flag to either ``+`` or ``-``.
|
||||
|
||||
If a flag has been defined as 'specifically requestable',
|
||||
a text box will appear next to the flag into which the requester may
|
||||
enter a Bugzilla username. That named person (a.k.a. ``the requestee``)
|
||||
will receive an email notifying them of the request, and pointing them
|
||||
to the bug/attachment in question.
|
||||
|
||||
If a flag has *not* been defined as 'specifically requestable',
|
||||
then no such text-box will appear. A request to set this flag cannot be made of
|
||||
any specific individual, but must be asked ``to the wind``.
|
||||
A requester may ``ask the wind`` on any flag simply by leaving the text-box blank.
|
||||
|
||||
.. _flag-types:
|
||||
|
||||
Two Types of Flags
|
||||
==================
|
||||
|
||||
Flags can go in two places: on an attachment, or on a bug.
|
||||
|
||||
.. _flag-type-attachment:
|
||||
|
||||
Attachment Flags
|
||||
----------------
|
||||
|
||||
Attachment flags are used to ask a question about a specific
|
||||
attachment on a bug.
|
||||
|
||||
Many Bugzilla installations use this to
|
||||
request that one developer ``review`` another
|
||||
developer's code before they check it in. They attach the code to
|
||||
a bug report, and then set a flag on that attachment called
|
||||
``review`` to
|
||||
``review?boss@domain.com``.
|
||||
boss@domain.com is then notified by email that
|
||||
he has to check out that attachment and approve it or deny it.
|
||||
|
||||
For a Bugzilla user, attachment flags show up in three places:
|
||||
|
||||
#. On the list of attachments in the ``Show Bug``
|
||||
screen, you can see the current state of any flags that
|
||||
have been set to ?, +, or -. You can see who asked about
|
||||
the flag (the requester), and who is being asked (the
|
||||
requestee).
|
||||
|
||||
#. When you ``Edit`` an attachment, you can
|
||||
see any settable flag, along with any flags that have
|
||||
already been set. This ``Edit Attachment``
|
||||
screen is where you set flags to ?, -, +, or unset them.
|
||||
|
||||
#. Requests are listed in the ``Request Queue``, which
|
||||
is accessible from the ``My Requests`` link (if you are
|
||||
logged in) or ``Requests`` link (if you are logged out)
|
||||
visible in the footer of all pages.
|
||||
|
||||
.. _flag-type-bug:
|
||||
|
||||
Bug Flags
|
||||
---------
|
||||
|
||||
Bug flags are used to set a status on the bug itself. You can
|
||||
see Bug Flags in the ``Show Bug`` and ``Requests``
|
||||
screens, as described above.
|
||||
|
||||
Only users with enough privileges (see below) may set flags on bugs.
|
||||
This doesn't necessarily include the assignee, reporter, or users with the
|
||||
``editbugs`` permission.
|
||||
|
||||
.. _flags-admin:
|
||||
|
||||
Administering Flags
|
||||
===================
|
||||
|
||||
If you have the ``editcomponents`` permission, you can
|
||||
edit Flag Types from the main administration page. Clicking the
|
||||
``Flags`` link will bring you to the ``Administer
|
||||
Flag Types`` page. Here, you can select whether you want
|
||||
to create (or edit) a Bug flag, or an Attachment flag.
|
||||
|
||||
No matter which you choose, the interface is the same, so we'll
|
||||
just go over it once.
|
||||
|
||||
.. _flags-edit:
|
||||
|
||||
Editing a Flag
|
||||
--------------
|
||||
|
||||
To edit a flag's properties, just click the flag's name.
|
||||
That will take you to the same
|
||||
form as described below (:ref:`flags-create`).
|
||||
|
||||
.. _flags-create:
|
||||
|
||||
Creating a Flag
|
||||
---------------
|
||||
|
||||
When you click on the ``Create a Flag Type for...``
|
||||
link, you will be presented with a form. Here is what the fields in
|
||||
the form mean:
|
||||
|
||||
.. _flags-create-field-name:
|
||||
|
||||
Name
|
||||
~~~~
|
||||
|
||||
This is the name of the flag. This will be displayed
|
||||
to Bugzilla users who are looking at or setting the flag.
|
||||
The name may contain any valid Unicode characters except commas
|
||||
and spaces.
|
||||
|
||||
.. _flags-create-field-description:
|
||||
|
||||
Description
|
||||
~~~~~~~~~~~
|
||||
|
||||
The description describes the flag in more detail. It is visible
|
||||
in a tooltip when hovering over a flag either in the ``Show Bug``
|
||||
or ``Edit Attachment`` pages. This field can be as
|
||||
long as you like, and can contain any character you want.
|
||||
|
||||
.. _flags-create-field-category:
|
||||
|
||||
Category
|
||||
~~~~~~~~
|
||||
|
||||
Default behaviour for a newly-created flag is to appear on
|
||||
products and all components, which is why ``__Any__:__Any__``
|
||||
is already entered in the ``Inclusions`` box.
|
||||
If this is not your desired behaviour, you must either set some
|
||||
exclusions (for products on which you don't want the flag to appear),
|
||||
or you must remove ``__Any__:__Any__`` from the Inclusions box
|
||||
and define products/components specifically for this flag.
|
||||
|
||||
To create an Inclusion, select a Product from the top drop-down box.
|
||||
You may also select a specific component from the bottom drop-down box.
|
||||
(Setting ``__Any__`` for Product translates to,
|
||||
``all the products in this Bugzilla``.
|
||||
Selecting ``__Any__`` in the Component field means
|
||||
``all components in the selected product.``)
|
||||
Selections made, press ``Include``, and your
|
||||
Product/Component pairing will show up in the ``Inclusions`` box on the right.
|
||||
|
||||
To create an Exclusion, the process is the same; select a Product from the
|
||||
top drop-down box, select a specific component if you want one, and press
|
||||
``Exclude``. The Product/Component pairing will show up in the
|
||||
``Exclusions`` box on the right.
|
||||
|
||||
This flag *will* and *can* be set for any
|
||||
products/components that appearing in the ``Inclusions`` box
|
||||
(or which fall under the appropriate ``__Any__``).
|
||||
This flag *will not* appear (and therefore cannot be set) on
|
||||
any products appearing in the ``Exclusions`` box.
|
||||
*IMPORTANT: Exclusions override inclusions.*
|
||||
|
||||
You may select a Product without selecting a specific Component,
|
||||
but you can't select a Component without a Product, or to select a
|
||||
Component that does not belong to the named Product. If you do so,
|
||||
Bugzilla will display an error message, even if all your products
|
||||
have a component by that name.
|
||||
|
||||
*Example:* Let's say you have a product called
|
||||
``Jet Plane`` that has thousands of components. You want
|
||||
to be able to ask if a problem should be fixed in the next model of
|
||||
plane you release. We'll call the flag ``fixInNext``.
|
||||
But, there's one component in ``Jet Plane,``
|
||||
called ``Pilot.`` It doesn't make sense to release a
|
||||
new pilot, so you don't want to have the flag show up in that component.
|
||||
So, you include ``Jet Plane:__Any__`` and you exclude
|
||||
``Jet Plane:Pilot``.
|
||||
|
||||
.. _flags-create-field-sortkey:
|
||||
|
||||
Sort Key
|
||||
~~~~~~~~
|
||||
|
||||
Flags normally show up in alphabetical order. If you want them to
|
||||
show up in a different order, you can use this key set the order on each flag.
|
||||
Flags with a lower sort key will appear before flags with a higher
|
||||
sort key. Flags that have the same sort key will be sorted alphabetically,
|
||||
but they will still be after flags with a lower sort key, and before flags
|
||||
with a higher sort key.
|
||||
|
||||
*Example:* I have AFlag (Sort Key 100), BFlag (Sort Key 10),
|
||||
CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in
|
||||
the order: DFlag, BFlag, CFlag, AFlag.
|
||||
|
||||
.. _flags-create-field-active:
|
||||
|
||||
Active
|
||||
~~~~~~
|
||||
|
||||
Sometimes, you might want to keep old flag information in the
|
||||
Bugzilla database, but stop users from setting any new flags of this type.
|
||||
To do this, uncheck ``active``. Deactivated
|
||||
flags will still show up in the UI if they are ?, +, or -, but they
|
||||
may only be cleared (unset), and cannot be changed to a new value.
|
||||
Once a deactivated flag is cleared, it will completely disappear from a
|
||||
bug/attachment, and cannot be set again.
|
||||
|
||||
.. _flags-create-field-requestable:
|
||||
|
||||
Requestable
|
||||
~~~~~~~~~~~
|
||||
|
||||
New flags are, by default, ``requestable``, meaning that they
|
||||
offer users the ``?`` option, as well as ``+``
|
||||
and ``-``.
|
||||
To remove the ? option, uncheck ``requestable``.
|
||||
|
||||
.. _flags-create-field-specific:
|
||||
|
||||
Specifically Requestable
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
By default this box is checked for new flags, meaning that users may make
|
||||
flag requests of specific individuals. Unchecking this box will remove the
|
||||
text box next to a flag; if it is still requestable, then requests may
|
||||
only be made ``to the wind.`` Removing this after specific
|
||||
requests have been made will not remove those requests; that data will
|
||||
stay in the database (though it will no longer appear to the user).
|
||||
|
||||
.. _flags-create-field-multiplicable:
|
||||
|
||||
Multiplicable
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
Any flag with ``Multiplicable`` set (default for new flags is 'on')
|
||||
may be set more than once. After being set once, an unset flag
|
||||
of the same type will appear below it with ``addl.`` (short for
|
||||
``additional``) before the name. There is no limit to the number of
|
||||
times a Multiplicable flags may be set on the same bug/attachment.
|
||||
|
||||
.. _flags-create-field-cclist:
|
||||
|
||||
CC List
|
||||
~~~~~~~
|
||||
|
||||
If you want certain users to be notified every time this flag is
|
||||
set to ?, -, +, or unset, add them here. This is a comma-separated
|
||||
list of email addresses that need not be restricted to Bugzilla usernames.
|
||||
|
||||
.. _flags-create-grant-group:
|
||||
|
||||
Grant Group
|
||||
~~~~~~~~~~~
|
||||
|
||||
When this field is set to some given group, only users in the group
|
||||
can set the flag to ``+`` and ``-``. This
|
||||
field does not affect who can request or cancel the flag. For that,
|
||||
see the ``Request Group`` field below. If this field
|
||||
is left blank, all users can set or delete this flag. This field is
|
||||
useful for restricting which users can approve or reject requests.
|
||||
|
||||
.. _flags-create-request-group:
|
||||
|
||||
Request Group
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
When this field is set to some given group, only users in the group
|
||||
can request or cancel this flag. Note that this field has no effect
|
||||
if the ``grant group`` field is empty. You can set the
|
||||
value of this field to a different group, but both fields have to be
|
||||
set to a group for this field to have an effect.
|
||||
|
||||
.. COMMENT: flags-create
|
||||
|
||||
.. _flags-delete:
|
||||
|
||||
Deleting a Flag
|
||||
---------------
|
||||
|
||||
When you are at the ``Administer Flag Types`` screen,
|
||||
you will be presented with a list of Bug flags and a list of Attachment
|
||||
Flags.
|
||||
|
||||
To delete a flag, click on the ``Delete`` link next to
|
||||
the flag description.
|
||||
|
||||
.. warning:: Once you delete a flag, it is *gone* from
|
||||
your Bugzilla. All the data for that flag will be deleted.
|
||||
Everywhere that flag was set, it will disappear,
|
||||
and you cannot get that data back. If you want to keep flag data,
|
||||
but don't want anybody to set any new flags or change current flags,
|
||||
unset ``active`` in the flag Edit form.
|
||||
|
||||
.. COMMENT: flags-admin
|
||||
|
||||
.. COMMENT: XXX We should add a "Uses of Flags" section, here, with examples.
|
||||
|
||||
.. COMMENT: flags
|
||||
|
||||
@ -0,0 +1,191 @@
|
||||
.. _groups:
|
||||
|
||||
Groups and Security
|
||||
###################
|
||||
|
||||
Groups allow for separating bugs into logical divisions.
|
||||
Groups are typically used
|
||||
to isolate bugs that should only be seen by certain people. For
|
||||
example, a company might create a different group for each one of its customers
|
||||
or partners. Group permissions could be set so that each partner or customer would
|
||||
only have access to their own bugs. Or, groups might be used to create
|
||||
variable access controls for different departments within an organization.
|
||||
Another common use of groups is to associate groups with products,
|
||||
creating isolation and access control on a per-product basis.
|
||||
|
||||
Groups and group behaviors are controlled in several places:
|
||||
|
||||
#. The group configuration page. To view or edit existing groups, or to
|
||||
create new groups, access the "Groups" link from the "Administration"
|
||||
page. This section of the manual deals primarily with the aspect of
|
||||
group controls accessed on this page.
|
||||
|
||||
#. Global configuration parameters. Bugzilla has several parameters
|
||||
that control the overall default group behavior and restriction
|
||||
levels. For more information on the parameters that control
|
||||
group behavior globally, see :ref:`param-group-security`.
|
||||
|
||||
#. Product association with groups. Most of the functionality of groups
|
||||
and group security is controlled at the product level. Some aspects
|
||||
of group access controls for products are discussed in this section,
|
||||
but for more detail see :ref:`product-group-controls`.
|
||||
|
||||
#. Group access for users. See :ref:`users-and-groups` for
|
||||
details on how users are assigned group access.
|
||||
|
||||
Group permissions are such that if a bug belongs to a group, only members
|
||||
of that group can see the bug. If a bug is in more than one group, only
|
||||
members of *all* the groups that the bug is in can see
|
||||
the bug. For information on granting read-only access to certain people and
|
||||
full edit access to others, see :ref:`product-group-controls`.
|
||||
|
||||
.. note:: By default, bugs can also be seen by the Assignee, the Reporter, and
|
||||
by everyone on the CC List, regardless of whether or not the bug would
|
||||
typically be viewable by them. Visibility to the Reporter and CC List can
|
||||
be overridden (on a per-bug basis) by bringing up the bug, finding the
|
||||
section that starts with ``Users in the roles selected below...``
|
||||
and un-checking the box next to either 'Reporter' or 'CC List' (or both).
|
||||
|
||||
.. _create-groups:
|
||||
|
||||
Creating Groups
|
||||
===============
|
||||
|
||||
To create a new group, follow the steps below:
|
||||
|
||||
#. Select the ``Administration`` link in the page footer,
|
||||
and then select the ``Groups`` link from the
|
||||
Administration page.
|
||||
|
||||
#. A table of all the existing groups is displayed. Below the table is a
|
||||
description of all the fields. To create a new group, select the
|
||||
``Add Group`` link under the table of existing groups.
|
||||
|
||||
#. There are five fields to fill out. These fields are documented below
|
||||
the form. Choose a name and description for the group. Decide whether
|
||||
this group should be used for bugs (in all likelihood this should be
|
||||
selected). Optionally, choose a regular expression that will
|
||||
automatically add any matching users to the group, and choose an
|
||||
icon that will help identify user comments for the group. The regular
|
||||
expression can be useful, for example, to automatically put all users
|
||||
from the same company into one group (if the group is for a specific
|
||||
customer or partner).
|
||||
|
||||
.. note:: If ``User RegExp`` is filled out, users whose email
|
||||
addresses match the regular expression will automatically be
|
||||
members of the group as long as their email addresses continue
|
||||
to match the regular expression. If their email address changes
|
||||
and no longer matches the regular expression, they will be removed
|
||||
from the group. Versions 2.16 and older of Bugzilla did not automatically
|
||||
remove users who's email addresses no longer matched the RegExp.
|
||||
|
||||
.. warning:: If specifying a domain in the regular expression, end
|
||||
the regexp with a "$". Otherwise, when granting access to
|
||||
"@mycompany\\.com", access will also be granted to
|
||||
'badperson@mycompany.com.cracker.net'. Use the syntax,
|
||||
'@mycompany\\.com$' for the regular expression.
|
||||
|
||||
#. After the new group is created, it can be edited for additional options.
|
||||
The "Edit Group" page allows for specifying other groups that should be included
|
||||
in this group and which groups should be permitted to add and delete
|
||||
users from this group. For more details, see :ref:`edit-groups`.
|
||||
|
||||
.. _edit-groups:
|
||||
|
||||
Editing Groups and Assigning Group Permissions
|
||||
==============================================
|
||||
|
||||
To access the "Edit Groups" page, select the
|
||||
``Administration`` link in the page footer,
|
||||
and then select the ``Groups`` link from the Administration page.
|
||||
A table of all the existing groups is displayed. Click on a group name
|
||||
you wish to edit or control permissions for.
|
||||
|
||||
The "Edit Groups" page contains the same five fields present when
|
||||
creating a new group. Below that are two additional sections, "Group
|
||||
Permissions," and "Mass Remove". The "Mass Remove" option simply removes
|
||||
all users from the group who match the regular expression entered. The
|
||||
"Group Permissions" section requires further explanation.
|
||||
|
||||
The "Group Permissions" section on the "Edit Groups" page contains four sets
|
||||
of permissions that control the relationship of this group to other
|
||||
groups. If the 'usevisibilitygroups' parameter is in use (see
|
||||
:ref:`parameters`) two additional sets of permissions are displayed.
|
||||
Each set consists of two select boxes. On the left, a select box
|
||||
with a list of all existing groups. On the right, a select box listing
|
||||
all groups currently selected for this permission setting (this box will
|
||||
be empty for new groups). The way these controls allow groups to relate
|
||||
to one another is called *inheritance*.
|
||||
Each of the six permissions is described below.
|
||||
|
||||
*Groups That Are a Member of This Group*
|
||||
Members of any groups selected here will automatically have
|
||||
membership in this group. In other words, members of any selected
|
||||
group will inherit membership in this group.
|
||||
|
||||
*Groups That This Group Is a Member Of*
|
||||
Members of this group will inherit membership to any group
|
||||
selected here. For example, suppose the group being edited is
|
||||
an Admin group. If there are two products (Product1 and Product2)
|
||||
and each product has its
|
||||
own group (Group1 and Group2), and the Admin group
|
||||
should have access to both products,
|
||||
simply select both Group1 and Group2 here.
|
||||
|
||||
*Groups That Can Grant Membership in This Group*
|
||||
The members of any group selected here will be able add users
|
||||
to this group, even if they themselves are not in this group.
|
||||
|
||||
*Groups That This Group Can Grant Membership In*
|
||||
Members of this group can add users to any group selected here,
|
||||
even if they themselves are not in the selected groups.
|
||||
|
||||
*Groups That Can See This Group*
|
||||
Members of any selected group can see the users in this group.
|
||||
This setting is only visible if the 'usevisibilitygroups' parameter
|
||||
is enabled on the Bugzilla Configuration page. See
|
||||
:ref:`parameters` for information on configuring Bugzilla.
|
||||
|
||||
*Groups That This Group Can See*
|
||||
Members of this group can see members in any of the selected groups.
|
||||
This setting is only visible if the 'usevisibilitygroups' parameter
|
||||
is enabled on the the Bugzilla Configuration page. See
|
||||
:ref:`parameters` for information on configuring Bugzilla.
|
||||
|
||||
.. _users-and-groups:
|
||||
|
||||
Assigning Users to Groups
|
||||
=========================
|
||||
|
||||
A User can become a member of a group in several ways:
|
||||
|
||||
#. The user can be explicitly placed in the group by editing
|
||||
the user's profile. This can be done by accessing the "Users" page
|
||||
from the "Administration" page. Use the search form to find the user
|
||||
you want to edit group membership for, and click on their email
|
||||
address in the search results to edit their profile. The profile
|
||||
page lists all the groups, and indicates if the user is a member of
|
||||
the group either directly or indirectly. More information on indirect
|
||||
group membership is below. For more details on User administration,
|
||||
see :ref:`useradmin`.
|
||||
|
||||
#. The group can include another group of which the user is
|
||||
a member. This is indicated by square brackets around the checkbox
|
||||
next to the group name in the user's profile.
|
||||
See :ref:`edit-groups` for details on group inheritance.
|
||||
|
||||
#. The user's email address can match the regular expression
|
||||
that has been specified to automatically grant membership to
|
||||
the group. This is indicated by "\*" around the check box by the
|
||||
group name in the user's profile.
|
||||
See :ref:`create-groups` for details on
|
||||
the regular expression option when creating groups.
|
||||
|
||||
Assigning Group Controls to Products
|
||||
====================================
|
||||
|
||||
The primary functionality of groups is derived from the relationship of
|
||||
groups to products. The concepts around segregating access to bugs with
|
||||
product group controls can be confusing. For details and examples on this
|
||||
topic, see :ref:`product-group-controls`.
|
||||
|
||||
@ -0,0 +1,21 @@
|
||||
.. _keywords:
|
||||
|
||||
Keywords
|
||||
########
|
||||
|
||||
The administrator can define keywords which can be used to tag and
|
||||
categorise bugs. For example, the keyword "regression" is commonly used.
|
||||
A company might have a policy stating all regressions
|
||||
must be fixed by the next release - this keyword can make tracking those
|
||||
bugs much easier.
|
||||
|
||||
Keywords are global, rather than per-product. If the administrator changes
|
||||
a keyword currently applied to any bugs, the keyword cache must be rebuilt
|
||||
using the :ref:`sanitycheck` script. Currently keywords cannot
|
||||
be marked obsolete to prevent future usage.
|
||||
|
||||
Keywords can be created, edited or deleted by clicking the "Keywords"
|
||||
link in the admin page. There are two fields for each keyword - the keyword
|
||||
itself and a brief description. Once created, keywords can be selected
|
||||
and applied to individual bugs in that bug's "Details" section.
|
||||
|
||||
@ -0,0 +1,554 @@
|
||||
.. _parameters:
|
||||
|
||||
Parameters
|
||||
##########
|
||||
|
||||
Bugzilla is configured by changing various parameters, accessed
|
||||
from the "Parameters" link in the Administration page (the
|
||||
Administration page can be found by clicking the "Administration"
|
||||
link in the footer). The parameters are divided into several categories,
|
||||
accessed via the menu on the left. Following is a description of the
|
||||
different categories and important parameters within those categories.
|
||||
|
||||
.. _param-requiredsettings:
|
||||
|
||||
Required Settings
|
||||
=================
|
||||
|
||||
The core required parameters for any Bugzilla installation are set
|
||||
here. These parameters must be set before a new Bugzilla installation
|
||||
can be used. Administrators should review this list before
|
||||
deploying a new Bugzilla installation.
|
||||
|
||||
maintainer
|
||||
Email address of the person
|
||||
responsible for maintaining this Bugzilla installation.
|
||||
The address need not be that of a valid Bugzilla account.
|
||||
|
||||
urlbase
|
||||
Defines the fully qualified domain name and web
|
||||
server path to this Bugzilla installation.
|
||||
For example, if the Bugzilla query page is
|
||||
:file:`http://www.foo.com/bugzilla/query.cgi`,
|
||||
the ``urlbase`` should be set
|
||||
to :file:`http://www.foo.com/bugzilla/`.
|
||||
|
||||
docs_urlbase
|
||||
Defines path to the Bugzilla documentation. This can be a fully
|
||||
qualified domain name, or a path relative to "urlbase".
|
||||
For example, if the "Bugzilla Configuration" page
|
||||
of the documentation is
|
||||
:file:`http://www.foo.com/bugzilla/docs/html/parameters.html`,
|
||||
set the ``docs_urlbase``
|
||||
to :file:`http://www.foo.com/bugzilla/docs/html/`.
|
||||
|
||||
sslbase
|
||||
Defines the fully qualified domain name and web
|
||||
server path for HTTPS (SSL) connections to this Bugzilla installation.
|
||||
For example, if the Bugzilla main page is
|
||||
:file:`https://www.foo.com/bugzilla/index.cgi`,
|
||||
the ``sslbase`` should be set
|
||||
to :file:`https://www.foo.com/bugzilla/`.
|
||||
|
||||
ssl_redirect
|
||||
If enabled, Bugzilla will force HTTPS (SSL) connections, by
|
||||
automatically redirecting any users who try to use a non-SSL
|
||||
connection.
|
||||
|
||||
cookiedomain
|
||||
Defines the domain for Bugzilla cookies. This is typically left blank.
|
||||
If there are multiple hostnames that point to the same webserver, which
|
||||
require the same cookie, then this parameter can be utilized. For
|
||||
example, If your website is at
|
||||
:file:`https://www.foo.com/`, setting this to
|
||||
:file:`.foo.com/` will also allow
|
||||
:file:`bar.foo.com/` to access Bugzilla cookies.
|
||||
|
||||
cookiepath
|
||||
Defines a path, relative to the web server root, that Bugzilla
|
||||
cookies will be restricted to. For example, if the
|
||||
:command:`urlbase` is set to
|
||||
:file:`http://www.foo.com/bugzilla/`, the
|
||||
:command:`cookiepath` should be set to
|
||||
:file:`/bugzilla/`. Setting it to "/" will allow all sites
|
||||
served by this web server or virtual host to read Bugzilla cookies.
|
||||
|
||||
utf8
|
||||
Determines whether to use UTF-8 (Unicode) encoding for all text in
|
||||
Bugzilla. New installations should set this to true to avoid character
|
||||
encoding problems. Existing databases should set this to true only
|
||||
after the data has been converted from existing legacy character
|
||||
encoding to UTF-8, using the
|
||||
:file:`contrib/recode.pl` script.
|
||||
|
||||
.. note:: If you turn this parameter from "off" to "on", you must
|
||||
re-run :file:`checksetup.pl` immediately afterward.
|
||||
|
||||
shutdownhtml
|
||||
If there is any text in this field, this Bugzilla installation will
|
||||
be completely disabled and this text will appear instead of all
|
||||
Bugzilla pages for all users, including Admins. Used in the event
|
||||
of site maintenance or outage situations.
|
||||
|
||||
.. note:: Although regular log-in capability is disabled
|
||||
while :command:`shutdownhtml`
|
||||
is enabled, safeguards are in place to protect the unfortunate
|
||||
admin who loses connection to Bugzilla. Should this happen to you,
|
||||
go directly to the :file:`editparams.cgi` (by typing
|
||||
the URL in manually, if necessary). Doing this will prompt you to
|
||||
log in, and your name/password will be accepted here (but nowhere
|
||||
else).
|
||||
|
||||
announcehtml
|
||||
Any text in this field will be displayed at the top of every HTML
|
||||
page in this Bugzilla installation. The text is not wrapped in any
|
||||
tags. For best results, wrap the text in a ``<div>``
|
||||
tag. Any style attributes from the CSS can be applied. For example,
|
||||
to make the text green inside of a red box, add ``id=message``
|
||||
to the ``<div>`` tag.
|
||||
|
||||
proxy_url
|
||||
If this Bugzilla installation is behind a proxy, enter the proxy
|
||||
information here to enable Bugzilla to access the Internet. Bugzilla
|
||||
requires Internet access to utilize the
|
||||
:command:`upgrade_notification` parameter (below). If the
|
||||
proxy requires authentication, use the syntax:
|
||||
:file:`http://user:pass@proxy_url/`.
|
||||
|
||||
upgrade_notification
|
||||
Enable or disable a notification on the homepage of this Bugzilla
|
||||
installation when a newer version of Bugzilla is available. This
|
||||
notification is only visible to administrators. Choose "disabled",
|
||||
to turn off the notification. Otherwise, choose which version of
|
||||
Bugzilla you want to be notified about: "development_snapshot" is the
|
||||
latest release on the trunk; "latest_stable_release" is the most
|
||||
recent release available on the most recent stable branch;
|
||||
"stable_branch_release" the most recent release on the branch
|
||||
this installation is based on.
|
||||
|
||||
.. _param-admin-policies:
|
||||
|
||||
Administrative Policies
|
||||
=======================
|
||||
|
||||
This page contains parameters for basic administrative functions.
|
||||
Options include whether to allow the deletion of bugs and users,
|
||||
and whether to allow users to change their email address.
|
||||
|
||||
.. _param-user-authentication:
|
||||
|
||||
User Authentication
|
||||
===================
|
||||
|
||||
This page contains the settings that control how this Bugzilla
|
||||
installation will do its authentication. Choose what authentication
|
||||
mechanism to use (the Bugzilla database, or an external source such
|
||||
as LDAP), and set basic behavioral parameters. For example, choose
|
||||
whether to require users to login to browse bugs, the management
|
||||
of authentication cookies, and the regular expression used to
|
||||
validate email addresses. Some parameters are highlighted below.
|
||||
|
||||
emailregexp
|
||||
Defines the regular expression used to validate email addresses
|
||||
used for login names. The default attempts to match fully
|
||||
qualified email addresses (i.e. 'user@example.com') in a slightly
|
||||
more restrictive way than what is allowed in RFC 2822.
|
||||
Some Bugzilla installations allow only local user names (i.e 'user'
|
||||
instead of 'user@example.com'). In that case, this parameter
|
||||
should be used to define the email domain.
|
||||
|
||||
emailsuffix
|
||||
This string is appended to login names when actually sending
|
||||
email to a user. For example,
|
||||
If :command:`emailregexp` has been set to allow
|
||||
local usernames,
|
||||
then this parameter would contain the email domain for all users
|
||||
(i.e. '@example.com').
|
||||
|
||||
.. _param-attachments:
|
||||
|
||||
Attachments
|
||||
===========
|
||||
|
||||
This page allows for setting restrictions and other parameters
|
||||
regarding attachments to bugs. For example, control size limitations
|
||||
and whether to allow pointing to external files via a URI.
|
||||
|
||||
.. _param-bug-change-policies:
|
||||
|
||||
Bug Change Policies
|
||||
===================
|
||||
|
||||
Set policy on default behavior for bug change events. For example,
|
||||
choose which status to set a bug to when it is marked as a duplicate,
|
||||
and choose whether to allow bug reporters to set the priority or
|
||||
target milestone. Also allows for configuration of what changes
|
||||
should require the user to make a comment, described below.
|
||||
|
||||
commenton*
|
||||
All these fields allow you to dictate what changes can pass
|
||||
without comment, and which must have a comment from the
|
||||
person who changed them. Often, administrators will allow
|
||||
users to add themselves to the CC list, accept bugs, or
|
||||
change the Status Whiteboard without adding a comment as to
|
||||
their reasons for the change, yet require that most other
|
||||
changes come with an explanation.
|
||||
Set the "commenton" options according to your site policy. It
|
||||
is a wise idea to require comments when users resolve, reassign, or
|
||||
reopen bugs at the very least.
|
||||
|
||||
.. note:: It is generally far better to require a developer comment
|
||||
when resolving bugs than not. Few things are more annoying to bug
|
||||
database users than having a developer mark a bug "fixed" without
|
||||
any comment as to what the fix was (or even that it was truly
|
||||
fixed!)
|
||||
|
||||
noresolveonopenblockers
|
||||
This option will prevent users from resolving bugs as FIXED if
|
||||
they have unresolved dependencies. Only the FIXED resolution
|
||||
is affected. Users will be still able to resolve bugs to
|
||||
resolutions other than FIXED if they have unresolved dependent
|
||||
bugs.
|
||||
|
||||
.. _param-bugfields:
|
||||
|
||||
Bug Fields
|
||||
==========
|
||||
|
||||
The parameters in this section determine the default settings of
|
||||
several Bugzilla fields for new bugs, and also control whether
|
||||
certain fields are used. For example, choose whether to use the
|
||||
"target milestone" field or the "status whiteboard" field.
|
||||
|
||||
useqacontact
|
||||
This allows you to define an email address for each component,
|
||||
in addition to that of the default assignee, who will be sent
|
||||
carbon copies of incoming bugs.
|
||||
|
||||
usestatuswhiteboard
|
||||
This defines whether you wish to have a free-form, overwritable field
|
||||
associated with each bug. The advantage of the Status Whiteboard is
|
||||
that it can be deleted or modified with ease, and provides an
|
||||
easily-searchable field for indexing some bugs that have some trait
|
||||
in common.
|
||||
|
||||
.. _param-bugmoving:
|
||||
|
||||
Bug Moving
|
||||
==========
|
||||
|
||||
This page controls whether this Bugzilla installation allows certain
|
||||
users to move bugs to an external database. If bug moving is enabled,
|
||||
there are a number of parameters that control bug moving behaviors.
|
||||
For example, choose which users are allowed to move bugs, the location
|
||||
of the external database, and the default product and component that
|
||||
bugs moved *from* other bug databases to this
|
||||
Bugzilla installation are assigned to.
|
||||
|
||||
.. _param-dependency-graphs:
|
||||
|
||||
Dependency Graphs
|
||||
=================
|
||||
|
||||
This page has one parameter that sets the location of a Web Dot
|
||||
server, or of the Web Dot binary on the local system, that is used
|
||||
to generate dependency graphs. Web Dot is a CGI program that creates
|
||||
images from :file:`.dot` graphic description files. If
|
||||
no Web Dot server or binary is specified, then dependency graphs will
|
||||
be disabled.
|
||||
|
||||
.. _param-group-security:
|
||||
|
||||
Group Security
|
||||
==============
|
||||
|
||||
Bugzilla allows for the creation of different groups, with the
|
||||
ability to restrict the visibility of bugs in a group to a set of
|
||||
specific users. Specific products can also be associated with
|
||||
groups, and users restricted to only see products in their groups.
|
||||
Several parameters are described in more detail below. Most of the
|
||||
configuration of groups and their relationship to products is done
|
||||
on the "Groups" and "Product" pages of the "Administration" area.
|
||||
The options on this page control global default behavior.
|
||||
For more information on Groups and Group Security, see
|
||||
:ref:`groups`
|
||||
|
||||
makeproductgroups
|
||||
Determines whether or not to automatically create groups
|
||||
when new products are created. If this is on, the groups will be
|
||||
used for querying bugs.
|
||||
|
||||
usevisibilitygroups
|
||||
If selected, user visibility will be restricted to members of
|
||||
groups, as selected in the group configuration settings.
|
||||
Each user-defined group can be allowed to see members of selected
|
||||
other groups.
|
||||
For details on configuring groups (including the visibility
|
||||
restrictions) see :ref:`edit-groups`.
|
||||
|
||||
querysharegroup
|
||||
The name of the group of users who are allowed to share saved
|
||||
searches with one another. For more information on using
|
||||
saved searches, see :ref:`savedsearches`.
|
||||
|
||||
.. _bzldap:
|
||||
|
||||
LDAP Authentication
|
||||
===================
|
||||
|
||||
LDAP authentication is a module for Bugzilla's plugin
|
||||
authentication architecture. This page contains all the parameters
|
||||
necessary to configure Bugzilla for use with LDAP authentication.
|
||||
|
||||
The existing authentication
|
||||
scheme for Bugzilla uses email addresses as the primary user ID, and a
|
||||
password to authenticate that user. All places within Bugzilla that
|
||||
require a user ID (e.g assigning a bug) use the email
|
||||
address. The LDAP authentication builds on top of this scheme, rather
|
||||
than replacing it. The initial log-in is done with a username and
|
||||
password for the LDAP directory. Bugzilla tries to bind to LDAP using
|
||||
those credentials and, if successful, tries to map this account to a
|
||||
Bugzilla account. If an LDAP mail attribute is defined, the value of this
|
||||
attribute is used, otherwise the "emailsuffix" parameter is appended to LDAP
|
||||
username to form a full email address. If an account for this address
|
||||
already exists in the Bugzilla installation, it will log in to that account.
|
||||
If no account for that email address exists, one is created at the time
|
||||
of login. (In this case, Bugzilla will attempt to use the "displayName"
|
||||
or "cn" attribute to determine the user's full name.) After
|
||||
authentication, all other user-related tasks are still handled by email
|
||||
address, not LDAP username. For example, bugs are still assigned by
|
||||
email address and users are still queried by email address.
|
||||
|
||||
.. warning:: Because the Bugzilla account is not created until the first time
|
||||
a user logs in, a user who has not yet logged is unknown to Bugzilla.
|
||||
This means they cannot be used as an assignee or QA contact (default or
|
||||
otherwise), added to any CC list, or any other such operation. One
|
||||
possible workaround is the :file:`bugzilla_ldapsync.rb`
|
||||
script in the :file:`contrib`
|
||||
directory. Another possible solution is fixing
|
||||
`bug
|
||||
201069 <https://bugzilla.mozilla.org/show_bug.cgi?id=201069>`_.
|
||||
|
||||
Parameters required to use LDAP Authentication:
|
||||
|
||||
user_verify_class
|
||||
If you want to list ``LDAP`` here,
|
||||
make sure to have set up the other parameters listed below.
|
||||
Unless you have other (working) authentication methods listed as
|
||||
well, you may otherwise not be able to log back in to Bugzilla once
|
||||
you log out.
|
||||
If this happens to you, you will need to manually edit
|
||||
:file:`data/params` and set user_verify_class to
|
||||
``DB``.
|
||||
|
||||
LDAPserver
|
||||
This parameter should be set to the name (and optionally the
|
||||
port) of your LDAP server. If no port is specified, it assumes
|
||||
the default LDAP port of 389.
|
||||
For example: ``ldap.company.com``
|
||||
or ``ldap.company.com:3268``
|
||||
You can also specify a LDAP URI, so as to use other
|
||||
protocols, such as LDAPS or LDAPI. If port was not specified in
|
||||
the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS'
|
||||
schemes respectively.
|
||||
|
||||
.. note:: In order to use SSL with LDAP, specify a URI with "ldaps://".
|
||||
This will force the use of SSL over port 636.
|
||||
For example, normal LDAP:
|
||||
``ldap://ldap.company.com``, LDAP over SSL:
|
||||
``ldaps://ldap.company.com`` or LDAP over a UNIX
|
||||
domain socket ``ldapi://%2fvar%2flib%2fldap_sock``.
|
||||
|
||||
LDAPbinddn \[Optional]
|
||||
Some LDAP servers will not allow an anonymous bind to search
|
||||
the directory. If this is the case with your configuration you
|
||||
should set the LDAPbinddn parameter to the user account Bugzilla
|
||||
should use instead of the anonymous bind.
|
||||
Ex. ``cn=default,cn=user:password``
|
||||
|
||||
LDAPBaseDN
|
||||
The LDAPBaseDN parameter should be set to the location in
|
||||
your LDAP tree that you would like to search for email addresses.
|
||||
Your uids should be unique under the DN specified here.
|
||||
Ex. ``ou=People,o=Company``
|
||||
|
||||
LDAPuidattribute
|
||||
The LDAPuidattribute parameter should be set to the attribute
|
||||
which contains the unique UID of your users. The value retrieved
|
||||
from this attribute will be used when attempting to bind as the
|
||||
user to confirm their password.
|
||||
Ex. ``uid``
|
||||
|
||||
LDAPmailattribute
|
||||
The LDAPmailattribute parameter should be the name of the
|
||||
attribute which contains the email address your users will enter
|
||||
into the Bugzilla login boxes.
|
||||
Ex. ``mail``
|
||||
|
||||
.. _bzradius:
|
||||
|
||||
RADIUS Authentication
|
||||
=====================
|
||||
|
||||
RADIUS authentication is a module for Bugzilla's plugin
|
||||
authentication architecture. This page contains all the parameters
|
||||
necessary for configuring Bugzilla to use RADIUS authentication.
|
||||
|
||||
.. note:: Most caveats that apply to LDAP authentication apply to RADIUS
|
||||
authentication as well. See :ref:`bzldap` for details.
|
||||
|
||||
Parameters required to use RADIUS Authentication:
|
||||
|
||||
user_verify_class
|
||||
If you want to list ``RADIUS`` here,
|
||||
make sure to have set up the other parameters listed below.
|
||||
Unless you have other (working) authentication methods listed as
|
||||
well, you may otherwise not be able to log back in to Bugzilla once
|
||||
you log out.
|
||||
If this happens to you, you will need to manually edit
|
||||
:file:`data/params` and set user_verify_class to
|
||||
``DB``.
|
||||
|
||||
RADIUS_server
|
||||
This parameter should be set to the name (and optionally the
|
||||
port) of your RADIUS server.
|
||||
|
||||
RADIUS_secret
|
||||
This parameter should be set to the RADIUS server's secret.
|
||||
|
||||
RADIUS_email_suffix
|
||||
Bugzilla needs an e-mail address for each user account.
|
||||
Therefore, it needs to determine the e-mail address corresponding
|
||||
to a RADIUS user.
|
||||
Bugzilla offers only a simple way to do this: it can concatenate
|
||||
a suffix to the RADIUS user name to convert it into an e-mail
|
||||
address.
|
||||
You can specify this suffix in the RADIUS_email_suffix parameter.
|
||||
If this simple solution does not work for you, you'll
|
||||
probably need to modify
|
||||
:file:`Bugzilla/Auth/Verify/RADIUS.pm` to match your
|
||||
requirements.
|
||||
|
||||
.. _param-email:
|
||||
|
||||
Email
|
||||
=====
|
||||
|
||||
This page contains all of the parameters for configuring how
|
||||
Bugzilla deals with the email notifications it sends. See below
|
||||
for a summary of important options.
|
||||
|
||||
mail_delivery_method
|
||||
This is used to specify how email is sent, or if it is sent at
|
||||
all. There are several options included for different MTAs,
|
||||
along with two additional options that disable email sending.
|
||||
"Test" does not send mail, but instead saves it in
|
||||
:file:`data/mailer.testfile` for later review.
|
||||
"None" disables email sending entirely.
|
||||
|
||||
mailfrom
|
||||
This is the email address that will appear in the "From" field
|
||||
of all emails sent by this Bugzilla installation. Some email
|
||||
servers require mail to be from a valid email address, therefore
|
||||
it is recommended to choose a valid email address here.
|
||||
|
||||
smtpserver
|
||||
This is the SMTP server address, if the ``mail_delivery_method``
|
||||
parameter is set to SMTP. Use "localhost" if you have a local MTA
|
||||
running, otherwise use a remote SMTP server. Append ":" and the port
|
||||
number, if a non-default port is needed.
|
||||
|
||||
smtp_username
|
||||
Username to use for SASL authentication to the SMTP server. Leave
|
||||
this parameter empty if your server does not require authentication.
|
||||
|
||||
smtp_password
|
||||
Password to use for SASL authentication to the SMTP server. This
|
||||
parameter will be ignored if the ``smtp_username``
|
||||
parameter is left empty.
|
||||
|
||||
smtp_ssl
|
||||
Enable SSL support for connection to the SMTP server.
|
||||
|
||||
smtp_debug
|
||||
This parameter allows you to enable detailed debugging output.
|
||||
Log messages are printed the web server's error log.
|
||||
|
||||
whinedays
|
||||
Set this to the number of days you want to let bugs go
|
||||
in the CONFIRMED state before notifying people they have
|
||||
untouched new bugs. If you do not plan to use this feature, simply
|
||||
do not set up the whining cron job described in the installation
|
||||
instructions, or set this value to "0" (never whine).
|
||||
|
||||
globalwatcher
|
||||
This allows you to define specific users who will
|
||||
receive notification each time a new bug in entered, or when
|
||||
an existing bug changes, according to the normal groupset
|
||||
permissions. It may be useful for sending notifications to a
|
||||
mailing-list, for instance.
|
||||
|
||||
.. _param-patchviewer:
|
||||
|
||||
Patch Viewer
|
||||
============
|
||||
|
||||
This page contains configuration parameters for the CVS server,
|
||||
Bonsai server and LXR server that Bugzilla will use to enable the
|
||||
features of the Patch Viewer. Bonsai is a tool that enables queries
|
||||
to a CVS tree. LXR is a tool that can cross reference and index source
|
||||
code.
|
||||
|
||||
.. _param-querydefaults:
|
||||
|
||||
Query Defaults
|
||||
==============
|
||||
|
||||
This page controls the default behavior of Bugzilla in regards to
|
||||
several aspects of querying bugs. Options include what the default
|
||||
query options are, what the "My Bugs" page returns, whether users
|
||||
can freely add bugs to the quip list, and how many duplicate bugs are
|
||||
needed to add a bug to the "most frequently reported" list.
|
||||
|
||||
.. _param-shadowdatabase:
|
||||
|
||||
Shadow Database
|
||||
===============
|
||||
|
||||
This page controls whether a shadow database is used, and all the
|
||||
parameters associated with the shadow database. Versions of Bugzilla
|
||||
prior to 3.2 used the MyISAM table type, which supports
|
||||
only table-level write locking. With MyISAM, any time someone is making a change to
|
||||
a bug, the entire table is locked until the write operation is complete.
|
||||
Locking for write also blocks reads until the write is complete.
|
||||
|
||||
The ``shadowdb`` parameter was designed to get around
|
||||
this limitation. While only a single user is allowed to write to
|
||||
a table at a time, reads can continue unimpeded on a read-only
|
||||
shadow copy of the database.
|
||||
|
||||
.. note:: As of version 3.2, Bugzilla no longer uses the MyISAM table type.
|
||||
Instead, InnoDB is used, which can do transaction-based locking.
|
||||
Therefore, the limitations the Shadow Database feature was designed
|
||||
to workaround no longer exist.
|
||||
|
||||
.. _admin-usermatching:
|
||||
|
||||
User Matching
|
||||
=============
|
||||
|
||||
The settings on this page control how users are selected and queried
|
||||
when adding a user to a bug. For example, users need to be selected
|
||||
when choosing who the bug is assigned to, adding to the CC list or
|
||||
selecting a QA contact. With the "usemenuforusers" parameter, it is
|
||||
possible to configure Bugzilla to
|
||||
display a list of users in the fields instead of an empty text field.
|
||||
This should only be used in Bugzilla installations with a small number
|
||||
of users. If users are selected via a text box, this page also
|
||||
contains parameters for how user names can be queried and matched
|
||||
when entered.
|
||||
|
||||
Another setting called 'ajax_user_autocompletion' enables certain
|
||||
user fields to display a list of matched user names as a drop down after typing
|
||||
a few characters. Note that it is recommended to use mod_perl when
|
||||
enabling 'ajax_user_autocompletion'.
|
||||
@ -0,0 +1,4 @@
|
||||
.. _default-preferences:
|
||||
|
||||
Default Preferences
|
||||
###################
|
||||
@ -0,0 +1,252 @@
|
||||
.. _users:
|
||||
|
||||
Users
|
||||
#####
|
||||
|
||||
.. _defaultuser:
|
||||
|
||||
Creating the Default User
|
||||
=========================
|
||||
|
||||
When you first run checksetup.pl after installing Bugzilla, it
|
||||
will prompt you for the administrative username (email address) and
|
||||
password for this "super user". If for some reason you delete
|
||||
the "super user" account, re-running checksetup.pl will again prompt
|
||||
you for this username and password.
|
||||
|
||||
.. 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).
|
||||
|
||||
.. _manageusers:
|
||||
|
||||
Managing Other Users
|
||||
====================
|
||||
|
||||
.. _user-account-search:
|
||||
|
||||
Searching for existing users
|
||||
----------------------------
|
||||
|
||||
If you have ``editusers`` privileges or if you are allowed
|
||||
to grant privileges for some groups, the ``Users`` link
|
||||
will appear in the Administration page.
|
||||
|
||||
The first screen is a search form to search for existing user
|
||||
accounts. You can run searches based either on the user ID, real
|
||||
name or login name (i.e. the email address, or just the first part
|
||||
of the email address if the "emailsuffix" parameter is set).
|
||||
The search can be conducted
|
||||
in different ways using the listbox to the right of the text entry
|
||||
box. You can match by case-insensitive substring (the default),
|
||||
regular expression, a *reverse* regular expression
|
||||
match (which finds every user name which does NOT match the regular
|
||||
expression), or the exact string if you know exactly who you are
|
||||
looking for. The search can be restricted to users who are in a
|
||||
specific group. By default, the restriction is turned off.
|
||||
|
||||
The search returns a list of
|
||||
users matching your criteria. User properties can be edited by clicking
|
||||
the login name. The Account History of a user can be viewed by clicking
|
||||
the "View" link in the Account History column. The Account History
|
||||
displays changes that have been made to the user account, the time of
|
||||
the change and the user who made the change. For example, the Account
|
||||
History page will display details of when a user was added or removed
|
||||
from a group.
|
||||
|
||||
.. _createnewusers:
|
||||
|
||||
Creating new users
|
||||
------------------
|
||||
|
||||
.. _self-registration:
|
||||
|
||||
Self-registration
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
By default, users can create their own user accounts by clicking the
|
||||
``New Account`` link at the bottom of each page (assuming
|
||||
they aren't logged in as someone else already). If you want to disable
|
||||
this self-registration, or if you want to restrict who can create his
|
||||
own user account, you have to edit the ``createemailregexp``
|
||||
parameter in the ``Configuration`` page, see
|
||||
:ref:`parameters`.
|
||||
|
||||
.. _user-account-creation:
|
||||
|
||||
Accounts created by an administrator
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Users with ``editusers`` privileges, such as administrators,
|
||||
can create user accounts for other users:
|
||||
|
||||
#. After logging in, click the "Users" link at the footer of
|
||||
the query page, and then click "Add a new user".
|
||||
|
||||
#. Fill out the form presented. This page is self-explanatory.
|
||||
When done, click "Submit".
|
||||
|
||||
.. note:: Adding a user this way will *not*
|
||||
send an email informing them of their username and password.
|
||||
While useful for creating dummy accounts (watchers which
|
||||
shuttle mail to another system, for instance, or email
|
||||
addresses which are a mailing list), in general it is
|
||||
preferable to log out and use the ``New Account``
|
||||
button to create users, as it will pre-populate all the
|
||||
required fields and also notify the user of her account name
|
||||
and password.
|
||||
|
||||
.. _modifyusers:
|
||||
|
||||
Modifying Users
|
||||
---------------
|
||||
|
||||
Once you have found your user, you can change the following
|
||||
fields:
|
||||
|
||||
- *Login Name*:
|
||||
This is generally the user's full email address. However, if you
|
||||
have are using the ``emailsuffix`` parameter, this may
|
||||
just be the user's login name. Note that users can now change their
|
||||
login names themselves (to any valid email address).
|
||||
|
||||
- *Real Name*: The user's real name. Note that
|
||||
Bugzilla does not require this to create an account.
|
||||
|
||||
- *Password*:
|
||||
You can change the user's password here. Users can automatically
|
||||
request a new password, so you shouldn't need to do this often.
|
||||
If you want to disable an account, see Disable Text below.
|
||||
|
||||
- *Bugmail Disabled*:
|
||||
Mark this checkbox to disable bugmail and whinemail completely
|
||||
for this account. This checkbox replaces the data/nomail file
|
||||
which existed in older versions of Bugzilla.
|
||||
|
||||
- *Disable Text*:
|
||||
If you type anything in this box, including just a space, the
|
||||
user is prevented from logging in, or making any changes to
|
||||
bugs via the web interface.
|
||||
The HTML you type in this box is presented to the user when
|
||||
they attempt to perform these actions, and should explain
|
||||
why the account was disabled.
|
||||
Users with disabled accounts will continue to receive
|
||||
mail from Bugzilla; furthermore, they will not be able
|
||||
to log in themselves to change their own preferences and
|
||||
stop it. If you want an account (disabled or active) to
|
||||
stop receiving mail, simply check the
|
||||
``Bugmail Disabled`` checkbox above.
|
||||
|
||||
.. note:: Even users whose accounts have been disabled can still
|
||||
submit bugs via the e-mail gateway, if one exists.
|
||||
The e-mail gateway should *not* be
|
||||
enabled for secure installations of Bugzilla.
|
||||
|
||||
.. warning:: Don't disable all the administrator accounts!
|
||||
|
||||
- *<groupname>*:
|
||||
If you have created some groups, e.g. "securitysensitive", then
|
||||
checkboxes will appear here to allow you to add users to, or
|
||||
remove them from, these groups. The first checkbox gives the
|
||||
user the ability to add and remove other users as members of
|
||||
this group. The second checkbox adds the user himself as a member
|
||||
of the group.
|
||||
|
||||
- *canconfirm*:
|
||||
This field is only used if you have enabled the "unconfirmed"
|
||||
status. If you enable this for a user,
|
||||
that user can then move bugs from "Unconfirmed" to a "Confirmed"
|
||||
status (e.g.: "New" status).
|
||||
|
||||
- *creategroups*:
|
||||
This option will allow a user to create and destroy groups in
|
||||
Bugzilla.
|
||||
|
||||
- *editbugs*:
|
||||
Unless a user has this bit set, they can only edit those bugs
|
||||
for which they are the assignee or the reporter. Even if this
|
||||
option is unchecked, users can still add comments to bugs.
|
||||
|
||||
- *editcomponents*:
|
||||
This flag allows a user to create new products and components,
|
||||
as well as modify and destroy those that have no bugs associated
|
||||
with them. If a product or component has bugs associated with it,
|
||||
those bugs must be moved to a different product or component
|
||||
before Bugzilla will allow them to be destroyed.
|
||||
|
||||
- *editkeywords*:
|
||||
If you use Bugzilla's keyword functionality, enabling this
|
||||
feature allows a user to create and destroy keywords. As always,
|
||||
the keywords for existing bugs containing the keyword the user
|
||||
wishes to destroy must be changed before Bugzilla will allow it
|
||||
to die.
|
||||
|
||||
- *editusers*:
|
||||
This flag allows a user to do what you're doing right now: edit
|
||||
other users. This will allow those with the right to do so to
|
||||
remove administrator privileges from other users or grant them to
|
||||
themselves. Enable with care.
|
||||
|
||||
- *tweakparams*:
|
||||
This flag allows a user to change Bugzilla's Params
|
||||
(using :file:`editparams.cgi`.)
|
||||
|
||||
- *<productname>*:
|
||||
This allows an administrator to specify the products
|
||||
in which a user can see bugs. If you turn on the
|
||||
``makeproductgroups`` parameter in
|
||||
the Group Security Panel in the Parameters page,
|
||||
then Bugzilla creates one group per product (at the time you create
|
||||
the product), and this group has exactly the same name as the
|
||||
product itself. Note that for products that already exist when
|
||||
the parameter is turned on, the corresponding group will not be
|
||||
created. The user must still have the ``editbugs``
|
||||
privilege to edit bugs in these products.
|
||||
|
||||
.. _user-account-deletion:
|
||||
|
||||
Deleting Users
|
||||
--------------
|
||||
|
||||
If the ``allowuserdeletion`` parameter is turned on, see
|
||||
:ref:`parameters`, then you can also delete user accounts.
|
||||
Note that this is most of the time not the best thing to do. If only
|
||||
a warning in a yellow box is displayed, then the deletion is safe.
|
||||
If a warning is also displayed in a red box, then you should NOT try
|
||||
to delete the user account, else you will get referential integrity
|
||||
problems in your database, which can lead to unexpected behavior,
|
||||
such as bugs not appearing in bug lists anymore, or data displaying
|
||||
incorrectly. You have been warned!
|
||||
|
||||
.. _impersonatingusers:
|
||||
|
||||
Impersonating Users
|
||||
-------------------
|
||||
|
||||
There may be times when an administrator would like to do something as
|
||||
another user. The :command:`sudo` feature may be used to do
|
||||
this.
|
||||
|
||||
.. note:: To use the sudo feature, you must be in the
|
||||
*bz_sudoers* group. By default, all
|
||||
administrators are in this group.
|
||||
|
||||
If you have access to this feature, you may start a session by
|
||||
going to the Edit Users page, Searching for a user and clicking on
|
||||
their login. You should see a link below their login name titled
|
||||
"Impersonate this user". Click on the link. This will take you
|
||||
to a page where you will see a description of the feature and
|
||||
instructions for using it. After reading the text, simply
|
||||
enter the login of the user you would like to impersonate, provide
|
||||
a short message explaining why you are doing this, and press the
|
||||
button.
|
||||
|
||||
As long as you are using this feature, everything you do will be done
|
||||
as if you were logged in as the user you are impersonating.
|
||||
|
||||
.. warning:: The user you are impersonating will not be told about what you are
|
||||
doing. If you do anything that results in mail being sent, that
|
||||
mail will appear to be from the user you are impersonating. You
|
||||
should be extremely careful while using this feature.
|
||||
|
||||
@ -0,0 +1,5 @@
|
||||
.. _versions-and-milestones:
|
||||
|
||||
Versions and Milestones
|
||||
#######################
|
||||
|
||||
@ -0,0 +1,8 @@
|
||||
.. _whining:
|
||||
|
||||
Whining
|
||||
#######
|
||||
|
||||
XXX Link to the bit of the docs about setting up the cron job
|
||||
|
||||
XXX Explain about admin interface to whines here
|
||||
@ -0,0 +1,18 @@
|
||||
.. _workflow:
|
||||
|
||||
Workflow
|
||||
########
|
||||
|
||||
The bug status workflow is no longer hardcoded but can be freely customized
|
||||
from the web interface. Only one bug status cannot be renamed nor deleted,
|
||||
UNCONFIRMED, but the workflow involving it is free. The configuration
|
||||
page displays all existing bug statuses twice, first on the left for bug
|
||||
statuses we come from and on the top for bug statuses we move to.
|
||||
If the checkbox is checked, then the transition between the two bug statuses
|
||||
is legal, else it's forbidden independently of your privileges. The bug status
|
||||
used for the "duplicate_or_move_bug_status" parameter must be part of the
|
||||
workflow as that is the bug status which will be used when duplicating or
|
||||
moving a bug, so it must be available from each bug status.
|
||||
|
||||
When the workflow is set, the "View Current Triggers" link below the table
|
||||
lets you set which transitions require a comment from the user.
|
||||
@ -1,3 +1,8 @@
|
||||
.. _existing-parameters:
|
||||
|
||||
Existing Parameters and Options
|
||||
===============================
|
||||
|
||||
You may find that Bugzilla already does what you want it to do, you just
|
||||
need to configure it correctly. Read the :ref:`administering` sections
|
||||
carefully to see if that's the case for you.
|
||||
|
||||
@ -1,7 +1,7 @@
|
||||
.. _extensions:
|
||||
|
||||
Extensions
|
||||
==========
|
||||
##########
|
||||
|
||||
One of the best ways to customize Bugzilla is by writing a Bugzilla
|
||||
Extension. Bugzilla Extensions let you modify both the code and
|
||||
@ -9,6 +9,7 @@ UI of Bugzilla in a way that can be distributed to other Bugzilla
|
||||
users and ported forward to future versions of Bugzilla with minimal
|
||||
effort.
|
||||
|
||||
See the `Bugzilla Extension
|
||||
documentation <../html/api/Bugzilla/Extension.html>`_ for information on how to write an Extension.
|
||||
|
||||
We maintain a
|
||||
`list of available extensions <https://wiki.mozilla.org/Bugzilla:Addons>`_
|
||||
on our wiki. You would need to
|
||||
make sure that the extension in question works with your version of Bugzilla.
|
||||
|
||||
@ -2,6 +2,11 @@ Languages
|
||||
=========
|
||||
|
||||
Bugzilla's templates can be localized, although it's a big job. If you have
|
||||
a localized set of templates for your version of Bugzilla, Bugzilla can also
|
||||
support multiple languages at once, with the user choosing which UI language
|
||||
they would prefer.
|
||||
a localized set of templates for your version of Bugzilla, Bugzilla can
|
||||
support multiple languages at once. In that case, Bugzilla honours the user's
|
||||
``Accept-Language`` HTTP header when deciding which language to serve.
|
||||
|
||||
Many language templates can be obtained from
|
||||
`the localization section of the Bugzilla website
|
||||
<http://www.bugzilla.org/download.html#localizations>`_. Instructions
|
||||
for submitting new languages are also available from that location.
|
||||
|
||||
@ -3,13 +3,11 @@
|
||||
Templates
|
||||
#########
|
||||
|
||||
Administrators can configure the look and feel of Bugzilla without
|
||||
having to edit Perl files or face the nightmare of massive merge
|
||||
conflicts when they upgrade to a newer version in the future.
|
||||
|
||||
It's possible to have Bugzilla's UI language
|
||||
determined by the user's browser. More information is available in
|
||||
:ref:`template-http-accept`.
|
||||
Bugzilla uses a system of templates to define its user interface. Templates
|
||||
can be modified, replaced or overridden. This means that administrators can
|
||||
configure the look and feel of Bugzilla without having to edit Perl files or
|
||||
facing the nightmare of massive merge conflicts when they upgrade to a newer
|
||||
version in the future.
|
||||
|
||||
.. _template-directory:
|
||||
|
||||
@ -18,8 +16,7 @@ Template Directory Structure
|
||||
|
||||
The template directory structure starts with top level directory
|
||||
named :file:`template`, which contains a directory
|
||||
for each installed localization. The next level defines the
|
||||
language used in the templates. Bugzilla comes with English
|
||||
for each installed localization. Bugzilla comes with English
|
||||
templates, so the directory name is :file:`en`,
|
||||
and we will discuss :file:`template/en` throughout
|
||||
the documentation. Below :file:`template/en` is the
|
||||
@ -56,16 +53,11 @@ into a mirrored directory structure under
|
||||
:file:`template/en/custom`. Templates in this
|
||||
directory structure automatically override any identically-named
|
||||
and identically-located templates in the
|
||||
:file:`default` directory.
|
||||
:file:`template/en/default` directory. (The :file:`custom` directory does not
|
||||
exist by default and must be created if you want to use it.)
|
||||
|
||||
The :file:`custom` directory does not exist at first and must be created if
|
||||
you want to use it.
|
||||
|
||||
The second method of customization should be used if you
|
||||
use the overwriting method of upgrade, because otherwise
|
||||
your changes will be lost. This method may also be better if
|
||||
you are using the Bzr method of upgrading and are going to make major
|
||||
changes, because it is guaranteed that the contents of this directory
|
||||
The second method of customization should be used if you are going to make
|
||||
major changes, because it is guaranteed that the contents of this directory
|
||||
will not be touched during an upgrade, and you can then decide whether
|
||||
to continue using your own templates, or make the effort to merge your
|
||||
changes into the new versions by hand.
|
||||
@ -73,34 +65,22 @@ changes into the new versions by hand.
|
||||
Using this method, your installation may break if incompatible
|
||||
changes are made to the template interface. Such changes should
|
||||
be documented in the release notes, provided you are using a
|
||||
stable release of Bugzilla. If you use using unstable code, you will
|
||||
need to deal with this one yourself, although if possible the changes
|
||||
will be mentioned before they occur in the deprecations section of the
|
||||
previous stable release's release notes.
|
||||
|
||||
.. note:: Regardless of which method you choose, it is recommended that
|
||||
you run :command:`./checksetup.pl` after
|
||||
editing any templates in the :file:`template/en/default`
|
||||
directory, and after creating or editing any templates in
|
||||
the :file:`custom` directory.
|
||||
|
||||
.. warning:: It is *required* that you run :command:`./checksetup.pl` after
|
||||
creating a new
|
||||
template in the :file:`custom` directory. Failure
|
||||
to do so will raise an incomprehensible error message.
|
||||
stable release of Bugzilla, so you should be able to see them coming.
|
||||
|
||||
.. _template-edit:
|
||||
|
||||
How To Edit Templates
|
||||
=====================
|
||||
|
||||
.. note:: If you are making template changes that you intend on submitting back
|
||||
for inclusion in standard Bugzilla, you should read the relevant
|
||||
.. note:: If you are making template changes that you intend on submitting
|
||||
back for inclusion in standard Bugzilla, you should read the relevant
|
||||
sections of the
|
||||
`Developers'
|
||||
Guide <http://www.bugzilla.org/docs/developer.html>`_.
|
||||
`Developers' Guide <http://www.bugzilla.org/docs/developer.html>`_.
|
||||
|
||||
The syntax of the Template Toolkit language is beyond the scope of
|
||||
XXX Is this still there?
|
||||
|
||||
Bugzilla uses a templating system called Template Toolkit. The syntax of the
|
||||
TT language is beyond the scope of
|
||||
this guide. It's reasonably easy to pick up by looking at the current
|
||||
templates; or, you can read the manual, available on the
|
||||
`Template Toolkit home
|
||||
@ -115,14 +95,18 @@ Template Toolkit to do this (or the 'uri' filter to encode special
|
||||
characters in URLs). If you forget, you may open up your installation
|
||||
to cross-site scripting attacks.
|
||||
|
||||
Editing templates is a good way of doing a ``poor man's custom
|
||||
fields``.
|
||||
For example, if you don't use the Status Whiteboard, but want to have
|
||||
a free-form text entry box for ``Build Identifier``,
|
||||
XXXMOVE Editing templates is a good way of doing a 'poor man's custom
|
||||
fields'.
|
||||
For example, if you don't use the :guilabel:`Status Whiteboard`, but want to
|
||||
have a free-form text entry box for :guilabel:`Build Identifier`,
|
||||
then you can just
|
||||
edit the templates to change the field labels. It's still be called
|
||||
status_whiteboard internally, but your users don't need to know that.
|
||||
|
||||
.. note:: you should run :command:`./checksetup.pl` after
|
||||
editing any templates. Failure to do so may mean your changes are
|
||||
not picked up.
|
||||
|
||||
.. _template-formats:
|
||||
|
||||
Template Formats and Types
|
||||
@ -179,130 +163,116 @@ Particular Templates
|
||||
There are a few templates you may be particularly interested in
|
||||
customizing for your installation.
|
||||
|
||||
:command:`index.html.tmpl`:
|
||||
This is the Bugzilla front page.
|
||||
:file:`index.html.tmpl`:
|
||||
This is the Bugzilla front page.
|
||||
|
||||
:command:`global/header.html.tmpl`:
|
||||
This defines the header that goes on all Bugzilla pages.
|
||||
The header includes the banner, which is what appears to users
|
||||
and is probably what you want to edit instead. However the
|
||||
header also includes the HTML HEAD section, so you could for
|
||||
example add a stylesheet or META tag by editing the header.
|
||||
:file:`global/header.html.tmpl`:
|
||||
This defines the header that goes on all Bugzilla pages.
|
||||
The header includes the banner, which is what appears to users
|
||||
and is probably what you want to edit instead. However the
|
||||
header also includes the HTML HEAD section, so you could for
|
||||
example add a stylesheet or META tag by editing the header.
|
||||
|
||||
:command:`global/banner.html.tmpl`:
|
||||
This contains the ``banner``, the part of the header
|
||||
that appears
|
||||
at the top of all Bugzilla pages. The default banner is reasonably
|
||||
barren, so you'll probably want to customize this to give your
|
||||
installation a distinctive look and feel. It is recommended you
|
||||
preserve the Bugzilla version number in some form so the version
|
||||
you are running can be determined, and users know what docs to read.
|
||||
:file:`global/banner.html.tmpl`:
|
||||
This contains the ``banner``, the part of the header that appears
|
||||
at the top of all Bugzilla pages. The default banner is reasonably
|
||||
barren, so you'll probably want to customize this to give your
|
||||
installation a distinctive look and feel. It is recommended you
|
||||
preserve the Bugzilla version number in some form so the version
|
||||
you are running can be determined, and users know what docs to read.
|
||||
|
||||
:command:`global/footer.html.tmpl`:
|
||||
This defines the footer that goes on all Bugzilla pages. Editing
|
||||
this is another way to quickly get a distinctive look and feel for
|
||||
your Bugzilla installation.
|
||||
:file:`global/footer.html.tmpl`:
|
||||
This defines the footer that goes on all Bugzilla pages. Editing
|
||||
this is another way to quickly get a distinctive look and feel for
|
||||
your Bugzilla installation.
|
||||
|
||||
:command:`global/variables.none.tmpl`:
|
||||
XXX Need to describe the use of this file
|
||||
:file:`global/variables.none.tmpl`:
|
||||
XXX Need to describe the use of this file
|
||||
|
||||
:command:`list/table.html.tmpl`:
|
||||
This template controls the appearance of the bug lists created
|
||||
by Bugzilla. Editing this template allows per-column control of
|
||||
the width and title of a column, the maximum display length of
|
||||
each entry, and the wrap behaviour of long entries.
|
||||
For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
|
||||
default; this behaviour is also controlled by this template, and
|
||||
that value can be modified here.
|
||||
:file:`list/table.html.tmpl`:
|
||||
This template controls the appearance of the bug lists created
|
||||
by Bugzilla. Editing this template allows per-column control of
|
||||
the width and title of a column, the maximum display length of
|
||||
each entry, and the wrap behaviour of long entries.
|
||||
For long bug lists, Bugzilla inserts a 'break' every 100 bugs by
|
||||
default; this behaviour is also controlled by this template, and
|
||||
that value can be modified here.
|
||||
|
||||
:command:`bug/create/user-message.html.tmpl`:
|
||||
This is a message that appears near the top of the bug reporting page.
|
||||
By modifying this, you can tell your users how they should report
|
||||
bugs.
|
||||
:file:`bug/create/user-message.html.tmpl`:
|
||||
This is a message that appears near the top of the bug reporting page.
|
||||
By modifying this, you can tell your users how they should report
|
||||
bugs.
|
||||
|
||||
:command:`bug/process/midair.html.tmpl`:
|
||||
This is the page used if two people submit simultaneous changes to the
|
||||
same bug. The second person to submit their changes will get this page
|
||||
to tell them what the first person did, and ask if they wish to
|
||||
overwrite those changes or go back and revisit the bug. The default
|
||||
title and header on this page read "Mid-air collision detected!" If
|
||||
you work in the aviation industry, or other environment where this
|
||||
might be found offensive (yes, we have true stories of this happening)
|
||||
you'll want to change this to something more appropriate for your
|
||||
environment.
|
||||
:file:`bug/process/midair.html.tmpl`:
|
||||
This is the page used if two people submit simultaneous changes to the
|
||||
same bug. The second person to submit their changes will get this page
|
||||
to tell them what the first person did, and ask if they wish to
|
||||
overwrite those changes or go back and revisit the bug. The default
|
||||
title and header on this page read "Mid-air collision detected!" If
|
||||
you work in the aviation industry, or other environment where this
|
||||
might be found offensive (yes, we have true stories of this happening)
|
||||
you'll want to change this to something more appropriate for your
|
||||
environment.
|
||||
|
||||
:command:`bug/create/create.html.tmpl` and
|
||||
:command:`bug/create/comment.txt.tmpl`:
|
||||
You may not wish to go to the effort of creating custom fields in
|
||||
Bugzilla, yet you want to make sure that each bug report contains
|
||||
a number of pieces of important information for which there is not
|
||||
a special field. The bug entry system has been designed in an
|
||||
extensible fashion to enable you to add arbitrary HTML widgets,
|
||||
such as drop-down lists or textboxes, to the bug entry page
|
||||
and have their values appear formatted in the initial comment.
|
||||
A hidden field that indicates the format should be added inside
|
||||
the form in order to make the template functional. Its value should
|
||||
be the suffix of the template filename. For example, if the file
|
||||
is called :file:`create-cust.html.tmpl`, then
|
||||
:file:`bug/create/create.html.tmpl` and :file:`bug/create/comment.txt.tmpl`:
|
||||
You may not wish to go to the effort of creating custom fields in
|
||||
Bugzilla, yet you want to make sure that each bug report contains
|
||||
a number of pieces of important information for which there is not
|
||||
a special field. The bug entry system has been designed in an
|
||||
extensible fashion to enable you to add arbitrary HTML widgets,
|
||||
such as drop-down lists or textboxes, to the bug entry page
|
||||
and have their values appear formatted in the initial comment.
|
||||
A hidden field that indicates the format should be added inside
|
||||
the form in order to make the template functional. Its value should
|
||||
be the suffix of the template filename. For example, if the file
|
||||
is called :file:`create-cust.html.tmpl`, then
|
||||
|
||||
::
|
||||
::
|
||||
|
||||
<input type="hidden" name="format" value="cust">
|
||||
<input type="hidden" name="format" value="cust">
|
||||
|
||||
should be used inside the form.
|
||||
should be used inside the form.
|
||||
|
||||
An example of this is the mozilla.org
|
||||
`guided
|
||||
bug submission form <http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided>`_. The code for this comes with the Bugzilla
|
||||
distribution as an example for you to copy. It can be found in the
|
||||
files
|
||||
:file:`create-guided.html.tmpl` and
|
||||
:file:`comment-guided.html.tmpl`.
|
||||
An example of this is the mozilla.org
|
||||
`guided
|
||||
bug submission form <http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided>`_. The code for this comes with the Bugzilla
|
||||
distribution as an example for you to copy. It can be found in the
|
||||
files
|
||||
:file:`create-guided.html.tmpl` and :file:`comment-guided.html.tmpl`.
|
||||
|
||||
So to use this feature, create a custom template for
|
||||
:file:`enter_bug.cgi`. The default template, on which you
|
||||
could base it, is
|
||||
:file:`custom/bug/create/create.html.tmpl`.
|
||||
Call it :file:`create-<formatname>.html.tmpl`, and
|
||||
in it, add widgets for each piece of information you'd like
|
||||
collected - such as a build number, or set of steps to reproduce.
|
||||
So to use this feature, create a custom template for
|
||||
:file:`enter_bug.cgi`. The default template, on which you
|
||||
could base it, is
|
||||
:file:`custom/bug/create/create.html.tmpl`.
|
||||
Call it :file:`create-<formatname>.html.tmpl`, and
|
||||
in it, add widgets for each piece of information you'd like
|
||||
collected - such as a build number, or set of steps to reproduce.
|
||||
|
||||
Then, create a template like
|
||||
:file:`custom/bug/create/comment.txt.tmpl`, and call it
|
||||
:file:`comment-<formatname>.txt.tmpl`. This
|
||||
template should reference the form fields you have created using
|
||||
the syntax :file:`[% form.<fieldname> %]`. When a
|
||||
bug report is
|
||||
submitted, the initial comment attached to the bug report will be
|
||||
formatted according to the layout of this template.
|
||||
Then, create a template like
|
||||
:file:`custom/bug/create/comment.txt.tmpl`, and call it
|
||||
:file:`comment-<formatname>.txt.tmpl`. This
|
||||
template should reference the form fields you have created using
|
||||
the syntax :file:`[% form.<fieldname> %]`. When a
|
||||
bug report is
|
||||
submitted, the initial comment attached to the bug report will be
|
||||
formatted according to the layout of this template.
|
||||
|
||||
For example, if your custom enter_bug template had a field
|
||||
For example, if your custom enter_bug template had a field
|
||||
|
||||
::
|
||||
::
|
||||
|
||||
<input type="text" name="buildid" size="30">
|
||||
<input type="text" name="buildid" size="30">
|
||||
|
||||
and then your comment.txt.tmpl had
|
||||
and then your comment.txt.tmpl had
|
||||
|
||||
::
|
||||
::
|
||||
|
||||
BuildID: \[% form.buildid %]
|
||||
BuildID: [% form.buildid %]
|
||||
|
||||
then something like
|
||||
then something like
|
||||
|
||||
::
|
||||
::
|
||||
|
||||
BuildID: 20020303
|
||||
BuildID: 20140303
|
||||
|
||||
would appear in the initial comment.
|
||||
|
||||
.. _template-http-accept:
|
||||
|
||||
Configuring Bugzilla to Detect the User's Language
|
||||
==================================================
|
||||
|
||||
Bugzilla honours the user's Accept: HTTP header. You can install
|
||||
templates in other languages, and Bugzilla will pick the most appropriate
|
||||
according to a priority order defined by you. Many
|
||||
language templates can be obtained from `<http://www.bugzilla.org/download.html#localizations>`_. Instructions
|
||||
for submitting new languages are also available from that location.
|
||||
would appear in the initial comment.
|
||||
|
||||
@ -3,13 +3,6 @@
|
||||
Who Can Change What
|
||||
###################
|
||||
|
||||
.. warning:: This feature should be considered experimental; the Bugzilla code you
|
||||
will be changing is not stable, and could change or move between
|
||||
versions. Be aware that if you make modifications as outlined here,
|
||||
you may have
|
||||
to re-make them or port them if Bugzilla changes internally between
|
||||
versions, and you upgrade.
|
||||
|
||||
Companies often have rules about which employees, or classes of employees,
|
||||
are allowed to change certain things in the bug system. For example,
|
||||
only the bug's designated QA Contact may be allowed to VERIFY the bug.
|
||||
@ -25,81 +18,7 @@ fields, but in a more restrictive manner. Other users, without
|
||||
*editbugs* privileges, cannot edit
|
||||
bugs, except to comment and add themselves to the CC list.
|
||||
|
||||
For maximum flexibility, customizing this means editing Bugzilla's Perl
|
||||
code. This gives the administrator complete control over exactly who is
|
||||
allowed to do what. The relevant method is called
|
||||
:file:`check_can_change_field()`,
|
||||
and is found in :file:`Bug.pm` in your
|
||||
Bugzilla/ directory. If you open that file and search for
|
||||
``sub check_can_change_field``, you'll find it.
|
||||
|
||||
This function has been carefully commented to allow you to see exactly
|
||||
how it works, and give you an idea of how to make changes to it.
|
||||
Certain marked sections should not be changed - these are
|
||||
the ``plumbing`` which makes the rest of the function work.
|
||||
In between those sections, you'll find snippets of code like:
|
||||
|
||||
::
|
||||
|
||||
# Allow the assignee to change anything.
|
||||
if ($ownerid eq $whoid) {
|
||||
return 1;
|
||||
}
|
||||
|
||||
It's fairly obvious what this piece of code does.
|
||||
|
||||
So, how does one go about changing this function? Well, simple changes
|
||||
can be made just by removing pieces - for example, if you wanted to
|
||||
prevent any user adding a comment to a bug, just remove the lines marked
|
||||
``Allow anyone to change comments.`` If you don't want the
|
||||
Reporter to have any special rights on bugs they have filed, just
|
||||
remove the entire section that deals with the Reporter.
|
||||
|
||||
More complex customizations are not much harder. Basically, you add
|
||||
a check in the right place in the function, i.e. after all the variables
|
||||
you are using have been set up. So, don't look at $ownerid before
|
||||
$ownerid has been obtained from the database. You can either add a
|
||||
positive check, which returns 1 (allow) if certain conditions are true,
|
||||
or a negative check, which returns 0 (deny.) E.g.:
|
||||
|
||||
::
|
||||
|
||||
if ($field eq "qacontact") {
|
||||
if (Bugzilla->user->in_group("quality_assurance")) {
|
||||
return 1;
|
||||
}
|
||||
else {
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
This says that only users in the group "quality_assurance" can change
|
||||
the QA Contact field of a bug.
|
||||
|
||||
Getting more weird:
|
||||
|
||||
::
|
||||
|
||||
if (($field eq "priority") &&
|
||||
(Bugzilla->user->email =~ /.*\\@example\\.com$/))
|
||||
{
|
||||
if ($oldvalue eq "P1") {
|
||||
return 1;
|
||||
}
|
||||
else {
|
||||
return 0;
|
||||
}
|
||||
}
|
||||
|
||||
This says that if the user is trying to change the priority field,
|
||||
and their email address is @example.com, they can only do so if the
|
||||
old value of the field was "P1". Not very useful, but illustrative.
|
||||
|
||||
.. warning:: If you are modifying :file:`process_bug.cgi` in any
|
||||
way, do not change the code that is bounded by DO_NOT_CHANGE blocks.
|
||||
Doing so could compromise security, or cause your installation to
|
||||
stop working entirely.
|
||||
|
||||
For a list of possible field names, look at the bugs table in the
|
||||
database. If you need help writing custom rules for your organization,
|
||||
ask in the newsgroup.
|
||||
Because this kind of change is such a common request, we have added a
|
||||
specific hook for it that :ref:`extensions` can call. It's called
|
||||
``bug_check_can_change_field``, and it's documented `in the Hooks
|
||||
documentation <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Hook.html#bug_check_can_change_field>`_.
|
||||
|
||||
@ -0,0 +1,10 @@
|
||||
.. _writing-extensions:
|
||||
|
||||
Writing Extensions
|
||||
##################
|
||||
|
||||
See the `Bugzilla Extension
|
||||
documentation <../html/api/Bugzilla/Extension.html>`_ for information on how
|
||||
to write an Extension.
|
||||
|
||||
XXX Also https://wiki.mozilla.org/Bugzilla:Extension_Notes
|
||||
@ -3,7 +3,7 @@ Bugzilla Documentation
|
||||
======================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 3
|
||||
:maxdepth: 2
|
||||
:numbered:
|
||||
|
||||
about
|
||||
|
||||
@ -0,0 +1,197 @@
|
||||
.. _post-install-config:
|
||||
|
||||
Post-Installation Configuration
|
||||
###############################
|
||||
|
||||
Bugzilla is configured in the Administration Parameters. Log in with the
|
||||
administrator account you defined in the last :file:`checksetup.pl` run,
|
||||
then click :guilabel:`Administration` in the header, and then
|
||||
:guilabel:`Parameters`. You will see the different parameter sections
|
||||
down the left hand side of the page.
|
||||
|
||||
Essential
|
||||
=========
|
||||
|
||||
There are a few parameters which it is very important to define (or
|
||||
explicitly decide not to change).
|
||||
|
||||
The first set of these are in the :guilabel:`Required Settings` section.
|
||||
|
||||
* :guilabel:`urlbase`: this is the URL by which people should access
|
||||
Bugzilla's front page.
|
||||
* :guilabel:`sslbase`: if you have configured SSL on your Bugzilla server,
|
||||
this is the SSL URL by which people should access Bugzilla's front page.
|
||||
* :guilabel:`ssl_redirect`: Set this if you want everyone to be redirected
|
||||
to use the SSL version. Recommended if you have set up SSL.
|
||||
* :guilabel:`cookiebase`: Bugzilla uses cookies to remember who each user is.
|
||||
In order to set those cookies in the correct scope, you may need to set a
|
||||
cookiebase. If your Bugzilla is at the root of your domain, you don't need
|
||||
to change the default value.
|
||||
|
||||
You will also need to tell Bugzilla how to :ref:`send email <email>`.
|
||||
|
||||
You may want to put your email address in the :guilabel:`maintainer`
|
||||
parameter in the :guilabel:`General` section. This will then let people
|
||||
know who to contact if they see problems or hit errors.
|
||||
|
||||
If you don't want just anyone able to read your Bugzilla, set the
|
||||
:guilabel:`requirelogin` parameter in the :guilabel:`User Authentication`
|
||||
section, and change or clear the :guilabel:`createemailregexp` parameter.
|
||||
|
||||
.. _optional-features:
|
||||
|
||||
Optional
|
||||
========
|
||||
|
||||
XXXHACKME
|
||||
|
||||
Bugzilla has a number of optional features. This section describes how
|
||||
to configure or enable them.
|
||||
|
||||
Bug Graphs
|
||||
----------
|
||||
|
||||
If you have installed the necessary Perl modules you
|
||||
can start collecting statistics for the nifty Bugzilla
|
||||
graphs.
|
||||
|
||||
::
|
||||
|
||||
# crontab -e
|
||||
|
||||
This should bring up the crontab file in your editor.
|
||||
Add a cron entry like this to run
|
||||
:file:`collectstats.pl`
|
||||
daily at 5 after midnight:
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
5 0 * * * cd <your-bugzilla-directory> && ./collectstats.pl
|
||||
|
||||
After two days have passed you'll be able to view bug graphs from
|
||||
the Reports page.
|
||||
|
||||
.. note:: Windows does not have 'cron', but it does have the Task
|
||||
Scheduler, which performs the same duties. There are also
|
||||
third-party tools that can be used to implement cron, such as
|
||||
`nncron <http://www.nncron.ru/>`_.
|
||||
|
||||
.. _installation-whining-cron:
|
||||
|
||||
The Whining Cron
|
||||
----------------
|
||||
|
||||
What good are
|
||||
bugs if they're not annoying? To help make them more so you
|
||||
can set up Bugzilla's automatic whining system to complain at engineers
|
||||
which leave their bugs in the CONFIRMED state without triaging them.
|
||||
|
||||
This can be done by adding the following command as a daily
|
||||
crontab entry, in the same manner as explained above for bug
|
||||
graphs. This example runs it at 12.55am.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
55 0 * * * cd <your-bugzilla-directory> && ./whineatnews.pl
|
||||
|
||||
.. note:: Windows does not have 'cron', but it does have the Task
|
||||
Scheduler, which performs the same duties. There are also
|
||||
third-party tools that can be used to implement cron, such as
|
||||
`nncron <http://www.nncron.ru/>`_.
|
||||
|
||||
.. _installation-whining:
|
||||
|
||||
Whining
|
||||
-------
|
||||
|
||||
As of Bugzilla 2.20, 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
|
||||
in :ref:`whining`, but for it to work a Perl script must be
|
||||
executed at regular intervals.
|
||||
|
||||
This can be done by adding the following command as a daily
|
||||
crontab entry, in the same manner as explained above for bug
|
||||
graphs. This example runs it every 15 minutes.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
*/15 * * * * cd <your-bugzilla-directory> && ./whine.pl
|
||||
|
||||
.. note:: Whines can be executed as often as every 15 minutes, so if you specify
|
||||
longer intervals between executions of whine.pl, some users may not
|
||||
be whined at as often as they would expect. Depending on the person,
|
||||
this can either be a very Good Thing or a very Bad Thing.
|
||||
|
||||
.. note:: Windows does not have 'cron', but it does have the Task
|
||||
Scheduler, which performs the same duties. There are also
|
||||
third-party tools that can be used to implement cron, such as
|
||||
`nncron <http://www.nncron.ru/>`_.
|
||||
|
||||
.. _apache-addtype:
|
||||
|
||||
Serving Alternate Formats with the right MIME type
|
||||
--------------------------------------------------
|
||||
|
||||
Some Bugzilla pages have alternate formats, other than just plain
|
||||
HTML. In particular, a few Bugzilla pages can
|
||||
output their contents as either XUL (a special
|
||||
Mozilla format, that looks like a program GUI)
|
||||
or RDF (a type of structured XML
|
||||
that can be read by various programs).
|
||||
|
||||
In order for your users to see these pages correctly, Apache must
|
||||
send them with the right MIME type. To do this,
|
||||
add the following lines to your Apache configuration, either in the
|
||||
``<VirtualHost>`` section for your
|
||||
Bugzilla, or in the ``<Directory>``
|
||||
section for your Bugzilla:
|
||||
|
||||
.. code-block:: apache
|
||||
|
||||
AddType application/vnd.mozilla.xul+xml .xul
|
||||
AddType application/rdf+xml .rdf
|
||||
|
||||
.. _multiple-bz-dbs:
|
||||
|
||||
Multiple Bugzilla databases with a single installation
|
||||
------------------------------------------------------
|
||||
|
||||
The previous instructions referred to a standard installation, with
|
||||
one unique Bugzilla database. However, you may want to host several
|
||||
distinct installations, without having several copies of the code. This is
|
||||
possible by using the PROJECT environment variable. When accessed,
|
||||
Bugzilla checks for the existence of this variable, and if present, uses
|
||||
its value to check for an alternative configuration file named
|
||||
:file:`localconfig.<PROJECT>` in the same location as
|
||||
the default one (:file:`localconfig`). It also checks for
|
||||
customized templates in a directory named
|
||||
:file:`<PROJECT>` in the same location as the
|
||||
default one (:file:`template/<langcode>`). By default
|
||||
this is :file:`template/en/default` so PROJECT's templates
|
||||
would be located at :file:`template/en/PROJECT`.
|
||||
|
||||
To set up an alternate installation, just export PROJECT=foo before
|
||||
running :command:`checksetup.pl` for the first time. It will
|
||||
result in a file called :file:`localconfig.foo` instead of
|
||||
:file:`localconfig`. Edit this file as described above, with
|
||||
reference to a new database, and re-run :command:`checksetup.pl`
|
||||
to populate it. That's all.
|
||||
|
||||
Now you have to configure the web server to pass this environment
|
||||
variable when accessed via an alternate URL, such as virtual host for
|
||||
instance. The following is an example of how you could do it in Apache,
|
||||
other Webservers may differ.
|
||||
|
||||
.. code-block:: apache
|
||||
|
||||
<VirtualHost 212.85.153.228:80>
|
||||
ServerName foo.bar.baz
|
||||
SetEnv PROJECT foo
|
||||
Alias /bugzilla /var/www/bugzilla
|
||||
</VirtualHost>
|
||||
|
||||
Don't forget to also export this variable before accessing Bugzilla
|
||||
by other means, such as cron tasks for instance.
|
||||
|
||||
@ -0,0 +1,54 @@
|
||||
.. _apis:
|
||||
|
||||
APIs
|
||||
####
|
||||
|
||||
Bugzilla has a number of APIs that you can call in your code to extract
|
||||
information from and put information into it. The APIs currently supported
|
||||
are as follows:
|
||||
|
||||
Ad-Hoc APIs
|
||||
===========
|
||||
|
||||
Various pages on Bugzilla are available in machine-readable formats. For
|
||||
example, bugs can be downloaded as XML, and buglists as CSV. While the team
|
||||
attempts not to break these APIs, they should not be used for new code.
|
||||
|
||||
XML-RPC
|
||||
=======
|
||||
|
||||
Bugzilla has an XXXLINK XML-RPC API. This will receive no further updates and will
|
||||
be removed in a future version of Bugzilla.
|
||||
|
||||
JSON-RPC
|
||||
========
|
||||
|
||||
Bugzilla has a XXXLINK JSON-RPC API. This will receive no further updates and will
|
||||
be removed in a future version of Bugzilla.
|
||||
|
||||
REST
|
||||
====
|
||||
|
||||
Bugzilla has a XXXLINK REST API which is the currently-recommended API for
|
||||
integrating with Bugzilla. The current REST API is version 1. It is stable,
|
||||
and so will not be changed in a backwardly-incompatible way.
|
||||
|
||||
BzAPI-Compatible REST
|
||||
=====================
|
||||
|
||||
The first ever REST API for Bugzilla was implemented using an external proxy
|
||||
called BzAPI. This became popular enough that a BzAPI-compatible shim on top
|
||||
of the (native) REST API has been written, to allow code which used the BzAPI
|
||||
API to take advantage of the speed improvements of direct integration without
|
||||
needing to be rewritten. The shim is an extension which you would need to
|
||||
install in your Bugzilla.
|
||||
|
||||
Neither BzAPI nor this BzAPI-compatible API shim will receive any further
|
||||
updates, and they should not be used for new code.
|
||||
|
||||
REST v2
|
||||
=======
|
||||
|
||||
The future of Bugzilla's APIs is version 2 of the REST API, which will take
|
||||
the best of the current REST API and the BzAPI API. It is still under
|
||||
development.
|
||||
@ -1,12 +1,8 @@
|
||||
.. _integration:
|
||||
.. _tips:
|
||||
|
||||
Integration Tips
|
||||
################
|
||||
|
||||
|
||||
Integrating Bugzilla with Third-Party Tools
|
||||
###########################################
|
||||
|
||||
Many utilities and applications can integrate with Bugzilla,
|
||||
either on the client- or server-side. None of them are maintained
|
||||
by the Bugzilla community, nor are they tested during our
|
||||
QA tests, so use them at your own risk. They are listed at
|
||||
`<https://wiki.mozilla.org/Bugzilla:Addons>`_.
|
||||
|
||||
|
||||
|
||||
@ -1,8 +1,31 @@
|
||||
.. _sanity-check:
|
||||
|
||||
Sanity Check
|
||||
============
|
||||
############
|
||||
|
||||
Over time it is possible for the Bugzilla database to become corrupt
|
||||
or to have anomalies.
|
||||
This could happen through normal usage of Bugzilla, manual database
|
||||
administration outside of the Bugzilla user interface, or from some
|
||||
other unexpected event. Bugzilla includes a "Sanity Check" script that
|
||||
can perform several basic database checks, and repair certain problems or
|
||||
inconsistencies.
|
||||
|
||||
To run the "Sanity Check" script, log in as an Administrator and click the
|
||||
"Sanity Check" link in the admin page. Any problems that are found will be
|
||||
displayed in red letters. If the script is capable of fixing a problem,
|
||||
it will present a link to initiate the fix. If the script cannot
|
||||
fix the problem it will require manual database administration or recovery.
|
||||
|
||||
The "Sanity Check" script can also be run from the command line via the perl
|
||||
script :file:`sanitycheck.pl`. The script can also be run as
|
||||
a :command:`cron` job. Results will be delivered by email.
|
||||
|
||||
The "Sanity Check" script should be run on a regular basis as a matter of
|
||||
best practice.
|
||||
|
||||
.. warning:: The "Sanity Check" script is no substitute for a competent database
|
||||
administrator. It is only designed to check and repair basic database
|
||||
problems.
|
||||
|
||||
|
||||
Bugzilla has an option in the Administration panel called "Sanity Check",
|
||||
which makes sure the database is consistent in various ways. You should
|
||||
run it every few months or so.
|
||||
|
||||
@ -11,4 +11,4 @@ Upgrading Bugzilla
|
||||
upgrading/upgrading-with-git
|
||||
upgrading/upgrading-from-bazaar
|
||||
upgrading/upgrading-from-cvs
|
||||
upgrading/upgrading-from-a-tarball
|
||||
upgrading/upgrading-with-a-tarball
|
||||
|
||||
@ -0,0 +1,23 @@
|
||||
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.
|
||||
|
||||
@ -0,0 +1,49 @@
|
||||
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.
|
||||
@ -0,0 +1,113 @@
|
||||
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.
|
||||
|
||||
|extstatusinfo|
|
||||
|
||||
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.
|
||||
@ -3,193 +3,10 @@
|
||||
Upgrading from Bazaar
|
||||
#####################
|
||||
|
||||
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.
|
||||
.. |updatecommand| replace:: :command:`bzr up -r tag:bugzilla-$VERSION`
|
||||
.. |diffcommand| replace:: :command:`bzr diff > patch.diff`
|
||||
.. |extstatusinfo| replace:: The command :command:`bzr status extensions/` should help you work out what you added, if anything.
|
||||
|
||||
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:
|
||||
|
||||
:command:`bzr up -r tag:bugzilla-$VERSION`
|
||||
|
||||
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.
|
||||
|
||||
Save Any Local Customizations
|
||||
=============================
|
||||
|
||||
Go into your Bugzilla directory and run this command:
|
||||
|
||||
:command:`bzr diff > patch.diff`
|
||||
|
||||
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.
|
||||
|
||||
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-git`
|
||||
|
||||
:command:`cd bugzilla-git`
|
||||
|
||||
: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. :file:`bugzilla-git` is the name of the
|
||||
local directory into which the source code will be downloaded.
|
||||
|
||||
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-git/`:
|
||||
|
||||
.. 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:
|
||||
|
||||
:command:`bzr status extensions/`
|
||||
|
||||
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-git/`:
|
||||
|
||||
.. 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-git` 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-git 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, 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.
|
||||
.. include:: upgrading-from-1.rst
|
||||
.. include:: get-from-git.rst
|
||||
.. include:: upgrading-from-2.rst
|
||||
|
||||
@ -3,11 +3,14 @@
|
||||
Upgrading from CVS
|
||||
##################
|
||||
|
||||
XXX https://wiki.mozilla.org/Bugzilla:Moving_From_CVS_To_Bazaar
|
||||
XXX Fill in commands from https://wiki.mozilla.org/Bugzilla:Moving_From_CVS_To_Bazaar
|
||||
|
||||
.. |updatecommand| replace:: :command:`bzr up -r tag:bugzilla-$VERSION`
|
||||
.. |diffcommand| replace:: :command:`bzr diff > patch.diff`
|
||||
.. |extstatusinfo| replace:: The command :command:`bzr status extensions/` should help you work out what you added, if anything.
|
||||
|
||||
.. include:: upgrading-from-1.rst
|
||||
.. include:: get-from-git.rst
|
||||
.. include:: upgrading-from-2.rst
|
||||
|
||||
This will be the same as the Bzr instructions but using CVS commands.
|
||||
There are only 3 bzr commands, so we should be able to share the rest of
|
||||
the text.
|
||||
|
||||
I'm not going to fill it in until the Bzr instructions have had a review,
|
||||
to save having to maintain two copies of the same stuff.
|
||||
|
||||
@ -0,0 +1,189 @@
|
||||
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.
|
||||
Loading…
x
Reference in New Issue
Block a user