Classifications, Products, Components, Versions, and Milestones
***************************************************************

Bugs in Bugzilla are classified into one of a set of admin-defined
Components. Components are themselves each part of a single Product.
Optionally, Products can be part of a single Classification, adding a
third level to the hierarchy.


Classifications
===============

Classifications are used to group several related products into one
distinct entity.

For example, if a company makes computer games, they could have a
classification of "Games", and a separate product for each game. This
company might also have a "Common" classification, containing products
representing units of technology used in multiple games, and perhaps
an "Other" classification containing a few special products that
represent items that are not actually shipping products (for example,
"Website", or "Administration").

The classifications layer is disabled by default; it can be turned on
or off using the useclassification parameter in the *Bug Fields*
section of Parameters.

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 usually represent real-world shipping products. Many of
Bugzilla's settings are configurable on a per-product basis.

When creating or editing products the following options are available:

Product
   The name of the product

Description
   A brief description of the product

Open for bug entry
   Deselect this box to prevent new bugs from being entered against
   this product.

Enable the UNCONFIRMED status in this product
   Select this option if you want to use the UNCONFIRMED status (see
   Workflow)

Default milestone
   Select the default milestone for this product.

Version
   Specify the default version for this product.

Create chart datasets for this product
   Select to make chart datasets available for this product.

It is compulsory to create at least one component in a product, and so
you will be asked for the details of that too.

When editing a product you can change all of the above, and there is
also a link to edit Group Access Controls; see Assigning Group
Controls to Products.


Creating New Products
---------------------

To create a new product:

1. Select "Administration" from the footer and then choose
   "Products" from the main administration page.

2. Select the "Add" link in the bottom right.

3. Enter the details as outlined above.


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 defined when the product was created. Click on the product
name to edit these properties, and to access links to other product
attributes such as the product's components, versions, milestones, and
group access controls.


Adding or Editing Components, Versions and Target Milestones
------------------------------------------------------------

To add new or edit existing 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 an 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 Components.

For more information on versions, see Versions.

For more information on milestones, see Milestones.


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 Groups and Security.

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 (i.e. bugs in this product can be associated
with this group), default (i.e. bugs in this product are in this group
by default), and mandatory (i.e. 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 Common
Applications of Group Controls 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.


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". You would like to make it so
that only users in the group "Foo" can enter bugs in the "Bar"
product. Additionally, bugs filed in product "Bar" must be visible
only to users in "Foo" (plus, by default, the reporter, assignee, and
CC list of each bug) at all times. Furthermore, only members of group
"Foo" should be able to 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".
Instead, you would like to make it so that only members of group "Foo"
can enter bugs in product "Bar", but bugs in "Bar" are not required to
be restricted in visibility to people in "Foo". Anyone with permission
to edit a particular bug in product "Bar" can put the bug in group
"Foo", even if they themselves are not in "Foo".

Furthermore, anyone in group "Foo" can edit all aspects of the
components of product "Bar", can confirm bugs in product "Bar", and
can edit all fields of any bug in product "Bar". That would be done
like this:

   Product Bar:
   foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS


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:

1. Support Group: Contains members of the support staff.

2. AccessA Group: Contains users of product A and the Support
   group.

3. 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 Groups and Security.


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:

1. Select the "Edit components" link from the "Edit product" page.

2. Select the "Add" link in the bottom right.

3. Fill out the "Component" field, a short "Description", the
   "Default Assignee", "Default CC List", and "Default QA Contact" (if
   enabled). The "Component Description" field may contain a limited
   subset of HTML tags. The "Default Assignee" field must be a login
   name already existing in the Bugzilla database.


Versions
========

Versions are the revisions of the product, such as "Flinders 3.1",
"Flinders 95", and "Flinders 2000". Version is not a multi-select
field; the usual practice is to select the earliest version known to
have the bug.

To create and edit Versions:

1. From the "Edit product" screen, select "Edit Versions".

2. You will notice that the product already has the default version
   "undefined". Click the "Add" link in the bottom right.

3. Enter the name of the Version. This field takes text only. Then
   click the "Add" button.


Milestones
==========

Milestones are "targets" that you plan to get a bug fixed by. For
example, if 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:

1. Select "Edit milestones" from the "Edit product" page.

2. Select "Add" in the bottom right corner.

3. 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".

======================================================================

This documentation undoubtedly has bugs; if you find some, please file
them here.
