diff options
| author | barnboy%trilobyte.net <> | 2001-03-08 14:35:44 +0100 |
|---|---|---|
| committer | barnboy%trilobyte.net <> | 2001-03-08 14:35:44 +0100 |
| commit | 6b607da839992bead01d7cba308f216e17eed520 (patch) | |
| tree | dce2e5e7aac71ccb906eb18b292712e93cd1ed85 /docs/html/programadmin.html | |
| parent | 3208181dc05fa0633e6cde53fec641f1db4b35ef (diff) | |
| download | bugzilla-6b607da839992bead01d7cba308f216e17eed520.tar.gz bugzilla-6b607da839992bead01d7cba308f216e17eed520.tar.xz | |
Documentation update; added docs/sgml, docs/html, docs/txt.
No text version of The Bugzilla Guide availabe yet, however.
Diffstat (limited to 'docs/html/programadmin.html')
| -rw-r--r-- | docs/html/programadmin.html | 923 |
1 files changed, 923 insertions, 0 deletions
diff --git a/docs/html/programadmin.html b/docs/html/programadmin.html new file mode 100644 index 000000000..2251d0f29 --- /dev/null +++ b/docs/html/programadmin.html @@ -0,0 +1,923 @@ +<HTML +><HEAD +><TITLE +>Product, Component, Milestone, and Version Administration</TITLE +><META +NAME="GENERATOR" +CONTENT="Modular DocBook HTML Stylesheet Version 1.61 +"><LINK +REL="HOME" +TITLE="The Bugzilla Guide" +HREF="index.html"><LINK +REL="UP" +TITLE="Administering Bugzilla" +HREF="administration.html"><LINK +REL="PREVIOUS" +TITLE="User Administration" +HREF="useradmin.html"><LINK +REL="NEXT" +TITLE="Bugzilla Security" +HREF="security.html"></HEAD +><BODY +CLASS="SECTION" +BGCOLOR="#FFFFFF" +TEXT="#000000" +LINK="#0000FF" +VLINK="#840084" +ALINK="#0000FF" +><DIV +CLASS="NAVHEADER" +><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TH +COLSPAN="3" +ALIGN="center" +>The Bugzilla Guide</TH +></TR +><TR +><TD +WIDTH="10%" +ALIGN="left" +VALIGN="bottom" +><A +HREF="useradmin.html" +>Prev</A +></TD +><TD +WIDTH="80%" +ALIGN="center" +VALIGN="bottom" +>Chapter 3. Administering Bugzilla</TD +><TD +WIDTH="10%" +ALIGN="right" +VALIGN="bottom" +><A +HREF="security.html" +>Next</A +></TD +></TR +></TABLE +><HR +ALIGN="LEFT" +WIDTH="100%"></DIV +><DIV +CLASS="SECTION" +><H1 +CLASS="SECTION" +><A +NAME="PROGRAMADMIN" +>3.3. Product, Component, Milestone, and Version Administration</A +></H1 +><TABLE +BORDER="0" +WIDTH="100%" +CELLSPACING="0" +CELLPADDING="0" +CLASS="EPIGRAPH" +><TR +><TD +WIDTH="45%" +> </TD +><TD +WIDTH="45%" +ALIGN="LEFT" +VALIGN="TOP" +><I +><P +><I +>Dear Lord, we have to get our users to do WHAT?</I +></P +></I +></TD +></TR +></TABLE +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="PRODUCTS" +>3.3.1. Products</A +></H2 +><FONT +COLOR="RED" +>Formerly, and in some spots still, called "Programs"</FONT +><P +> <A +HREF="glossary.html#GLOSS_PRODUCT" +><I +CLASS="GLOSSTERM" +>Products</I +></A +> 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...) + </P +><P +> 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. + </P +><P +>To create a new product:</P +><P +></P +><OL +TYPE="1" +><LI +><P +> Select "components" from the yellow footer + </P +><DIV +CLASS="TIP" +><BLOCKQUOTE +CLASS="TIP" +><P +><B +>Tip: </B +> 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... + </P +></BLOCKQUOTE +></DIV +></LI +><LI +><P +> Select the "Add" link to the right of "Add a new product". + </P +></LI +><LI +><P +> Enter the name of the product and a description. + The Description field is free-form. + </P +></LI +></OL +><DIV +CLASS="TIP" +><BLOCKQUOTE +CLASS="TIP" +><P +><B +>Tip: </B +> 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. + </P +></BLOCKQUOTE +></DIV +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="COMPONENTS" +>3.3.2. Components</A +></H2 +><P +> Components are subsections of a Product. + + <DIV +CLASS="EXAMPLE" +><A +NAME="AEN491" +></A +><P +><B +>Example 3-1. Creating some Components</B +></P +><DIV +CLASS="INFORMALEXAMPLE" +><A +NAME="AEN493" +></A +><P +></P +><P +> The computer game you are designing may 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. + </P +><P +></P +></DIV +></DIV +> + + Each component has a owner and (if you turned it on in the parameters), a qa + contact. The owner should be the primary person who fixes bugs in that component. The QA + Contact should be the person who will ensure these bugs are completely fixed. The Owner, + QA Contact, and Reporter will get email when new bugs are created in this Component and + when these bugs change. Default Owner and Default QA Contact fields only dictate the + <EM +>default assignments</EM +>; the Owner and Q/A Contact fields in a bug + are otherwise unrelated to the Component. + </P +><P +> To create a new Component: + </P +><P +></P +><OL +TYPE="1" +><LI +><P +> Select the "Edit components" link from the "Edit Product" page + </P +></LI +><LI +><P +> Select the "Add" link to the right of the "Add a new component" text + on the "Select Component" page. + </P +></LI +><LI +><P +> Fill out the "Component" field, a short "Description", and the "Initial Owner". + The "Component" field should not contain a space. The "Description" field is + free-form. The "Initial Owner" field must be that of a valid user already + existing in the database. If the initial owner does not exist, Bugzilla + will refuse to create the component. + <DIV +CLASS="TIP" +><BLOCKQUOTE +CLASS="TIP" +><P +><B +>Tip: </B +> Is your "Default Owner" a user who is not yet in the database? + No problem. + <P +></P +><OL +TYPE="a" +><LI +><P +> Select the "Log out" link on the footer of the page. + </P +></LI +><LI +><P +> Select the "New Account" link on the footer of the "Relogin" page + </P +></LI +><LI +><P +> 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. + </P +></LI +><LI +><P +> Now select "Log in" again, type in your login information, and you + can modify the product to use the Default Owner information + you require. + </P +></LI +></OL +> + </P +></BLOCKQUOTE +></DIV +> + </P +></LI +><LI +><P +> Either "edit" more components or return to the "query" page on the ensuing + "Addming new component" page. To return to the Product you were editing, you + must select the "components" link as before. + </P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="VERSIONS" +>3.3.3. Versions</A +></H2 +><P +> 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. + + <DIV +CLASS="EXAMPLE" +><A +NAME="AEN520" +></A +><P +><B +>Example 3-2. Common Use of Versions</B +></P +><DIV +CLASS="INFORMALEXAMPLE" +><A +NAME="AEN522" +></A +><P +></P +><P +> 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 + </P +><P +></P +></DIV +></DIV +> + <DIV +CLASS="EXAMPLE" +><A +NAME="AEN524" +></A +><P +><B +>Example 3-3. A Different Use of Versions</B +></P +><DIV +CLASS="INFORMALEXAMPLE" +><A +NAME="AEN526" +></A +><P +></P +><P +> 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. + </P +><P +></P +></DIV +></DIV +> + </P +><P +> To create and edit Versions: + </P +><P +></P +><OL +TYPE="1" +><LI +><P +> From the "Edit Product" screen, select "Edit Versions" + </P +></LI +><LI +><P +> 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. + </P +><P +> Otherwise, click the "Add" button to the right of the "Add a new version" text. + </P +></LI +><LI +><P +> 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. + </P +></LI +><LI +><P +> 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. + </P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="MILESTONES" +>3.3.4. Milestones</A +></H2 +><P +> 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. + </P +><DIV +CLASS="NOTE" +><BLOCKQUOTE +CLASS="NOTE" +><P +><B +>Note: </B +> Milestone options will only appear for a Product if you turned the "usetargetmilestone" field + in the "Edit Parameters" screen "On". + </P +></BLOCKQUOTE +></DIV +><P +> To create new Milestones, set Default Milestones, and set Milestone URL: + </P +><P +></P +><OL +TYPE="1" +><LI +><P +> Select "edit milestones" + </P +></LI +><LI +><P +> Select "Add" to the right of the "Add a new milestone" text + </P +></LI +><LI +><P +> 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". + </P +><DIV +CLASS="EXAMPLE" +><A +NAME="AEN552" +></A +><P +><B +>Example 3-4. Using SortKey with Target Milestone</B +></P +><DIV +CLASS="INFORMALEXAMPLE" +><A +NAME="AEN554" +></A +><P +></P +><P +> 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" + </P +><P +></P +></DIV +></DIV +></LI +><LI +><P +> 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. + <DIV +CLASS="NOTE" +><BLOCKQUOTE +CLASS="NOTE" +><P +><B +>Note: </B +> 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. + </P +></BLOCKQUOTE +></DIV +> + </P +></LI +><LI +><P +> 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" + </P +><P +> Some common uses of this field include product descriptions, product roadmaps, + and of course a simple description of the meaning of each milestone. + </P +></LI +><LI +><P +> 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. + </P +><P +>Select the "Update" button when you are done.</P +></LI +><LI +><P +> + </P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="VOTING" +>3.3.5. Voting</A +></H2 +><P +> 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. + </P +><P +> 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. + </P +><P +>To modify Voting settings:</P +><P +></P +><OL +TYPE="1" +><LI +><P +> Navigate to the "Edit Product" screen for the Product you wish to modify + </P +></LI +><LI +><P +> Set "Maximum Votes per person" to your calculated value. Setting this field + to "0" disables voting. + </P +></LI +><LI +><P +> 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. + </P +></LI +><LI +><P +> 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? + <DIV +CLASS="TIP" +><BLOCKQUOTE +CLASS="TIP" +><P +><B +>Tip: </B +> 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 <EM +>really</EM +> bad bug! + </P +></BLOCKQUOTE +></DIV +> + </P +></LI +><LI +><P +> Once you have adjusted the values to your preference, select the "Update" button. + </P +></LI +></OL +></DIV +><DIV +CLASS="SECTION" +><H2 +CLASS="SECTION" +><A +NAME="GROUPS" +>3.3.6. Groups and Group Security</A +></H2 +><P +> 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. + + <DIV +CLASS="EXAMPLE" +><A +NAME="AEN590" +></A +><P +><B +>Example 3-5. When to Use Group Security</B +></P +><DIV +CLASS="INFORMALEXAMPLE" +><A +NAME="AEN592" +></A +><P +></P +><P +> 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. + </P +><P +></P +></DIV +></DIV +> + + Groups only work if you enable the "usebuggroups" paramater. + In addition, if the "usebuggroupsentry" parameter is "On", one can restrict access + to products by groups, so that only members of a product group are able to view + bugs within that product. + Group security in Bugzilla can be divided into two categories: + Generic and Product-Based. + </P +><DIV +CLASS="NOTE" +><BLOCKQUOTE +CLASS="NOTE" +><P +><B +>Note: </B +> 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. + </P +><P +> 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. + </P +></BLOCKQUOTE +></DIV +><P +> To enable Generic Group Security ("usebuggroups"): + </P +><P +></P +><OL +TYPE="1" +><LI +><P +> Turn "On" "usebuggroups" in the "Edit Parameters" screen. + </P +></LI +><LI +><P +> You will generally have no groups set up. Select the "groups" link + in the footer. + </P +></LI +><LI +><P +> 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. + </P +></LI +><LI +><P +> 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. + + <DIV +CLASS="EXAMPLE" +><A +NAME="AEN607" +></A +><P +><B +>Example 3-6. Creating a New Group</B +></P +><DIV +CLASS="INFORMALEXAMPLE" +><A +NAME="AEN609" +></A +><P +></P +><P +> I created a group called "DefaultGroup" with a description of "This is simply + a group to play with", and a "New User RegExp" of "*@velio.com". This + new group automatically includes all Bugzilla users with "@velio.com" at the + end of their user id. When I finished, my new group was assigned bit #128. + </P +><P +></P +></DIV +></DIV +> + + When you have finished, select the "Add" button. + </P +></LI +></OL +><P +> To enable Product-Based Group Security ("usebuggroupsentry"): + </P +><DIV +CLASS="WARNING" +><P +></P +><TABLE +CLASS="WARNING" +BORDER="1" +WIDTH="100%" +><TR +><TD +ALIGN="CENTER" +><B +>Warning</B +></TD +></TR +><TR +><TD +ALIGN="LEFT" +><P +> 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. + </P +></TD +></TR +></TABLE +></DIV +><P +></P +><OL +TYPE="1" +><LI +><P +> Turn "On" "usebuggroups" and "usebuggroupsentry" in the "Edit Parameters" screen. + </P +><DIV +CLASS="WARNING" +><P +></P +><TABLE +CLASS="WARNING" +BORDER="1" +WIDTH="90%" +><TR +><TD +ALIGN="CENTER" +><B +>Warning</B +></TD +></TR +><TR +><TD +ALIGN="LEFT" +><P +> "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. + </P +></TD +></TR +></TABLE +></DIV +></LI +><LI +><P +> 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. + </P +></LI +></OL +></DIV +></DIV +><DIV +CLASS="NAVFOOTER" +><HR +ALIGN="LEFT" +WIDTH="100%"><TABLE +WIDTH="100%" +BORDER="0" +CELLPADDING="0" +CELLSPACING="0" +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +><A +HREF="useradmin.html" +>Prev</A +></TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="index.html" +>Home</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +><A +HREF="security.html" +>Next</A +></TD +></TR +><TR +><TD +WIDTH="33%" +ALIGN="left" +VALIGN="top" +>User Administration</TD +><TD +WIDTH="34%" +ALIGN="center" +VALIGN="top" +><A +HREF="administration.html" +>Up</A +></TD +><TD +WIDTH="33%" +ALIGN="right" +VALIGN="top" +>Bugzilla Security</TD +></TR +></TABLE +></DIV +></BODY +></HTML +>
\ No newline at end of file |