3.7. 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.
3.7.1. 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.
3.7.2. About Flags
3.7.2.1. 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.
3.7.3. Using flag requests
If a flag has been defined as 'requestable', users are allowed to set the flag's status to "?". This status indicates that someone (aka "the requester" is asking for 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 (aka "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.
3.7.4. Two Types of Flags
Flags can go in two places: on an attachment, or on a bug.
3.7.4.1. 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 [email protected]. [email protected] 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 two 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.
3.7.4.2. Bug Flags
Bug flags are used to set a status on the bug itself. You can see Bug Flags in the "Show Bug" screen (editbug.cgi).
Only users with the ability to edit the bug may set flags on bugs. This includes the owner, reporter, and any user with the editbugs permission.
3.7.5. Administering Flags
If you have the "editcomponents" permission, you will have "Edit: ... | Flags | ..." in your page footer. Clicking on that 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.
3.7.5.1. 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:
3.7.5.1.1. 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 consist of any valid Unicode character.
3.7.5.1.2. Description
This describes the flag in more detail. At present, this doesn't show 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.
3.7.5.1.3. 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 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.
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".
3.7.5.1.4. 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.
3.7.5.1.5. 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.
3.7.5.1.6. Requestable
New flags are, by default, "requestable", meaning that they offer users the "?" option, as well as "+" and "-". To remove the ? option, uncheck "requestable".
3.7.5.1.7. 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..
3.7.5.1.8. 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).
3.7.5.1.9. 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.
3.7.5.2. 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.
 | 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. |
3.7.5.3. Editing a Flag
To edit a flag's properties, just click on the "Edit" link next to the flag's description. That will take you to the same form described in the "Creating a Flag" section.