4.3. Product, Component, Milestone, and Version + Administration
Dear Lord, we have to get our users to do WHAT? |
4.3.1. Products
Formerly, and in some spots still, called + "Programs"Products are + the broadest category in Bugzilla, and you should have the + least of these. If your company makes computer games, you + should have one product per game, and possibly a few special + products (website, meetings...) +
A Product (formerly called "Program", and still referred to + that way in some portions of the source code) controls some + very important functions. The number of "votes" available for + users to vote for the most important bugs is set per-product, + as is the number of votes required to move a bug automatically + from the UNCONFIRMED status to the NEW status. One can close + a Product for further bug entry and define various Versions + available from the Edit product screen. +
To create a new product:
Select "components" from the yellow footer +
It may seem counterintuitive to click "components" when + you want to edit the properties associated with + Products. This is one of a long list of things we want + in Bugzilla 3.0... +
Select the "Add" link to the right of "Add a new product". +
Enter the name of the product and a description. The + Description field is free-form. +
Don't worry about the "Closed for bug entry", "Maximum Votes + per person", "Maximum votes a person can put on a single + bug", "Number of votes a bug in this Product needs to + automatically get out of the UNCOMFIRMED state", and + "Version" options yet. We'll cover those in a few moments. + |
4.3.2. Components
Components are subsections of a Product. + +
Example 4-1. Creating some Components
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. +
To create a new Component: +
Select the "Edit components" link from the "Edit product" + page +
Select the "Add" link to the right of the "Add a new + component" text on the "Select Component" page. +
Fill out the "Component" field, a short "Description", and + the "Initial Owner". The Component and Description fields + are free-form; the "Initial Owner" field must be that of a + user ID already existing in the database. If the initial + owner does not exist, Bugzilla will refuse to create the + component. +
+Is your "Default Owner" a user who is not yet in the + database? No problem. +
Select the "Log out" link on the footer of the + page. +
Select the "New Account" link on the footer of + the "Relogin" page +
Type in the email address of the default owner + you want to create in the "E-mail address" + field, and her full name in the "Real name" + field, then select the "Submit Query" button. +
Now select "Log in" again, type in your login + information, and you can modify the product to + use the Default Owner information you require. +
Either Edit more components or return to the Bugzilla + Query Page. To return to the Product you were editing, you + must select the Components link as before. +
4.3.3. Versions
Versions are the revisions of the product, such as "Flinders + 3.1", "Flinders 95", and "Flinders 2000". Using Versions + helps you isolate code changes and are an aid in reporting. + +
Example 4-2. Common Use of Versions
A user reports a bug against Version "Beta 2.0" of your + product. The current Version of your software is + "Release Candidate 1", and no longer has the bug. This + will help you triage and classify bugs according to + their relevance. It is also possible people may report + bugs against bleeding-edge beta versions that are not + evident in older versions of the software. This can + help isolate code changes that caused the bug +
Example 4-3. A Different Use of Versions
This field has been used to good effect by an online + service provider in a slightly different way. They had + three versions of the product: "Production", "QA", and + "Dev". Although it may be the same product, a bug in + the development environment is not normally as critical + as a Production bug, nor does it need to be reported + publicly. When used in conjunction with Target + Milestones, one can easily specify the environment where + a bug can be reproduced, and the Milestone by which it + will be fixed. +
To create and edit Versions: +
From the "Edit product" screen, select "Edit Versions" +
You will notice that the product already has the default + version "undefined". If your product doesn't use version + numbers, you may want to leave this as it is or edit it so + that it is "---". You can then go back to the edit + versions page and add new versions to your product. +
Otherwise, click the "Add" button to the right of the "Add + a new version" text. +
Enter the name of the Version. This can be free-form + characters up to the limit of the text box. Then select + the "Add" button. +
At this point you can select "Edit" to edit more Versions, + or return to the "Query" page, from which you can navigate + back to the product through the "components" link at the + foot of the Query page. +
4.3.4. Milestones
Milestones are "targets" that you plan to get a bug fixed by. + For example, you have a bug that you plan to fix for your 3.0 + release, it would be assigned the milestone of 3.0. Or, you + have a bug that you plan to fix for 2.8, this would have a + milestone of 2.8. +
Milestone options will only appear for a Product if you + turned the "usetargetmilestone" field in the "Edit + Parameters" screen "On". + |
To create new Milestones, set Default Milestones, and set + Milestone URL: +
Select "edit milestones" +
Select "Add" to the right of the "Add a new milestone" + text +
Enter the name of the Milestone in the "Milestone" field. + You can optionally set the "Sortkey", which is a positive + or negative number (-255 to 255) that defines where in the + list this particular milestone appears. Select "Add". +
Example 4-4. Using SortKey with Target Milestone
Let's say you create a target milestone called + "Release 1.0", with Sortkey set to "0". Later, you + realize that you will have a public beta, called + "Beta1". You can create a Milestone called "Beta1", + with a Sortkey of "-1" in order to ensure people will + see the Target Milestone of "Beta1" earlier on the + list than "Release 1.0" +
If you want to add more milestones, select the "Edit" + link. If you don't, well shoot, you have to go back to the + "query" page and select "components" again, and make your + way back to the Product you were editing. +
+This is another in the list of unusual user interface + decisions that we'd like to get cleaned up. Shouldn't + there be a link to the effect of "edit the Product I + was editing when I ended up here"? In any case, + clicking "components" in the footer takes you back to + the "Select product" screen, from which you can begin + editing your product again. +
From the Edit product screen again (once you've made your + way back), enter the URL for a description of what your + milestones are for this product in the "Milestone URL" + field. It should be of the format + "http://www.foo.com/bugzilla/product_milestones.html" +
Some common uses of this field include product + descriptions, product roadmaps, and of course a simple + description of the meaning of each milestone. +
If you're using Target Milestones, the "Default Milestone" + field must have some kind of entry. If you really don't + care if people set coherent Target Milestones, simply + leave this at the default, "---". However, controlling + and regularly updating the Default Milestone field is a + powerful tool when reporting the status of projects. +
Select the "Update" button when you are done.
4.3.5. Voting
The concept of "voting" is a poorly understood, yet powerful + feature for the management of open-source projects. Each user + is assigned so many Votes per product, which they can freely + reassign (or assign multiple votes to a single bug). This + allows developers to gauge user need for a particular + enhancement or bugfix. By allowing bugs with a certain number + of votes to automatically move from "UNCONFIRMED" to "NEW", + users of the bug system can help high-priority bugs garner + attention so they don't sit for a long time awaiting triage. +
The daunting challenge of Votes is deciding where you draw the + line for a "vocal majority". If you only have a user base of + 100 users, setting a low threshold for bugs to move from + UNCONFIRMED to NEW makes sense. As the Bugzilla user base + expands, however, these thresholds must be re-evaluated. You + should gauge whether this feature is worth the time and close + monitoring involved, and perhaps forego implementation until + you have a critical mass of users who demand it. +
To modify Voting settings:
Navigate to the "Edit product" screen for the Product you + wish to modify +
Set "Maximum Votes per person" to your calculated value. + Setting this field to "0" disables voting. +
Set "Maximum Votes a person can put on a single bug" to + your calculated value. It should probably be some number + lower than the "Maximum votes per person". Setting this + field to "0" disables voting, but leaves the voting + options open to the user. This is confusing. +
Set "Number of votes a bug in this product needs to + automatically get out of the UNCONFIRMED state" to your + calculated number. Setting this field to "0" disables + the automatic move of bugs from UNCONFIRMED to NEW. Some + people advocate leaving this at "0", but of what use are + Votes if your Bugzilla user base is unable to affect which + bugs appear on Development radar? +
+You should probably set this number to higher than a + small coalition of Bugzilla users can influence it. + Most sites use this as a "referendum" mechanism -- if + users are able to vote a bug out of UNCONFIRMED, it is + a really bad bug! +
Once you have adjusted the values to your preference, + select the "Update" button. +
4.3.6. Groups and Group Security
Groups can be very useful in bugzilla, because they allow + users to isolate bugs or products that should only be seen by + certain people. Groups can also be a complicated minefield of + interdependencies and weirdness if mismanaged. + +
Example 4-5. When to Use Group Security
Many Bugzilla sites isolate "Security-related" bugs from + all other bugs. This way, they can have a fix ready + before the security vulnerability is announced to the + world. You can create a "Security" product which, by + default, has no members, and only add members to the + group (in their individual User page, as described under + User Administration) who should have priveleged access + to "Security" bugs. Alternately, you may create a Group + independently of any Product, and change the Group mask + on individual bugs to restrict access to members only of + certain Groups. +
Groups in Bugzilla are a complicated beast that evolved out + of very simple user permission bitmasks, apparently itself + derived from common concepts in UNIX access controls. A + "bitmask" is a fixed-length number whose value can describe + one, and only one, set of states. For instance, UNIX file + permissions are assigned bitmask values: "execute" has a + value of 1, "write" has a value of 2, and "read" has a + value of 4. Add them together, and a file can be read, + written to, and executed if it has a bitmask of "7". (This + is a simplified example -- anybody who knows UNIX security + knows there is much more to it than this. Please bear with + me for the purpose of this note.) The only way a bitmask + scheme can work is by doubling the bit count for each value. + Thus if UNIX wanted to offer another file permission, the + next would have to be a value of 8, then the next 16, the + next 32, etc. + Similarly, Bugzilla offers a bitmask to define group + permissions, with an internal limit of 64. Several are + already occupied by built-in permissions. The way around + this limitation is to avoid assigning groups to products if + you have many products, avoid bloating of group lists, and + religiously prune irrelevant groups. In reality, most + installations of Bugzilla support far fewer than 64 groups, + so this limitation has not hit for most sites, but it is on + the table to be revised for Bugzilla 3.0 because it + interferes with the security schemes of some administrators. + |
To enable Generic Group Security ("usebuggroups"): +
Turn "On" "usebuggroups" in the "Edit Parameters" screen. +
You will generally have no groups set up. Select the + "groups" link in the footer. +
Take a moment to understand the instructions on the "Edit + Groups" screen. Once you feel confident you understand + what is expected of you, select the "Add Group" link. +
Fill out the "New Name" (remember, no spaces!), "New + Description", and "New User RegExp" fields. "New User + RegExp" allows you to automatically place all users who + fulfill the Regular Expression into the new group. + +
When you have finished, select the Add + button. +Example 4-6. Creating a New Group
I created a group called DefaultGroup with a + description of "This is simply a group to play + with", and a New User RegExp of ".*@mydomain.tld". + This new group automatically includes all Bugzilla + users with "@mydomain.tld" at the end of their user id. + When I finished, my new group was assigned bit #128. +
To enable Product-Based Group Security (usebuggroupsentry): +
Don't forget that you only have 64 groups masks available, + total, for your installation of Bugzilla! If you plan on + having more than 50 products in your individual Bugzilla + installation, and require group security for your products, + you should consider either running multiple Bugzillas or + using Generic Group Security instead of Product-Based + ("usebuggroupsentry") Group Security. + |
Turn "On" "usebuggroups" and "usebuggroupsentry" in the + "Edit Parameters" screen. +
"usebuggroupsentry" has the capacity to prevent the + administrative user from directly altering bugs because + of conflicting group permissions. If you plan on using + "usebuggroupsentry", you should plan on restricting + administrative account usage to administrative duties + only. In other words, manage bugs with an unpriveleged + user account, and manage users, groups, Products, etc. + with the administrative account. +
You will generally have no Groups set up, unless you + enabled "usebuggroupsentry" prior to creating any + Products. To create "Generic Group Security" groups, + follow the instructions given above. To create + Product-Based Group security, simply follow the + instructions for creating a new Product. If you need to + add users to these new groups as you create them, you will + find the option to add them to the group available under + the "Edit User" screens. +