Skip to content

bugzilla
bugzilla
Commit 05f7fa76 authored by jocuri%softhome.net's avatar jocuri%softhome.net
Browse files
Options

Documentation patch for bug 198020: provide admin docs for flags; patch by Shane…

Documentation patch for bug 198020: provide admin docs for flags; patch by Shane H. W. Travis <travis@sedsystems.ca>; r=myk.
parent 29ff5764
Show whitespace changes
Inline Side-by-side
Showing with 411 additions and 0 deletions
docs/xml/administration.xml
View file @ 05f7fa76
......@@ -581,6 +581,417 @@
</orderedlist>
</section>
<section id="flags">
<title>Flags</title>
<para>
Flags are a way to attach a specific status to a bug or attachment,
either <quote>+</quote> or <quote>-</quote>. 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 <quote>?</quote> as a
request to another user that they look at the bug/attachment, and set
the flag to its correct status.
</para>
<section id="flags-simpleexample">
<title>A Simple Example</title>
<para>
A developer might want to ask their manager,
<quote>Should we fix this bug before we release version 2.0?</quote>
They might want to do this for a <emphasis>lot</emphasis> of bugs,
so it would be nice to streamline the process...
</para>
<para>
In Bugzilla, it would work this way:
<orderedlist>
<listitem>
<para>
The Bugzilla administrator creates a flag type called
<quote>blocking2.0</quote> that shows up on all bugs in
your product.
</para>
<para>
It shows up on the <quote>Show Bug</quote> screen
as the text <quote>blocking2.0</quote> with a drop-down box next
to it. The drop-down box contains four values: an empty space,
<quote>?</quote>, <quote>-</quote>, and <quote>+</quote>.
</para>
</listitem>
<listitem>
<para>The developer sets the flag to <quote>?</quote>.</para>
</listitem>
<listitem>
<para>
The manager sees the <computeroutput>blocking2.0</computeroutput>
flag with a <quote>?</quote> value.
</para>
</listitem>
<listitem>
<para>
If the manager thinks the feature should go into the product
before version 2.0 can be released, he sets the flag to
<quote>+</quote>. Otherwise, he sets it to <quote>-</quote>.
</para>
</listitem>
<listitem>
<para>
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.
</para>
</listitem>
</orderedlist>
</para>
</section>
<section id="flags-about">
<title>About Flags</title>
<section id="flag-values">
<title>Values</title>
<para>
Flags can have three values:
<variablelist>
<varlistentry>
<term><computeroutput>?</computeroutput></term>
<listitem><simpara>
A user is requesting that a status be set. (Think of it as 'A question is being asked'.)
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>-</computeroutput></term>
<listitem><simpara>
The status has been set negatively. (The question has been answered <quote>no</quote>.)
</simpara></listitem>
</varlistentry>
<varlistentry>
<term><computeroutput>+</computeroutput></term>
<listitem><simpara>
The status has been set positively. (The question has been answered <quote>yes</quote>.)
</simpara></listitem>
</varlistentry>
</variablelist>
</para>
<para>
Actually, there's a fourth value a flag can have --
<quote>unset</quote> -- 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.
</para>
</section>
</section>
<section id="flag-askto">
<title>Using flag requests</title>
<para>
If a flag has been defined as 'requestable',
users are allowed to set the flag's status to <quote>?</quote>.
This status indicates that someone (aka <quote>the requester</quote> is asking
for someone else to set the flag to either <quote>+</quote> or <quote>-</quote>.
</para>
<para>
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 (aka <quote>the requestee</quote>)
will receive an email notifying them of the request, and pointing them
to the bug/attachment in question.
</para>
<para>
If a flag has <emphasis>not</emphasis> 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 <quote>to the wind</quote>.
A requester may <quote>ask the wind</quote> on any flag simply by leaving the text-box blank.
</para>
</section>
<section id="flag-types">
<title>Two Types of Flags</title>
<para>
Flags can go in two places: on an attachment, or on a bug.
</para>
<section id="flag-type-attachment">
<title>Attachment Flags</title>
<para>
Attachment flags are used to ask a question about a specific
attachment on a bug.
</para>
<para>
Many Bugzilla installations use this to
request that one developer <quote>review</quote> 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
<quote>review</quote> to
<computeroutput>review?boss@domain.com</computeroutput>.
boss@domain.com is then notified by email that
he has to check out that attachment and approve it or deny it.
</para>
<para>
For a Bugzilla user, attachment flags show up in two
places:
<orderedlist>
<listitem>
<para>
On the list of attachments in the <quote>Show Bug</quote>
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).
</para>
</listitem>
<listitem>
<para>
When you <quote>Edit</quote> an attachment, you can
see any settable flag, along with any flags that have
already been set. This <quote>Edit Attachment</quote>
screen is where you set flags to ?, -, +, or unset them.
</para>
</listitem>
</orderedlist>
</para>
</section>
<section id="flag-type-bug">
<title>Bug Flags</title>
<para>
Bug flags are used to set a status on the bug itself. You can
see Bug Flags in the <quote>Show Bug</quote> screen
(<filename>editbug.cgi</filename>).
</para>
<para>
Only users with the ability to edit the bug may
set flags on bugs. This includes the owner, reporter, and
any user with the <computeroutput>editbugs</computeroutput>
permission.
</para>
</section>
</section>
<section id="flags-admin">
<title>Administering Flags</title>
<para>
If you have the <quote>editcomponents</quote> permission, you will
have <quote>Edit: ... | Flags | ...</quote> in your page footer.
Clicking on that link will bring you to the <quote>Administer
Flag Types</quote> page. Here, you can select whether you want
to create (or edit) a Bug flag, or an Attachment flag.
</para>
<para>
No matter which you choose, the interface is the same, so we'll
just go over it once.
</para>
<section id="flags-create">
<title>Creating a Flag</title>
<para>
When you click on the <quote>Create a Flag Type for...</quote>
link, you will be presented with a form. Here is what the felds in
the form mean:
</para>
<section id="flags-create-field-name">
<title>Name</title>
<para>
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 consist of any valid Unicode character.
</para>
</section>
<section id="flags-create-field-description">
<title>Description</title>
<para>
This describes the flag in more detail. At present, this doesn't
whos up anywhere helpful; ideally, it would be nice to have
it show up as a tooltip. This field
can be as long as you like, and can contain any character you want.
</para>
</section>
<section id="flags-create-field-category">
<title>Category</title>
<para>
Default behaviour for a newly-created flag is to appear on
products and all components, which is why <quote>__Any__:__Any__</quote>
is already entered in the <quote>Inclusions</quote> 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 <quote>__Any__:__Any__</quote> from the Inclusions box
and define products/components specifically for this flag.
</para>
<para>
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 <quote>__Any__</quote> for Product translates to,
<quote>all the products in this Bugzilla</quote>.
Selecting <quote>__Any__</quote> in the Component field means
<quote>all components in the selected product.</quote>)
Selections made, press <quote>Include</quote>, and your
Product/Component pairing will show up in the <quote>Inclusions</quote> box on the right.
</para>
<para>
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
<quote>Exclude</quote>. The Product/Component pairing will show up in the
<quote>Exclusions</quote> box on the right.
</para>
<para>
This flag <emphasis>will</emphasis> and <emphasis>can</emphasis> be set for any
products/components that appearing in the <quote>Inclusions</quote> box
(or which fall under the appropriate <quote>__Any__</quote>).
This flag <emphasis>will not</emphasis> appear (and therefore cannot be set) on
any products appearing in the <quote>Exclusions</quote> box.
<emphasis> IMPORTANT: Exclusions override inclusions.</emphasis>
</para>
<para>
You may select a Product without selecting a specific Component,
but it is illegal to select a Component without a Product, or to select a
Component that does not belong to the named Product. Doing so as of
this writing (2.18rc3) will raise an error... even if all your products
have a component by that name.
</para>
<para><emphasis>Example:</emphasis> Let's say you have a product called
<quote>Jet Plane</quote> 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 <quote>fixInNext</quote>.
But, there's one component in <quote>Jet Plane,</quote>
called <quote>Pilot.</quote> 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 <quote>Jet Plane:__Any__</quote> and you exclude
<quote>Jet Plane:Pilot</quote>.
</para>
</section>
<section id="flags-create-field-sortkey">
<title>Sort Key</title>
<para>
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.
</para>
<para>
<emphasis>Example:</emphasis> 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.
</para>
</section>
<section id="flags-create-field-active">
<title>Active</title>
<para>
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 <quote>active</quote>. 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.
</para>
</section>
<section id="flags-create-field-requestable">
<title>Requestable</title>
<para>
New flags are, by default, <quote>requestable</quote>, meaning that they
offer users the <quote>?</quote> option, as well as <quote>+</quote> and <quote>-</quote>.
To remove the ? option, uncheck <quote>requestable</quote>.
</para>
</section>
<section id="flags-create-field-cclist">
<title>CC List</title>
<para>
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..
</para>
</section>
<section id="flags-create-field-specific">
<title>Specifically Requestable</title>
<para>
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 <quote>to the wind.</quote> 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).
</para>
</section>
<section id="flags-create-field-multiplicable">
<title>Multiplicable</title>
<para>
Any flag with <quote>Multiplicable</quote> 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 <quote>addl.</quote> (short for
<quote>additional</quote>) before the name. There is no limit to the number of
times a Multiplicable flags may be set on the same bug/attachment.
</para>
</section>
</section> <!-- flags-create -->
<section id="flags-delete">
<title>Deleting a Flag</title>
<para>
When you are at the <quote>Administer Flag Types</quote> screen,
you will be presented with a list of Bug flags and a list of Attachment
Flags.
</para>
<para>
To delete a flag, click on the <quote>Delete</quote> link next to
the flag description.
</para>
<warning>
<para>
Once you delete a flag, it is <emphasis>gone</emphasis> 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 <quote>active</quote> in the flag Edit form.
</para>
</warning>
</section>
<section id="flags-edit">
<title>Editing a Flag</title>
<para>
To edit a flag's properties, just click on the <quote>Edit</quote>
link next to the flag's description. That will take you to the same
form described in the <quote>Creating a Flag</quote> section.
</para>
</section>
</section> <!-- flags-admin -->
<!-- XXX We should add a "Uses of Flags" section, here, with examples. -->
</section> <!-- flags -->
<section id="voting">
<title>Voting</title>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment