<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html><head><meta http-equiv="Content-Type" content="text/html; charset=ANSI_X3.4-1968"><title>3.8. Flags</title><link rel="stylesheet" type="text/css" href="../../style.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"><meta name="keywords" content="Bugzilla, Guide, installation, FAQ, administration, integration, MySQL, Mozilla, webtools"><link rel="home" href="index.html" title="The Bugzilla Guide - 4.4.11 Release"><link rel="up" href="administration.html" title="Chapter 3. Administering Bugzilla"><link rel="prev" href="milestones.html" title="3.7. Milestones"><link rel="next" href="keywords.html" title="3.9. Keywords"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">3.8. Flags</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="milestones.html">Prev</a> </td><th width="60%" align="center">Chapter 3. Administering Bugzilla</th><td width="20%" align="right"> <a accesskey="n" href="keywords.html">Next</a></td></tr></table><hr></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="flags-overview"></a>3.8. Flags</h2></div></div></div><p>
Flags are a way to attach a specific status to a bug or attachment,
either <span class="quote">“<span class="quote">+</span>”</span> or <span class="quote">“<span class="quote">-</span>”</span>. 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 <span class="quote">“<span class="quote">?</span>”</span> as a
request to another user that they look at the bug/attachment, and set
the flag to its correct status.
</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="flags-simpleexample"></a>3.8.1. A Simple Example</h3></div></div></div><p>
A developer might want to ask their manager,
<span class="quote">“<span class="quote">Should we fix this bug before we release version 2.0?</span>”</span>
They might want to do this for a <span class="emphasis"><em>lot</em></span> of bugs,
so it would be nice to streamline the process...
</p><p>
In Bugzilla, it would work this way:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
The Bugzilla administrator creates a flag type called
<span class="quote">“<span class="quote">blocking2.0</span>”</span> that shows up on all bugs in
your product.
</p><p>
It shows up on the <span class="quote">“<span class="quote">Show Bug</span>”</span> screen
as the text <span class="quote">“<span class="quote">blocking2.0</span>”</span> with a drop-down box next
to it. The drop-down box contains four values: an empty space,
<span class="quote">“<span class="quote">?</span>”</span>, <span class="quote">“<span class="quote">-</span>”</span>, and <span class="quote">“<span class="quote">+</span>”</span>.
</p></li><li class="listitem"><p>The developer sets the flag to <span class="quote">“<span class="quote">?</span>”</span>.</p></li><li class="listitem"><p>
The manager sees the <code class="computeroutput">blocking2.0</code>
flag with a <span class="quote">“<span class="quote">?</span>”</span> value.
</p></li><li class="listitem"><p>
If the manager thinks the feature should go into the product
before version 2.0 can be released, he sets the flag to
<span class="quote">“<span class="quote">+</span>”</span>. Otherwise, he sets it to <span class="quote">“<span class="quote">-</span>”</span>.
</p></li><li class="listitem"><p>
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.
</p></li></ol></div><p>
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="flags-about"></a>3.8.2. About Flags</h3></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="flag-values"></a>3.8.2.1. Values</h4></div></div></div><p>
Flags can have three values:
</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="computeroutput">?</code></span></dt><dd>
A user is requesting that a status be set. (Think of it as 'A question is being asked'.)
</dd><dt><span class="term"><code class="computeroutput">-</code></span></dt><dd>
The status has been set negatively. (The question has been answered <span class="quote">“<span class="quote">no</span>”</span>.)
</dd><dt><span class="term"><code class="computeroutput">+</code></span></dt><dd>
The status has been set positively.
(The question has been answered <span class="quote">“<span class="quote">yes</span>”</span>.)
</dd></dl></div><p>
</p><p>
Actually, there's a fourth value a flag can have --
<span class="quote">“<span class="quote">unset</span>”</span> -- 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.
</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="flag-askto"></a>3.8.3. Using flag requests</h3></div></div></div><p>
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 <span class="quote">“<span class="quote">?</span>”</span>.
This status indicates that someone (a.k.a. <span class="quote">“<span class="quote">the requester</span>”</span>) is asking
someone else to set the flag to either <span class="quote">“<span class="quote">+</span>”</span> or <span class="quote">“<span class="quote">-</span>”</span>.
</p><p>
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. <span class="quote">“<span class="quote">the requestee</span>”</span>)
will receive an email notifying them of the request, and pointing them
to the bug/attachment in question.
</p><p>
If a flag has <span class="emphasis"><em>not</em></span> 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 <span class="quote">“<span class="quote">to the wind</span>”</span>.
A requester may <span class="quote">“<span class="quote">ask the wind</span>”</span> on any flag simply by leaving the text-box blank.
</p></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="flag-types"></a>3.8.4. Two Types of Flags</h3></div></div></div><p>
Flags can go in two places: on an attachment, or on a bug.
</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="flag-type-attachment"></a>3.8.4.1. Attachment Flags</h4></div></div></div><p>
Attachment flags are used to ask a question about a specific
attachment on a bug.
</p><p>
Many Bugzilla installations use this to
request that one developer <span class="quote">“<span class="quote">review</span>”</span> 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
<span class="quote">“<span class="quote">review</span>”</span> to
<code class="computeroutput">review?boss@domain.com</code>.
boss@domain.com is then notified by email that
he has to check out that attachment and approve it or deny it.
</p><p>
For a Bugzilla user, attachment flags show up in three places:
</p><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
On the list of attachments in the <span class="quote">“<span class="quote">Show Bug</span>”</span>
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).
</p></li><li class="listitem"><p>
When you <span class="quote">“<span class="quote">Edit</span>”</span> an attachment, you can
see any settable flag, along with any flags that have
already been set. This <span class="quote">“<span class="quote">Edit Attachment</span>”</span>
screen is where you set flags to ?, -, +, or unset them.
</p></li><li class="listitem"><p>
Requests are listed in the <span class="quote">“<span class="quote">Request Queue</span>”</span>, which
is accessible from the <span class="quote">“<span class="quote">My Requests</span>”</span> link (if you are
logged in) or <span class="quote">“<span class="quote">Requests</span>”</span> link (if you are logged out)
visible in the footer of all pages.
</p></li></ol></div><p>
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="flag-type-bug"></a>3.8.4.2. Bug Flags</h4></div></div></div><p>
Bug flags are used to set a status on the bug itself. You can
see Bug Flags in the <span class="quote">“<span class="quote">Show Bug</span>”</span> and <span class="quote">“<span class="quote">Requests</span>”</span>
screens, as described above.
</p><p>
Only users with enough privileges (see below) may set flags on bugs.
This doesn't necessarily include the assignee, reporter, or users with the
<code class="computeroutput">editbugs</code> permission.
</p></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="flags-admin"></a>3.8.5. Administering Flags</h3></div></div></div><p>
If you have the <span class="quote">“<span class="quote">editcomponents</span>”</span> permission, you can
edit Flag Types from the main administration page. Clicking the
<span class="quote">“<span class="quote">Flags</span>”</span> link will bring you to the <span class="quote">“<span class="quote">Administer
Flag Types</span>”</span> page. Here, you can select whether you want
to create (or edit) a Bug flag, or an Attachment flag.
</p><p>
No matter which you choose, the interface is the same, so we'll
just go over it once.
</p><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="flags-edit"></a>3.8.5.1. Editing a Flag</h4></div></div></div><p>
To edit a flag's properties, just click the flag's name.
That will take you to the same
form as described below (<a class="xref" href="flags-overview.html#flags-create" title="3.8.5.2. Creating a Flag">Section 3.8.5.2, “Creating a Flag”</a>).
</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="flags-create"></a>3.8.5.2. Creating a Flag</h4></div></div></div><p>
When you click on the <span class="quote">“<span class="quote">Create a Flag Type for...</span>”</span>
link, you will be presented with a form. Here is what the fields in
the form mean:
</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-name"></a>3.8.5.2.1. Name</h5></div></div></div><p>
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.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-description"></a>3.8.5.2.2. Description</h5></div></div></div><p>
The description describes the flag in more detail. It is visible
in a tooltip when hovering over a flag either in the <span class="quote">“<span class="quote">Show Bug</span>”</span>
or <span class="quote">“<span class="quote">Edit Attachment</span>”</span> pages. This field can be as
long as you like, and can contain any character you want.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-category"></a>3.8.5.2.3. Category</h5></div></div></div><p>
Default behaviour for a newly-created flag is to appear on
products and all components, which is why <span class="quote">“<span class="quote">__Any__:__Any__</span>”</span>
is already entered in the <span class="quote">“<span class="quote">Inclusions</span>”</span> 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 <span class="quote">“<span class="quote">__Any__:__Any__</span>”</span> from the Inclusions box
and define products/components specifically for this flag.
</p><p>
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 <span class="quote">“<span class="quote">__Any__</span>”</span> for Product translates to,
<span class="quote">“<span class="quote">all the products in this Bugzilla</span>”</span>.
Selecting <span class="quote">“<span class="quote">__Any__</span>”</span> in the Component field means
<span class="quote">“<span class="quote">all components in the selected product.</span>”</span>)
Selections made, press <span class="quote">“<span class="quote">Include</span>”</span>, and your
Product/Component pairing will show up in the <span class="quote">“<span class="quote">Inclusions</span>”</span> box on the right.
</p><p>
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
<span class="quote">“<span class="quote">Exclude</span>”</span>. The Product/Component pairing will show up in the
<span class="quote">“<span class="quote">Exclusions</span>”</span> box on the right.
</p><p>
This flag <span class="emphasis"><em>will</em></span> and <span class="emphasis"><em>can</em></span> be set for any
products/components that appearing in the <span class="quote">“<span class="quote">Inclusions</span>”</span> box
(or which fall under the appropriate <span class="quote">“<span class="quote">__Any__</span>”</span>).
This flag <span class="emphasis"><em>will not</em></span> appear (and therefore cannot be set) on
any products appearing in the <span class="quote">“<span class="quote">Exclusions</span>”</span> box.
<span class="emphasis"><em> IMPORTANT: Exclusions override inclusions.</em></span>
</p><p>
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.
</p><p><span class="emphasis"><em>Example:</em></span> Let's say you have a product called
<span class="quote">“<span class="quote">Jet Plane</span>”</span> 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 <span class="quote">“<span class="quote">fixInNext</span>”</span>.
But, there's one component in <span class="quote">“<span class="quote">Jet Plane,</span>”</span>
called <span class="quote">“<span class="quote">Pilot.</span>”</span> 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 <span class="quote">“<span class="quote">Jet Plane:__Any__</span>”</span> and you exclude
<span class="quote">“<span class="quote">Jet Plane:Pilot</span>”</span>.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-sortkey"></a>3.8.5.2.4. Sort Key</h5></div></div></div><p>
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.
</p><p>
<span class="emphasis"><em>Example:</em></span> 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.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-active"></a>3.8.5.2.5. Active</h5></div></div></div><p>
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 <span class="quote">“<span class="quote">active</span>”</span>. 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.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-requestable"></a>3.8.5.2.6. Requestable</h5></div></div></div><p>
New flags are, by default, <span class="quote">“<span class="quote">requestable</span>”</span>, meaning that they
offer users the <span class="quote">“<span class="quote">?</span>”</span> option, as well as <span class="quote">“<span class="quote">+</span>”</span>
and <span class="quote">“<span class="quote">-</span>”</span>.
To remove the ? option, uncheck <span class="quote">“<span class="quote">requestable</span>”</span>.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-specific"></a>3.8.5.2.7. Specifically Requestable</h5></div></div></div><p>
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 <span class="quote">“<span class="quote">to the wind.</span>”</span> 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).
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-multiplicable"></a>3.8.5.2.8. Multiplicable</h5></div></div></div><p>
Any flag with <span class="quote">“<span class="quote">Multiplicable</span>”</span> 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 <span class="quote">“<span class="quote">addl.</span>”</span> (short for
<span class="quote">“<span class="quote">additional</span>”</span>) before the name. There is no limit to the number of
times a Multiplicable flags may be set on the same bug/attachment.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-field-cclist"></a>3.8.5.2.9. CC List</h5></div></div></div><p>
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.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-grant-group"></a>3.8.5.2.10. Grant Group</h5></div></div></div><p>
When this field is set to some given group, only users in the group
can set the flag to <span class="quote">“<span class="quote">+</span>”</span> and <span class="quote">“<span class="quote">-</span>”</span>. This
field does not affect who can request or cancel the flag. For that,
see the <span class="quote">“<span class="quote">Request Group</span>”</span> 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.
</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="flags-create-request-group"></a>3.8.5.2.11. Request Group</h5></div></div></div><p>
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 <span class="quote">“<span class="quote">grant group</span>”</span> 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.
</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="flags-delete"></a>3.8.5.3. Deleting a Flag</h4></div></div></div><p>
When you are at the <span class="quote">“<span class="quote">Administer Flag Types</span>”</span> screen,
you will be presented with a list of Bug flags and a list of Attachment
Flags.
</p><p>
To delete a flag, click on the <span class="quote">“<span class="quote">Delete</span>”</span> link next to
the flag description.
</p><div class="warning" style="margin-left: 1em; margin-right: 1em"><table border="0" summary="Warning"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Warning]" src="../images/warning.gif"></td><th align="left"></th></tr><tr><td align="left" valign="top"><p>
Once you delete a flag, it is <span class="emphasis"><em>gone</em></span> 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 <span class="quote">“<span class="quote">active</span>”</span> in the flag Edit form.
</p></td></tr></table></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="milestones.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="administration.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="keywords.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">3.7. Milestones </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> 3.9. Keywords</td></tr></table></div></body></html>
