diff options
| -rw-r--r-- | docs/en/xml/administration.xml | 2057 |
1 files changed, 1106 insertions, 951 deletions
diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml index b261f4ee2..a35ba047d 100644 --- a/docs/en/xml/administration.xml +++ b/docs/en/xml/administration.xml @@ -1,966 +1,1121 @@ -<!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> -<chapter id="administration"> - <title>Administering Bugzilla</title> - - <section id="parameters"> - <title>Bugzilla Configuration</title> - - <para>Bugzilla is configured by changing various parameters, accessed - from the "Edit parameters" link in the page footer. Here are - some of the key parameters on that page. You should run down this - list and set them appropriately after installing Bugzilla.</para> - - <indexterm> - <primary>checklist</primary> - </indexterm> - - <procedure> - <step> - <para> - <command>maintainer</command>: - The maintainer parameter is the email address of the person - responsible for maintaining this - Bugzilla installation. The address need not be that of a valid Bugzilla - account.</para> - </step> - - <step> - <para> - <command>urlbase</command>: - This parameter defines the fully qualified domain name and web - server path to your Bugzilla installation.</para> - - <para>For example, if your Bugzilla query page is - <filename>http://www.foo.com/bugzilla/query.cgi</filename>, - set your <quote>urlbase</quote> - to <filename>http://www.foo.com/bugzilla/</filename>.</para> - </step> - - <step> - <para> - <command>makeproductgroups</command>: - This dictates whether or not to automatically create groups - when new products are created. - </para> - </step> - - <step> - <para> - <command>useentrygroupdefault</command>: - Bugzilla products can have a group associated with them, so that - certain users can only see bugs in certain products. When this - parameter is set to <quote>on</quote>, this - causes the initial group controls on newly created products - to place all newly-created bugs in the group - having the same name as the product immediately. - After a product is initially created, the group controls - can be further adjusted without interference by - this mechanism.</para> - </step> - - <step> - <para> - <command>shadowdb</command>: - You run into an interesting problem when Bugzilla reaches a - high level of continuous activity. MySQL supports only table-level - write locking. What this means is that if someone needs to make a - change to a bug, they will lock the entire table until the operation - is complete. Locking for write also blocks reads until the write is - complete. Note that more recent versions of mysql support row level - locking using different table types. These types are slower than the - standard type, and Bugzilla does not yet take advantage of features - such as transactions which would justify this speed decrease. The - Bugzilla team are, however, happy to hear about any experiences with - row level locking and Bugzilla.</para> - - <para>The <quote>shadowdb</quote> - parameter was designed to get around this limitation. While only a - single user is allowed to write to a table at a time, reads can - continue unimpeded on a read-only shadow copy of the database. - Although your database size will double, a shadow database can cause - an enormous performance improvement when implemented on extremely - high-traffic Bugzilla databases.</para> - - <para> - As a guide, on reasonably old hardware, mozilla.org began needing - <quote>shadowdb</quote> - when they reached around 40,000 Bugzilla users with several hundred - Bugzilla bug changes and comments per day.</para> - - <para>The value of the parameter defines the name of the - shadow bug database. You will need to set the host and port settings - from the params page, and set up replication in your database server - so that updates reach this readonly mirror. Consult your database - documentation for more detail.</para> - </step> - - <step> - <para> - <command>shutdownhtml</command>: - - If you need to shut down Bugzilla to perform administration, enter - some descriptive HTML here and anyone who tries to use Bugzilla will - receive a page to that effect. Obviously, editparams.cgi will - still be accessible so you can remove the HTML and re-enable Bugzilla. - :-) - </para> - </step> - - <step> - <para> - <command>passwordmail</command>: - - Every time a user creates an account, the text of - this parameter (with substitutions) is sent to the new user along with - their password message.</para> - - <para>Add any text you wish to the "passwordmail" parameter box. For - instance, many people choose to use this box to give a quick training - blurb about how to use Bugzilla at your site.</para> - </step> - - - <step> - <para> - <command>movebugs</command>: - - This option is an undocumented feature to allow moving bugs - between separate Bugzilla installations. You will need to understand - the source code in order to use this feature. Please consult - <filename>movebugs.pl</filename> in your Bugzilla source tree for - further documentation, such as it is. - </para> - </step> - - <step> - <para> - <command>useqacontact</command>: - - This allows you to define an email address for each component, in - addition - to that of the default owner, who will be sent carbon copies of - incoming bugs.</para> - </step> - <step> - <para> - <command>usestatuswhiteboard</command>: - This defines whether you wish to have a free-form, overwritable field - associated with each bug. The advantage of the Status Whiteboard is - that it can be deleted or modified with ease, and provides an - easily-searchable field for indexing some bugs that have some trait - in common. - </para> - </step> - - <step> - <para> - <command>whinedays</command>: - Set this to the number of days you want to let bugs go - in the NEW or REOPENED state before notifying people they have - untouched new bugs. If you do not plan to use this feature, simply do - not set up the whining cron job described in the installation - instructions, or set this value to "0" (never whine).</para> - </step> - - <step> - <para> - <command>commenton*</command>: - All these - fields allow you to dictate what changes can pass without comment, - and which must have a comment from the person who changed them. - Often, administrators will allow users to add themselves to the CC - list, accept bugs, or change the Status Whiteboard without adding a - comment as to their reasons for the change, yet require that most - other changes come with an explanation.</para> - - <para>Set the "commenton" options according to your site policy. It - is a wise idea to require comments when users resolve, reassign, or - reopen bugs at the very least. - <note> - <para>It is generally far better to require a developer comment - when resolving bugs than not. Few things are more annoying to bug - database users than having a developer mark a bug "fixed" without - any comment as to what the fix was (or even that it was truly - fixed!)</para> - </note> - </para> - </step> - - <step> - <para> - <command>supportwatchers</command>: - - Turning on this option allows users to ask to receive copies of - all a particular other user's bug email. This is, of - course, subject to the groupset restrictions on the bug; if the - <quote>watcher</quote> - would not normally be allowed to view a bug, the watcher cannot get - around the system by setting herself up to watch the bugs of someone - with bugs outside her privileges. They would still only receive email - updates for those bugs she could normally view.</para> - </step> - </procedure> - </section> - - <section id="useradmin"> - <title>User Administration</title> - - <section id="defaultuser"> - <title>Creating the Default User</title> - - <para>When you first run checksetup.pl after installing Bugzilla, it - will prompt you for the administrative username (email address) and - password for this "super user". If for some reason you delete - the "super user" account, re-running checksetup.pl will again prompt - you for this username and password.</para> - - <tip> - <para>If you wish to add more administrative users, add them to - the "admin" group and, optionally, add edit the tweakparams, editusers, - creategroups, editcomponents, and editkeywords groups to add the - entire admin group to those groups. - </para> - </tip> - </section> - - <section id="manageusers"> - <title>Managing Other Users</title> - - <section id="createnewusers"> - <title>Creating new users</title> - - <para>Your users can create their own user accounts by clicking the - "New Account" link at the bottom of each page (assuming they - aren't logged in as someone else already.) However, should you - desire to create user accounts ahead of time, here is how you do - it.</para> - - <orderedlist> - <listitem> - <para>After logging in, click the "Users" link at the footer of - the query page, and then click "Add a new user".</para> - </listitem> - - <listitem> - <para>Fill out the form presented. This page is self-explanatory. - When done, click "Submit".</para> - - <note> - <para>Adding a user this way will - <emphasis>not</emphasis> - - send an email informing them of their username and password. - While useful for creating dummy accounts (watchers which - shuttle mail to another system, for instance, or email - addresses which are a mailing list), in general it is - preferable to log out and use the - <quote>New Account</quote> - - button to create users, as it will pre-populate all the - required fields and also notify the user of her account name - and password.</para> - </note> - </listitem> - </orderedlist> - </section> - - <section id="modifyusers"> - <title>Modifying Users</title> - - <para>To see a specific user, search for their login name - in the box provided on the "Edit Users" page. To see all users, - leave the box blank.</para> - - <para>You can search in different ways the listbox to the right - of the text entry box. You can match by - case-insensitive substring (the default), - regular expression, or a - <emphasis>reverse</emphasis> - regular expression match, which finds every user name which does NOT - match the regular expression. (Please see - the <command>man regexp</command> - manual page for details on regular expression syntax.) - </para> - - <para>Once you have found your user, you can change the following - fields:</para> - - <itemizedlist> - <listitem> - <para> - <emphasis>Login Name</emphasis>: - This is generally the user's full email address. However, if you - have are using the emailsuffix Param, this may just be the user's - login name. Note that users can now change their login names - themselves (to any valid email address.) - </para> - </listitem> - - <listitem> - <para> - <emphasis>Real Name</emphasis>: The user's real name. Note that - Bugzilla does not require this to create an account.</para> - </listitem> - - <listitem> - <para> - <emphasis>Password</emphasis>: - You can change the user's password here. Users can automatically - request a new password, so you shouldn't need to do this often. - If you want to disable an account, see Disable Text below. - </para> - </listitem> - - <listitem> - <para> - <emphasis>Disable Text</emphasis>: - If you type anything in this box, including just a space, the - user is prevented from logging in, or making any changes to - bugs via the web interface. - The HTML you type in this box is presented to the user when - they attempt to perform these actions, and should explain - why the account was disabled. - <warning> - <para>Don't disable all the administrator accounts!</para> - </warning> - - <note> - <para>The user can still submit bugs via - the e-mail gateway, if you set it up, even if the disabled text - field is filled in. The e-mail gateway should - <emphasis>not</emphasis> - be enabled for secure installations of Bugzilla.</para> - </note> - </para> - </listitem> - - <listitem> - <para> - <emphasis><groupname></emphasis>: - If you have created some groups, e.g. "securitysensitive", then - checkboxes will appear here to allow you to add users to, or - remove them from, these groups. - </para> - </listitem> - - <listitem> - <para> - <emphasis>canconfirm</emphasis>: - This field is only used if you have enabled the "unconfirmed" - status. If you enable this for a user, - that user can then move bugs from "Unconfirmed" to a "Confirmed" - status (e.g.: "New" status).</para> - </listitem> - - <listitem> - <para> - <emphasis>creategroups</emphasis>: - This option will allow a user to create and destroy groups in - Bugzilla.</para> - </listitem> - - <listitem> - <para> - <emphasis>editbugs</emphasis>: - Unless a user has this bit set, they can only edit those bugs - for which they are the assignee or the reporter. Even if this - option is unchecked, users can still add comments to bugs. - </para> - </listitem> - - <listitem> - <para> - <emphasis>editcomponents</emphasis>: - This flag allows a user to create new products and components, - as well as modify and destroy those that have no bugs associated - with them. If a product or component has bugs associated with it, - those bugs must be moved to a different product or component - before Bugzilla will allow them to be destroyed. - </para> - </listitem> - - <listitem> - <para> - <emphasis>editkeywords</emphasis>: - If you use Bugzilla's keyword functionality, enabling this - feature allows a user to create and destroy keywords. As always, - the keywords for existing bugs containing the keyword the user - wishes to destroy must be changed before Bugzilla will allow it - to die.</para> - </listitem> - - <listitem> - <para> - <emphasis>editusers</emphasis>: - This flag allows a user to do what you're doing right now: edit - other users. This will allow those with the right to do so to - remove administrator privileges from other users or grant them to - themselves. Enable with care.</para> - </listitem> - - - <listitem> - <para> - <emphasis>tweakparams</emphasis>: - This flag allows a user to change Bugzilla's Params - (using <filename>editparams.cgi</filename>.)</para> - </listitem> - - <listitem> - <para> - <emphasis><productname></emphasis>: - This allows an administrator to specify the products in which - a user can see bugs. The user must still have the - "editbugs" privilege to edit bugs in these products.</para> - </listitem> - </itemizedlist> - </section> - </section> - </section> - - <section id="products"> - <title>Products</title> - - <para> - <glossterm linkend="gloss-product" baseform="product"> - Products</glossterm> - - are the broadest category in Bugzilla, and tend to represent real-world - shipping products. E.g. if your company makes computer games, - you should have one product per game, perhaps a "Common" product for - units of technology used in multiple games, and maybe a few special - products (Website, Administration...)</para> - - <para>Many of Bugzilla's settings are configurable on a per-product - basis. The number of "votes" available to users is set per-product, - as is the number of votes - required to move a bug automatically from the UNCONFIRMED status to the - NEW status.</para> - - <para>To create a new product:</para> - - <orderedlist> - <listitem> - <para>Select "products" from the footer</para> - - </listitem> - - <listitem> - <para>Select the "Add" link in the bottom right</para> - </listitem> - - <listitem> - <para>Enter the name of the product and a description. The - Description field may contain HTML.</para> - </listitem> - </orderedlist> - - <para>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. - </para> - </section> - - <section id="components"> - <title>Components</title> - - <para>Components are subsections of a Product. E.g. 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.</para> - - <para> - 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 - <emphasis>default assignments</emphasis>; - these can be changed on bug submission, or at any later point in - a bug's life.</para> - - <para>To create a new Component:</para> - - <orderedlist> - <listitem> - <para>Select the "Edit components" link from the "Edit product" - page</para> - </listitem> - - <listitem> - <para>Select the "Add" link in the bottom right.</para> - </listitem> - - <listitem> - <para>Fill out the "Component" field, a short "Description", - the "Initial Owner" and "Initial QA Contact" (if enabled.) - The Component and Description fields may contain HTML; - the "Initial Owner" field must be a login name - already existing in the database. - </para> - </listitem> - </orderedlist> - </section> - - <section id="versions"> - <title>Versions</title> - - <para>Versions are the revisions of the product, such as "Flinders - 3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select - field; the usual practice is to select the earliest version known to have - the bug. - </para> - - <para>To create and edit Versions:</para> - - <orderedlist> - <listitem> - <para>From the "Edit product" screen, select "Edit Versions"</para> - </listitem> - - <listitem> - <para>You will notice that the product already has the default - version "undefined". Click the "Add" link in the bottom right.</para> - </listitem> - - <listitem> - <para>Enter the name of the Version. This field takes text only. - Then click the "Add" button.</para> - </listitem> - - </orderedlist> - </section> - - <section id="milestones"> - <title>Milestones</title> - - <para>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.</para> - - <note> - <para>Milestone options will only appear for a Product if you turned - on the "usetargetmilestone" Param in the "Edit Parameters" screen. - </para> - </note> - - <para>To create new Milestones, set Default Milestones, and set - Milestone URL:</para> - - <orderedlist> - <listitem> - <para>Select "Edit milestones" from the "Edit product" page.</para> - </listitem> - - <listitem> - <para>Select "Add" in the bottom right corner. - text</para> - </listitem> - - <listitem> - <para>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. This is because milestones often do not - occur in alphanumeric order For example, "Future" might be - after "Release 1.2". Select "Add".</para> - </listitem> - - <listitem> - <para>From the Edit product screen, you can enter the URL of a - page which gives information about your milestones and what - they mean. </para> - </listitem> - </orderedlist> - </section> - - <section id="voting"> - <title>Voting</title> - - <para>Voting allows users to be given a pot of votes which they can allocate - to bugs, to indicate that they'd like them fixed. - 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.</para> - - <para>To modify Voting settings:</para> - - <orderedlist> - <listitem> - <para>Navigate to the "Edit product" screen for the Product you - wish to modify</para> - </listitem> - - <listitem> - <para><emphasis>Maximum Votes per person</emphasis>: - Setting this field to "0" disables voting.</para> - </listitem> - - <listitem> - <para><emphasis>Maximum Votes a person can put on a single - bug</emphasis>: - It should probably be some number lower than the - "Maximum votes per person". Don't set this field to "0" if - "Maximum votes per person" is non-zero; that doesn't make - any sense.</para> - </listitem> - - <listitem> - <para><emphasis>Number of votes a bug in this product needs to - automatically get out of the UNCONFIRMED state</emphasis>: - Setting this field to "0" disables the automatic move of - bugs from UNCONFIRMED to NEW. - </para> - </listitem> - - <listitem> - <para>Once you have adjusted the values to your preference, click - "Update".</para> - </listitem> - </orderedlist> - </section> - - <section id="groups"> - <title>Groups and Group Security</title> - - <para>Groups allow the administrator - to isolate bugs or products that should only be seen by certain people. - The association between products and groups is controlled from - the product edit page under <quote>Edit Group Controls.</quote> - </para> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> + +<!-- TOC +Chapter: Administration + Localconfig and Checksetup.pl customizations + The Email Gateway + Editing parameters + Deciding your site policies + The Shadow Database + Customizing password mail & layout + The Whining Cron + Why you shouldn't allow deletion + User administration + Creating Users + Disabling Users + User Permissions + Product Administration + Creating products + Creating components + Assigning default owners and Q/A contacts to components + Product Milestones + Product Versions + Voting +--> - <para> - If the makeproductgroups param is on, a new group will be automatically - created for every new product. - </para> +<CHAPTER id="administration"> + <TITLE>Administering Bugzilla</TITLE> +<SUBTITLE>Or, I just got this cool thing installed. Now what the heck do I do with it?</SUBTITLE> + +<PARA> +So you followed the README isntructions to the letter, and +just logged into bugzilla with your super-duper god account and you are sitting at the query +screen. Yet, you have nothing to query. Your first act of business needs to be to setup the +operating parameters for bugzilla.</PARA> + + <SECTION id="postinstall-check"> + <TITLE>Post-Installation Checklist</TITLE> + <PARA> + After installation, follow the checklist below to ensure that + you have a successful installation. + If you do not see a recommended setting for a parameter, + consider leaving it at the default + while you perform your initial tests on your Bugzilla setup. + </PARA> + <INDEXTERM> + <PRIMARY>checklist</PRIMARY> + </INDEXTERM> + <PROCEDURE> + <STEP> + <PARA> + Bring up "editparams.cgi" in your web browser. For instance, to edit parameters + at mozilla.org, the URL would be <ULINK URL="http://bugzilla.mozilla.org/editparams.cgi"> + http://bugzilla.mozilla.org/editparams.cgi</ULINK>, also available under the "edit parameters" + link on your query page. + </PARA> + </STEP> + <STEP> + <PARA> + Set "maintainer" to <EMPHASIS>your</EMPHASIS> email address. + This allows Bugzilla's error messages + to display your email + address and allow people to contact you for help. + </PARA> + </STEP> + <STEP> + <PARA> + Set "urlbase" to the URL reference for your Bugzilla installation. + If your bugzilla query page is at http://www.foo.com/bugzilla/query.cgi, + your url base is http://www.foo.com/bugzilla/ + </PARA> + </STEP> + <STEP> + <PARA> + Set "usebuggroups" to "1" <EMPHASIS>only</EMPHASIS> + if you need to restrict access to products. + I suggest leaving this parameter <EMPHASIS>off</EMPHASIS> + while initially testing your Bugzilla. + </PARA> + </STEP> + <STEP> + <PARA> + Set "usebuggroupsentry" to "1" if you want to restrict access to products. + Once again, if you are simply testing your installation, I suggest against + turning this parameter on; the strict security checking may stop you from + being able to modify your new entries. + </PARA> + </STEP> + <STEP> + <PARA> + Set "shadowdb" to "bug_shadowdb" if you will be + running a *very* large installation of Bugzilla. + The shadow database enables many simultaneous users + to read and write to the database + without interfering with one another. + <NOTE> + <PARA> + Enabling "shadowdb" can adversely affect the stability + of your installation of Bugzilla. + You may frequently need to manually synchronize your databases, + or schedule nightly syncs + via "cron" + </PARA> + </NOTE> + Once again, in testing you should + avoid this option -- use it if or when you <EMPHASIS>need</EMPHASIS> to use it, and have + repeatedly run into the problem it was designed to solve -- very long wait times while + attempting to commit a change to the database. + </PARA> + <PARA> + If you use the "shadowdb" option, + it is only natural that you should turn the "queryagainstshadowdb" + option "On" as well. Otherwise you are replicating data into a shadow database for no reason! + </PARA> + </STEP> + <STEP> + <PARA> + If you have custom logos or HTML you must put in place to fit within your site design guidelines, + place the code in the "headerhtml", "footerhtml", "errorhtml", + "bannerhtml", or "blurbhtml" text boxes. + <NOTE> + <PARA> + The "headerhtml" text box is the HTML printed out + <EMPHASIS>before</EMPHASIS> any other code on the page. + If you have a special banner, put the code for it in "bannerhtml". + You may want to leave these + settings at the defaults initially. + </PARA> + </NOTE> + </PARA> + </STEP> + <STEP> + <PARA> + Add any text you wish to the "passwordmail" parameter box. For instance, + many people choose to use this box to give a quick training blurb about how to + use Bugzilla at your site. + </PARA> + </STEP> + <STEP> + <PARA> + Ensure "newemailtech" is "on". + Your users will thank you. This is the default in the post-2.12 world, and is + only an issue if you are upgrading. + </PARA> + </STEP> + <STEP> + <PARA> + Do you want to use the qa contact ("useqacontact") + and status whiteboard ("usestatuswhiteboard") fields? + These fields are useful because they allow for more flexibility, + particularly when you have an existing + Quality Assurance and/or Release Engineering team, + but they may not be needed for smaller installations. + </PARA> + </STEP> + <STEP> + <PARA> + Set "whinedays" to the amount of days you want to let bugs go + in the "New" or "Reopened" state before + notifying people they have untouched new bugs. If you do not plan to use this feature, simply do + not set up the whining cron job described in the README, or set this value to "0". + </PARA> + </STEP> + <STEP> + <PARA> + Set the "commenton" options according to your site policy. + It is a wise idea to require comments when users + resolve, reassign, or reopen bugs. + <NOTE> + <PARA> + It is generally far better to require a developer comment when resolving bugs than not. + Few things are more annoying to bug database users than having a developer + mark a bug "fixed" without any comment as to what the fix was (or even that it was truly fixed!) + </PARA> + </NOTE> + </PARA> + </STEP> + <STEP> + <PARA> + Set "supportwatchers" to "On". This feature is helpful for team leads to monitor progress in their + respective areas, and can offer many other benefits, such as allowing a developer to pick up a + former engineer's bugs without requiring her to change all the information in the bug. + </PARA> + </STEP> + </PROCEDURE> + </SECTION> + + <SECTION id="useradmin"> + <TITLE>User Administration</TITLE> + <PARA> + User administration is one of the easiest parts of Bugzilla. + Keeping it from getting out of hand, however, can become a challenge. + </PARA> + + <SECTION id="defaultuser"> + <TITLE>Creating the Default User</TITLE> + + <PARA> + When you first run checksetup.pl after installing Bugzilla, it will prompt you + for the administrative username (email address) and password for this "super user". + If for some reason you were to delete the "super user" account, re-running + checksetup.pl will again prompt you for this username and password. + </PARA> + <TIP> + <PARA> + If you wish to add more administrative users, you must use the MySQL interface. + Run "mysql" from the command line, and use these commands ("mysql>" denotes the + mysql prompt, not something you should type in): + <COMMAND><PROMPT>mysql></PROMPT> use bugs;</COMMAND> + <COMMAND><PROMPT>mysql></PROMPT> update profiles set groupset=0x7ffffffffffffff + where login_name = "(user's login name)"; </COMMAND> + </PARA> + </TIP> + </SECTION> + + <SECTION id="manageusers"> + <TITLE>Managing Other Users</TITLE> + + <SECTION id="login"> + <TITLE>Logging In</TITLE> + <ORDEREDLIST> + <LISTITEM> + <PARA> + Open the index.html page for your Bugzilla installation in your browser window. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Click the "Query Existing Bug Reports" link. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Click the "Log In" link at the foot of the page. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Type your email address, and the password which was emailed to you when you + created your Bugzilla account, into the spaces provided. + </PARA> + </LISTITEM> + </ORDEREDLIST> + <PARA>Congratulations, you are logged in!</PARA> + </SECTION> + + <SECTION id="createnewusers"> + <TITLE>Creating new users</TITLE> + <PARA> + Your users can create their own user accounts by clicking the "New Account" + link at the bottom of each page. + However, should you desire to create user accounts ahead of time, here is how you do it. + </PARA> + <ORDEREDLIST> + <LISTITEM> + <PARA> + After logging in, click the "Users" link at the footer of the query page. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + To see a specific user, type a portion of their login name + in the box provided and click "submit". + To see all users, simply click the "submit" button. + You must click "submit" here to be able to add a new user. + </PARA> + <TIP> + <PARA> + More functionality is available via the list on the right-hand side + of the text entry box. + You can match what you type as a case-insensitive substring (the default) + of all users on your system, a case-sensitive regular expression + (please see the "man regexp" manual page for details on regular expression syntax), + or a <EMPHASIS>reverse</EMPHASIS> regular expression match, + where every user name which does NOT match the regular expression + is selected. + </PARA> + </TIP> + </LISTITEM> + <LISTITEM> + <PARA> + Click the "Add New User" link at the bottom of the user list + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Fill out the form presented. This page is self-explanatory. When done, click "submit". + </PARA> + <NOTE> + <PARA> + Adding a user this way will <EMPHASIS>not</EMPHASIS> send an email + informing them of their username and password. + In general, it is preferable to log out and use the "New Account" + button to create users, as it will pre-populate all the required fields and also notify + the user of her account name and password. + </PARA> + </NOTE> + </LISTITEM> + </ORDEREDLIST> + </SECTION> + + <SECTION id="disableusers"> + <TITLE>Disabling Users</TITLE> + <PARA> + I bet you noticed that big "Disabled Text" entry box available from the "Add New User" screen, + when you edit an account? + By entering any text in this box and selecting "submit", + you have prevented the user from using Bugzilla via the web interface. + Your explanation, written in this text box, will be presented to the user + the next time she attempts to use the system. + <WARNING> + <PARA> + Don't disable your own administrative account, or you will hate life! + </PARA> + </WARNING> + </PARA> + </SECTION> + + <SECTION id="modifyusers"> + <TITLE>Modifying Users</TITLE> + <PARA> + Here I will attempt to describe the function of each option on the user edit screen. + </PARA> + <ITEMIZEDLIST> + <LISTITEM> + <PARA> + <EMPHASIS>Login Name</EMPHASIS>: This is generally the user's email address. + However, if you have edited your system parameters, + this may just be the user's login name or some other identifier. + <TIP> + <PARA> + For compatability reasons, you should probably + stick with email addresses as user login names. It will make your life easier. + </PARA> + </TIP> + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>Real Name</EMPHASIS>: Duh! + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>Password</EMPHASIS>: You will only see asterisks in versions + of Bugzilla newer than 2.10 or early 2.11. You can change the user password here. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>Email Notification</EMPHASIS>: You may choose from one of three options: + <ORDEREDLIST> + <LISTITEM> + <PARA> + All qualifying bugs except those which I change: + The user will be notified of any change to any bug + for which she is the reporter, assignee, Q/A contact, CC recipient, or "watcher". + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Only those bugs which I am listed on the CC line: + The user will not be notified of changes to bugs where she is the assignee, + reporter, or Q/A contact, but will receive them if she is on the CC list. + <NOTE> + <PARA> + She will still receive whining cron emails if you set up the "whinemail" feature. + </PARA> + </NOTE> + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>All Qualifying Bugs</EMPHASIS>: This user is a glutton for punishment. + If her name is in the reporter, Q/A contact, CC, assignee, or is a "watcher", + she will get email updates regarding the bug. + </PARA> + </LISTITEM> + </ORDEREDLIST> +</PARA> + <PARA> + <EMPHASIS>Disable Text</EMPHASIS>: If you type anything in this box, + including just a space, the user account is disabled from making any changes + to bugs via the web interface, and what you type in this box is presented as the reason. + <WARNING> + <PARA>Don't disable the administrator account!</PARA> + </WARNING> + <NOTE> + <PARA> + As of this writing, the user can still submit bugs via the e-mail gateway, + if you set it up, despite the disabled text field. The e-mail gateway should + <EMPHASIS>not</EMPHASIS> be enabled for secure installations of Bugzilla. + </PARA> + </NOTE> + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>CanConfirm</EMPHASIS>: This field is only used if you have enabled + "unconfirmed" status in your parameters screen. If you enable this for a user, + that user can then move bugs from "Unconfirmed" to "Confirmed" status (ergo: "New" status). + Be judicious about allowing users to turn this bit on for other users. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>Creategroups</EMPHASIS>: This option will allow a user to create and + destroy groups in Bugzilla. Unless you are using the Bugzilla GroupSentry security + option "usebuggroupsentry" in your parameters, this setting has no effect. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>Editbugs</EMPHASIS>: Unless a user has this bit set, they can only edit + those bugs for which they are the assignee or the reporter. + <NOTE> + <PARA> + Leaving this option unchecked does not prevent users from adding + comments to a bug! They simply cannot change a bug priority, severity, + etc. unless they are the assignee or reporter. + </PARA> + </NOTE> + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>Editcomponents</EMPHASIS>: This flag allows a user to create new + products and components, as well as modify and destroy those that have no bugs + associated with them. If a product or component has bugs associated with it, + those bugs must be moved to a different product or component before Bugzilla + will allow them to be destroyed. The name of a product or component can be + changed without affecting the associated bugs, but it tends to annoy + the hell out of your users when these change a lot. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>Editkeywords</EMPHASIS>: If you use Bugzilla's keyword functionality, + enabling this feature allows a user can create and destroy keywords. + As always, the keywords for existing bugs containing the keyword + the user wishes to destroy must be changed before Bugzilla will allow it to die. + You must be very careful about creating too many new keywords + if you run a very large Bugzilla installation; keywords are global variables + across products, and you can often run into a phenomenon called "keyword bloat". + This confuses users, and then the feature goes unused. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>Editusers</EMPHASIS>: This flag allows a user do what you're doing + right now: edit other users. + This will allow those with the right to do so to remove administrator + priveleges from other users or grant them to themselves. Enable with care. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + <EMPHASIS>PRODUCT</EMPHASIS>: PRODUCT bugs access. This allows an administrator, + with product-level granularity, to specify in which products a user can edit bugs. + The user must still have the "editbugs" privelege to edit bugs in this area; + this simply restricts them from even seeing bugs outside these boundaries if the administrator + has enabled the group sentry parameter "usebuggroupsentry". Unless you are using bug groups, + this option has no effect. + </PARA> + </LISTITEM> + </ITEMIZEDLIST> + </SECTION> + </SECTION> + </SECTION> + + <SECTION id="programadmin"> + <TITLE>Product, Component, Milestone, and Version Administration</TITLE> + <EPIGRAPH> + <PARA> + Dear Lord, we have to get our users to do WHAT? + </PARA> + </EPIGRAPH> + + <SECTION id="products"> + <TITLE>Products</TITLE> + <SUBTITLE>Formerly, and in some spots still, called "Programs"</SUBTITLE> + <PARA> + <GLOSSTERM baseform="product" linkend="gloss_product">Products</GLOSSTERM> 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...) + </PARA> + <PARA> + 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. + </PARA> + <PARA>To create a new product:</PARA> + <ORDEREDLIST> + <LISTITEM> + <PARA> + Select "components" from the yellow footer + </PARA> + <TIP> + <PARA> + 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... + </PARA> + </TIP> + </LISTITEM> + <LISTITEM> + <PARA> + Select the "Add" link to the right of "Add a new product". + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Enter the name of the product and a description. + The Description field is free-form. + </PARA> + </LISTITEM> + </ORDEREDLIST> + <TIP> + <PARA> + 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. + </PARA> + </TIP> + </SECTION> - <para> - On the product edit page, there is a page to edit the - <quote>Group Controls</quote> - for a product and determine which groups are applicable, default, - and mandatory for each product as well as controlling entry - for each product and being able to set bugs in a product to be - totally read-only unless some group restrictions are met. - </para> + <SECTION id="components"> + <TITLE>Components</TITLE> + <PARA> + Components are subsections of a Product. + + <EXAMPLE> + <TITLE>Creating some Components</TITLE> + <INFORMALEXAMPLE> + <PARA> + 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. + </PARA> + </INFORMALEXAMPLE> + </EXAMPLE> + + 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 + <EMPHASIS>default assignments</EMPHASIS>; the Owner and Q/A Contact fields in a bug + are otherwise unrelated to the Component. + </PARA> + + <PARA> + To create a new Component: + </PARA> + <ORDEREDLIST> + <LISTITEM> + <PARA> + Select the "Edit components" link from the "Edit Product" page + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Select the "Add" link to the right of the "Add a new component" text + on the "Select Component" page. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + <TIP> + <PARA> + Is your "Default Owner" a user who is not yet in the database? + No problem. + <ORDEREDLIST> + <LISTITEM> + <PARA> + Select the "Log out" link on the footer of the page. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Select the "New Account" link on the footer of the "Relogin" page + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Now select "Log in" again, type in your login information, and you + can modify the product to use the Default Owner information + you require. + </PARA> + </LISTITEM> + </ORDEREDLIST> + </PARA> + </TIP> + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + </LISTITEM> + </ORDEREDLIST> + </SECTION> - <para> - For each group, it is possible to specify if membership in that - group is... - </para> - <orderedlist> - <listitem> - <para> - required for bug entry, - </para> - </listitem> - <listitem> - <para> - Not applicable to this product(NA), - a possible restriction for a member of the - group to place on a bug in this product(Shown), - a default restriction for a member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product(Mandatory). - </para> - </listitem> - <listitem> - <para> - Not applicable by non-members to this product(NA), - a possible restriction for a non-member of the - group to place on a bug in this product(Shown), - a default restriction for a non-member of the - group to place on a bug in this product(Default), - or a mandatory restriction to be placed on bugs - in this product when entered by a non-member(Mandatory). - </para> - </listitem> - <listitem> - <para> - required in order to make <emphasis>any</emphasis> change - to bugs in this product <emphasis>including comments.</emphasis> - </para> - </listitem> - </orderedlist> + <SECTION id="versions"> + <TITLE>Versions</TITLE> + <PARA> + 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> + <TITLE>Common Use of Versions</TITLE> + <INFORMALEXAMPLE> + <PARA> + 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 + </PARA> + </INFORMALEXAMPLE> + </EXAMPLE> + <EXAMPLE> + <TITLE>A Different Use of Versions</TITLE> + <INFORMALEXAMPLE> + <PARA> + 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. + </PARA> + </INFORMALEXAMPLE> + </EXAMPLE> + </PARA> + <PARA> + To create and edit Versions: + </PARA> + <ORDEREDLIST> + <LISTITEM> + <PARA> + From the "Edit Product" screen, select "Edit Versions" + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + <PARA> + Otherwise, click the "Add" button to the right of the "Add a new version" text. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + </LISTITEM> + </ORDEREDLIST> + </SECTION> - <para>To create Groups:</para> - - <orderedlist> - <listitem> - <para>Select the <quote>groups</quote> - link in the footer.</para> - </listitem> - - <listitem> - <para>Take a moment to understand the instructions on the <quote>Edit - Groups</quote> screen, then select the <quote>Add Group</quote> link.</para> - </listitem> - - <listitem> - <para>Fill out the <quote>Group</quote>, <quote>Description</quote>, - and <quote>User RegExp</quote> fields. - <quote>User RegExp</quote> allows you to automatically - place all users who fulfill the Regular Expression into the new group. - When you have finished, click <quote>Add</quote>.</para> - <warning> - <para>If specifying a domain in the regexp, make sure you end - the regexp with a $. Otherwise, when granting access to - "@mycompany\.com", you will allow access to - 'badperson@mycompany.com.cracker.net'. You need to use - '@mycompany\.com$' as the regexp.</para> - </warning> - </listitem> - <listitem> - <para>After you add your new group, edit the new group. On the - edit page, you can specify other groups that should be included - in this group and which groups should be permitted to add and delete - users from this group.</para> - </listitem> - </orderedlist> - - <para> - Note that group permissions are such that you need to be a member - of <emphasis>all</emphasis> the groups a bug is in, for whatever - reason, to see that bug. Similarly, you must be a member - of <emphasis>all</emphasis> of the entry groups for a product - to add bugs to a product and you must be a member - of <emphasis>all</emphasis> of the canedit groups for a product - in order to make <emphasis>any</emphasis> change to bugs in that - product. - </para> - </section> - - <section id="upgrading"> - <title>Upgrading to New Releases</title> - - <warning> - <para>Upgrading is a one-way process. You should backup your database - and current Bugzilla directory before attempting the upgrade. If you wish - to revert to the old Bugzilla version for any reason, you will have to - restore from these backups. - </para> - </warning> - - <para>Upgrading Bugzilla is something we all want to do from time to time, - be it to get new features or pick up the latest security fix. How easy - it is to update depends on a few factors. - </para> - - <itemizedlist> - <listitem> - <para>If the new version is a revision or a new point release</para> - </listitem> - <listitem> - <para>How many, if any, local changes have been made</para> - </listitem> - </itemizedlist> - - <para>There are also three different methods to upgrade your installation. - </para> - - <orderedlist> - <listitem> - <para>Using CVS (<xref linkend="upgrade-cvs"/>)</para> - </listitem> - <listitem> - <para>Downloading a new tarball (<xref linkend="upgrade-tarball"/>)</para> - </listitem> - <listitem> - <para>Applying the relevant patches (<xref linkend="upgrade-patches"/>)</para> - </listitem> - </orderedlist> - - <para>Which options are available to you may depend on how large a jump - you are making and/or your network configuration. - </para> - - <para>Revisions are normally released to fix security vulnerabilities - and are distinguished by an increase in the third number. For example, - when 2.16.2 was released, it was a revision to 2.16.1. - </para> - - <para>Point releases are normally released when the Bugzilla team feels - that there has been a significant amount of progress made between the - last point release and the current time. These are often proceeded by a - stabilization period and release candidates, however the use of - development versions or release candidates is beyond the scope of this - document. Point releases can be distinguished by an increase in the - second number, or minor version. For example, 2.16.2 is a newer point - release than 2.14.5. - </para> - - <para>The examples in this section are written as if you were updating - to version 2.16.2. The procedures are the same regardless if you are - updating to a new point release or a new revision. However, the chance - of running into trouble increases when upgrading to a new point release, - escpecially if you've made local changes. - </para> - - <para>These examples also assume that your Bugzilla installation is at - <filename>/var/www/html/bugzilla</filename>. If that is not the case, - simply substitute the proper paths where appropriate. - </para> - - <example id="upgrade-cvs"> - <title>Upgrading using CVS</title> - - <para>Every release of Bugzilla, whether it is a revision or a point - release, is tagged in CVS. Also, every tarball we have distributed - since version 2.12 has been primed for using CVS. This does, however, - require that you are able to access cvs-mirror.mozilla.org on port - 2401. - - <tip> - <para>If you can do this, updating using CVS is probably the most - painless method, especially if you have a lot of local changes. - </para> - </tip> - </para> - - <programlisting> -bash$ <command>cd /var/www/html/bugzilla</command> -bash$ <command>cvs login</command> -Logging in to :pserver:anonymous@cvs-mirror.mozilla.org:2401/cvsroot -CVS password: <command>anonymous</command> -bash$ <command>cvs -q update -r BUGZILLA-2_16_2 -dP</command> -P checksetup.pl -P collectstats.pl -P globals.pl -P docs/rel_notes.txt -P template/en/default/list/quips.html.tmpl - </programlisting> - - <para> - <caution> - <para>If a line in the output from <command>cvs update</command> - begins with a <computeroutput>C</computeroutput> that represents a - file with local changes that CVS was unable to properly merge. You - need to resolve these conflicts manually before Bugzilla (or at - least the portion using that file) will be usable. - </para> - </caution> - - <note> - <para>You also need to run <command>./checksetup.pl</command> - before your Bugzilla upgrade will be complete. - </para> - </note> - </para> - </example> - - <example id="upgrade-tarball"> - <title>Upgrading using the tarball</title> - - <para>If you are unable or unwilling to use CVS, another option that's - always available is to download the latest tarball. This is the most - difficult option to use, especially if you have local changes. - </para> - - <programlisting> -bash$ <command>cd /var/www/html</command> -bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.2.tar.gz</command> -<emphasis>Output omitted</emphasis> -bash$ <command>tar xzvf bugzilla-2.16.2.tar.gz</command> -bugzilla-2.16.2/ -bugzilla-2.16.2/.cvsignore -bugzilla-2.16.2/1x1.gif -<emphasis>Output truncated</emphasis> -bash$ <command>cd bugzilla-2.16.2</command> -bash$ <command>cp ../bugzilla/localconfig* .</command> -bash$ <command>cp -r ../bugzilla/data .</command> -bash$ <command>cd ..</command> -bash$ <command>mv bugzilla bugzilla.old</command> -bash$ <command>mv bugzilla-2.16.2 bugzilla</command> -bash$ <command>cd bugzilla</command> -bash$ <command>./checksetup.pl</command> -<emphasis>Output omitted</emphasis> - </programlisting> - - <para> - <warning> - <para>The <command>cp</command> commands both end with periods which - is a very important detail, it tells the shell that the destination - directory is the current working directory. Also, the period at the - beginning of the <command>./checksetup.pl</command> is important and - can not be omitted. - </para> - </warning> - - <note> - <para>You will now have to reapply any changes you have made to your - local installation manually. - </para> - </note> - </para> - </example> - - <example id="upgrade-patches"> - <title>Upgrading using patches</title> - - <para>The Bugzilla team will normally make a patch file available for - revisions to go from the most recent revision to the new one. You could - also read the release notes and grab the patches attached to the - mentioned bug, but it is safer to use the released patch file as - sometimes patches get changed before they get checked in. - It is also theoretically possible to - scour the fixed bug list and pick and choose which patches to apply - from a point release, but this is not recommended either as what you'll - end up with is a hodge podge Bugzilla that isn't really any version. - This would also make it more difficult to upgrade in the future. - </para> - - <programlisting> -bash$ <command>cd /var/www/html/bugzilla</command> -bash$ <command>wget ftp://ftp.mozilla.org/pub/webtools/bugzilla-2.16.1-to-2.16.2.diff.gz</command> -<emphasis>Output omitted</emphasis> -bash$ <command>gunzip bugzilla-2.16.1-to-2.16.2.diff.gz</command> -bash$ <command>patch -p1 < bugzilla-2.16.1-to-2.16.2.diff</command> -patching file checksetup.pl -patching file collectstats.pl -patching file globals.pl - </programlisting> - - <para> - <caution> - <para>If you do this, beware that this doesn't change the entires in - your <filename id="dir">CVS</filename> directory so it may make - updates using CVS (<xref linkend="upgrade-cvs"/>) more difficult in the - future. - </para> - </caution> - </para> - </example> + <SECTION id="milestones"> + <TITLE>Milestones</TITLE> + <PARA> + 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. + </PARA> + <NOTE> + <PARA> + Milestone options will only appear for a Product if you turned the "usetargetmilestone" field + in the "Edit Parameters" screen "On". + </PARA> + </NOTE> + <PARA> + To create new Milestones, set Default Milestones, and set Milestone URL: + </PARA> + <ORDEREDLIST> + <LISTITEM> + <PARA> + Select "edit milestones" + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Select "Add" to the right of the "Add a new milestone" text + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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". + </PARA> + <EXAMPLE> + <TITLE>Using SortKey with Target Milestone</TITLE> + <INFORMALEXAMPLE> + <PARA> + 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" + </PARA> + </INFORMALEXAMPLE> + </EXAMPLE> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + <NOTE> + <PARA> + 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. + </PARA> + </NOTE> + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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" + </PARA> + <PARA> + Some common uses of this field include product descriptions, product roadmaps, + and of course a simple description of the meaning of each milestone. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + <PARA>Select the "Update" button when you are done.</PARA> + </LISTITEM> + <LISTITEM> + <PARA> + + </PARA> + </LISTITEM> + </ORDEREDLIST> + </SECTION> + + <SECTION id="voting"> + <TITLE>Voting</TITLE> + <PARA> + 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. + </PARA> + <PARA> + 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. + </PARA> + <PARA>To modify Voting settings:</PARA> + <ORDEREDLIST> + <LISTITEM> + <PARA> + Navigate to the "Edit Product" screen for the Product you wish to modify + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Set "Maximum Votes per person" to your calculated value. Setting this field + to "0" disables voting. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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? + <TIP> + <PARA> + 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 <EMPHASIS>really</EMPHASIS> bad bug! + </PARA> + </TIP> + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Once you have adjusted the values to your preference, select the "Update" button. + </PARA> + </LISTITEM> + </ORDEREDLIST> + </SECTION> + + <SECTION id="groups"> + <TITLE>Groups and Group Security</TITLE> + <PARA> + 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> + <TITLE>When to Use Group Security</TITLE> + <INFORMALEXAMPLE> + <PARA> + 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. + </PARA> + </INFORMALEXAMPLE> + </EXAMPLE> + + 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. + </PARA> + <NOTE> + <PARA> + 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. + </PARA> + <PARA> + 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. + </PARA> + </NOTE> + <PARA> + To enable Generic Group Security ("usebuggroups"): + </PARA> + <ORDEREDLIST> + <LISTITEM> + <PARA> + Turn "On" "usebuggroups" in the "Edit Parameters" screen. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + You will generally have no groups set up. Select the "groups" link + in the footer. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + + <EXAMPLE> + <TITLE>Creating a New Group</TITLE> + <INFORMALEXAMPLE> + <PARA> + 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. + </PARA> + </INFORMALEXAMPLE> + </EXAMPLE> + + When you have finished, select the "Add" button. + </PARA> + </LISTITEM> + </ORDEREDLIST> + + <PARA> + To enable Product-Based Group Security ("usebuggroupsentry"): + </PARA> + <WARNING> + <PARA> + 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. + </PARA> + </WARNING> + <ORDEREDLIST> + <LISTITEM> + <PARA> + Turn "On" "usebuggroups" and "usebuggroupsentry" in the "Edit Parameters" screen. + </PARA> + <WARNING> + <PARA> + "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. + </PARA> + </WARNING> + </LISTITEM> + <LISTITEM> + <PARA> + 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. + </PARA> + </LISTITEM> + </ORDEREDLIST> + </SECTION> + </SECTION> + + <SECTION id="security"> + <TITLE>Bugzilla Security</TITLE> + <EPIGRAPH> + <PARA> + Putting your money in a wall safe is better protection than depending on the fact that + no one knows that you hide your money in a mayonnaise jar in your fridge. + </PARA> + </EPIGRAPH> + <NOTE> + <PARA> + Poorly-configured MySQL, Bugzilla, and FTP installations have given attackers full + access to systems in the past. Please take these guidelines seriously, even + for Bugzilla machines hidden away behind your firewall. 80% of all computer + trespassers are insiders, not anonymous crackers. + </PARA> + </NOTE> + <PARA> + First thing's first: Secure your installation. + <NOTE> + <PARA> + These instructions must, of necessity, be somewhat vague since Bugzilla runs on so many different + platforms. If you have refinements of these directions for specific platforms, please + submit them to <ULINK URL="mailto://mozilla-webtools@mozilla.org">mozilla-webtools@mozilla.org</ULINK> + </PARA> + </NOTE> + <ORDEREDLIST> + <LISTITEM> + <PARA> + Ensure you are running at least MysQL version 3.22.32 or newer. Earlier versions had + notable security holes and poorly secured default configuration choices. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA><EMPHASIS>There is no substitute for understanding the tools on your system!</EMPHASIS> + Read <ULINK URL="http://www.mysql.com/documentation/mysql/bychapter/manual_Privilege_system.html"> + The MySQL Privelege System</ULINK> until you can recite it from memory!</PARA> + <PARA> + At the very least, ensure you password the "mysql -u root" account and the "bugs" account, establish grant + table rights (consult the Keystone guide in Appendix C: The Bugzilla Database for some easy-to-use details) + that do not allow CREATE, DROP, RELOAD, SHUTDOWN, and PROCESS for user "bugs". I wrote up the Keystone + advice back when I knew far less about security than I do now : ) + </PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Lock down /etc/inetd.conf. Heck, disable inet entirely on this box. It should only listen to + port 25 for Sendmail + and port 80 for Apache. + </PARA> + </LISTITEM> + <LISTITEM> + <PARA>Do not run Apache as "nobody". This will require very lax permissions in your Bugzilla directories. + Run it, instead, as a user with a name, set via your httpd.conf file.</PARA> + </LISTITEM> + <LISTITEM> + <PARA> + Ensure you have adequate access controls for the $BUGZILLA_HOME/data/ and + $BUGZILLA_HOME/shadow/ directories, as well as the $BUGZILLA_HOME/localconfig file. + The localconfig file stores your "bugs" user password, + which would be terrible to have in the hands + of a criminal. Also some files under $BUGZILLA_HOME/data/ store sensitive information, and + $BUGZILLA_HOME/shadow/ stores bug information for faster retrieval. If you fail to secure + these directories and this file, you will expose bug information to those who may not + be allowed to see it. + </PARA> + <PARA> + On Apache, you can use .htaccess files to protect access to these directories, as outlined + in <ULINK URL="http://bugzilla.mozilla.org/show_bug.cgi?id=57161">Bug 57161</ULINK> for the + localconfig file, and <ULINK URL="http://bugzilla.mozilla.org/show_bug.cgi?id=65572"> + Bug 65572</ULINK> for adequate protection in your data/ and shadow/ directories. + </PARA> + <PARA> + Note the instructions which follow are Apache-specific. If you use IIS, Netscape, or other + non-Apache web servers, please consult your system documentation for how to secure these + files from being transmitted to curious users. + </PARA> + <PARA> + Place the following text into a file named ".htaccess", readable by your web server, + in your $BUGZILLA_HOME/data directory. + <LITERALLAYOUT> + <Files comments> + allow from all + </Files> + deny from all + </LITERALLAYOUT> + </PARA> + <PARA> + Place the following text into a file named ".htaccess", readable by your web server, + in your $BUGZILLA_HOME/ directory. + <LITERALLAYOUT> + <Files localconfig> + deny from all + </Files> + allow from all + </LITERALLAYOUT> + </PARA> + <PARA> + Place the following text into a file named ".htaccess", readable by your web server, + in your $BUGZILLA_HOME/shadow directory. + <LITERALLAYOUT> + deny from all + </LITERALLAYOUT> + </PARA> + </LISTITEM> + </ORDEREDLIST> + </PARA> + </SECTION> +</CHAPTER> - </section> -</chapter> <!-- Keep this comment at the end of the file Local variables: mode: sgml +sgml-omittag:t +sgml-shorttag:t +sgml-namecase-general:t +sgml-general-insert-case:upper +sgml-minimize-attributes:nil sgml-always-quote-attributes:t -sgml-auto-insert-required-elements:t -sgml-balanced-tag-edit:t -sgml-exposed-tags:nil -sgml-general-insert-case:lower -sgml-indent-data:t sgml-indent-step:2 +sgml-indent-data:t +sgml-parent-document:nil +sgml-exposed-tags:nil sgml-local-catalogs:nil sgml-local-ecat-files:nil -sgml-minimize-attributes:nil -sgml-namecase-general:t -sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") -sgml-shorttag:t -sgml-tag-region-if-active:t End: --> - |