diff options
| -rw-r--r-- | docs/xml/administration.xml | 411 |
1 files changed, 411 insertions, 0 deletions
diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml index f247108ae..e23a27a67 100644 --- a/docs/xml/administration.xml +++ b/docs/xml/administration.xml @@ -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> |