| <!-- <!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> |
| |
| <variablelist> |
| <varlistentry> |
| <term> |
| maintainer |
| </term> |
| <listitem> |
| <para> |
| 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| urlbase |
| </term> |
| <listitem> |
| <para> |
| 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| makeproductgroups |
| </term> |
| <listitem> |
| <para> |
| This dictates whether or not to automatically create groups |
| when new products are created. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| useentrygroupdefault |
| </term> |
| <listitem> |
| <para> |
| 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| maildeliverymethod |
| </term> |
| <listitem> |
| <para> |
| This is used to specify how email is sent, or if it is sent at |
| all. There are several options included for different MTAs, |
| along with two additional options that disable email sending. |
| "testfile" does not send mail, but instead saves it in |
| <filename>data/mailer.testfile</filename> for later review. |
| "none" disables email sending entirely. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| shadowdb |
| </term> |
| <listitem> |
| <para> |
| 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| shutdownhtml |
| </term> |
| <listitem> |
| <para> |
| If you need to shut down Bugzilla to perform administration, enter |
| some descriptive text (with embedded HTML codes, if you'd like) |
| into this box. Anyone who tries to use Bugzilla (including admins) |
| will receive a page displaying this text. Users can neither log in |
| nor log out while shutdownhtml is enabled. |
| </para> |
| |
| <note> |
| <para> |
| Although regular log-in capability is disabled while 'shutdownhtml' |
| is enabled, safeguards are in place to protect the unfortunate |
| admin who loses connection to Bugzilla. Should this happen to you, |
| go directly to the <filename>editparams.cgi</filename> (by typing |
| the URL in manually, if necessary). Doing this will prompt you to |
| log in, and your name/password will be accepted here (but nowhere |
| else). |
| </para> |
| </note> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| passwordmail |
| </term> |
| <listitem> |
| <para> |
| 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| movebugs |
| </term> |
| <listitem> |
| <para> |
| 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| useqacontact |
| </term> |
| <listitem> |
| <para> |
| This allows you to define an email address for each component, |
| in addition to that of the default assignee, who will be sent |
| carbon copies of incoming bugs. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| usestatuswhiteboard |
| </term> |
| <listitem> |
| <para> |
| 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| whinedays |
| </term> |
| <listitem> |
| <para> |
| 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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| commenton* |
| </term> |
| <listitem> |
| <para> |
| 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. |
| </para> |
| |
| <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> |
| </listitem> |
| </varlistentry> |
| |
| <varlistentry> |
| <term> |
| supportwatchers |
| </term> |
| <listitem> |
| <para> |
| Turning on this option allows users to ask to receive copies |
| of bug mail sent to another user. Watching a user with |
| different group permissions is not a way to 'get around' the |
| system; copied emails are still subject to the normal groupset |
| permissions of a bug, and <quote>watchers</quote> will only be |
| copied on emails from bugs they would normally be allowed to view. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| |
| <varlistentry> |
| <term> |
| noresolveonopenblockers |
| </term> |
| <listitem> |
| <para> |
| This option will prevent users from resolving bugs as FIXED if |
| they have unresolved dependencies. Only the FIXED resolution |
| is affected. Users will be still able to resolve bugs to |
| resolutions other than FIXED if they have unresolved dependent |
| bugs. |
| </para> |
| </listitem> |
| </varlistentry> |
| |
| </variablelist> |
| </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. |
| </para> |
| <para> |
| Users with disabled accounts will continue to receive |
| mail from Bugzilla; furthermore, they will not be able |
| to log in themselves to change their own preferences and |
| stop it. If you want an account (disabled or active) to |
| stop receiving mail, add the account name (one account |
| per line) to the file <filename>data/nomail</filename>. |
| </para> |
| <note> |
| <para> |
| Even users whose accounts have been disabled can still |
| submit bugs via the e-mail gateway, if one exists. |
| The e-mail gateway should <emphasis>not</emphasis> be |
| enabled for secure installations of Bugzilla. |
| </para> |
| </note> |
| <warning> |
| <para> |
| Don't disable all the administrator accounts! |
| </para> |
| </warning> |
| </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 default assignee and (if you turned it on in the parameters), |
| a QA Contact. The default assignee 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 Assignee, QA Contact, and Reporter |
| will get email when new bugs are created in this Component and when |
| these bugs change. Default Assignee 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 "Default Assignee" and "Default QA Contact" (if enabled.) |
| The Component and Description fields may contain HTML; |
| the "Default Assignee" 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 (-32768 to 32767) 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="flags-overview"> |
| <title>Flags</title> |
| |
| <para> |
| Flags are a way to attach a specific status to a bug or attachment, |
| either <quote>+</quote> or <quote>-</quote>. The meaning of these symbols depends on the text |
| the flag itself, but contextually they could mean pass/fail, |
| accept/reject, approved/denied, or even a simple yes/no. If your site |
| allows requestable flags, then users may set a flag to <quote>?</quote> as a |
| request to another user that they look at the bug/attachment, and set |
| the flag to its correct status. |
| </para> |
| |
| <section id="flags-simpleexample"> |
| <title>A Simple Example</title> |
| |
| <para> |
| A developer might want to ask their manager, |
| <quote>Should we fix this bug before we release version 2.0?</quote> |
| They might want to do this for a <emphasis>lot</emphasis> of bugs, |
| so it would be nice to streamline the process... |
| </para> |
| <para> |
| In Bugzilla, it would work this way: |
| <orderedlist> |
| <listitem> |
| <para> |
| The Bugzilla administrator creates a flag type called |
| <quote>blocking2.0</quote> that shows up on all bugs in |
| your product. |
| </para> |
| |
| <para> |
| It shows up on the <quote>Show Bug</quote> screen |
| as the text <quote>blocking2.0</quote> with a drop-down box next |
| to it. The drop-down box contains four values: an empty space, |
| <quote>?</quote>, <quote>-</quote>, and <quote>+</quote>. |
| </para> |
| </listitem> |
| <listitem> |
| <para>The developer sets the flag to <quote>?</quote>.</para> |
| </listitem> |
| <listitem> |
| <para> |
| The manager sees the <computeroutput>blocking2.0</computeroutput> |
| flag with a <quote>?</quote> value. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| If the manager thinks the feature should go into the product |
| before version 2.0 can be released, he sets the flag to |
| <quote>+</quote>. Otherwise, he sets it to <quote>-</quote>. |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| Now, every Bugzilla user who looks at the bug knows whether or |
| not the bug needs to be fixed before release of version 2.0. |
| </para> |
| </listitem> |
| </orderedlist> |
| </para> |
| |
| </section> |
| |
| <section id="flags-about"> |
| <title>About Flags</title> |
| |
| <section id="flag-values"> |
| <title>Values</title> |
| <para> |
| Flags can have three values: |
| <variablelist> |
| <varlistentry> |
| <term><computeroutput>?</computeroutput></term> |
| <listitem><simpara> |
| A user is requesting that a status be set. (Think of it as 'A question is being asked'.) |
| </simpara></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><computeroutput>-</computeroutput></term> |
| <listitem><simpara> |
| The status has been set negatively. (The question has been answered <quote>no</quote>.) |
| </simpara></listitem> |
| </varlistentry> |
| <varlistentry> |
| <term><computeroutput>+</computeroutput></term> |
| <listitem><simpara> |
| The status has been set positively. |
| (The question has been answered <quote>yes</quote>.) |
| </simpara></listitem> |
| </varlistentry> |
| </variablelist> |
| </para> |
| <para> |
| Actually, there's a fourth value a flag can have -- |
| <quote>unset</quote> -- which shows up as a blank space. This |
| just means that nobody has expressed an opinion (or asked |
| someone else to express an opinion) about this bug or attachment. |
| </para> |
| </section> |
| </section> |
| |
| <section id="flag-askto"> |
| <title>Using flag requests</title> |
| <para> |
| If a flag has been defined as 'requestable', |
| users are allowed to set the flag's status to <quote>?</quote>. |
| This status indicates that someone (aka <quote>the requester</quote> is asking |
| for someone else to set the flag to either <quote>+</quote> or <quote>-</quote>. |
| </para> |
| <para> |
| If a flag has been defined as 'specifically requestable', |
| a text box will appear next to the flag into which the requester may |
| enter a Bugzilla username. That named person (aka <quote>the requestee</quote>) |
| will receive an email notifying them of the request, and pointing them |
| to the bug/attachment in question. |
| </para> |
| <para> |
| If a flag has <emphasis>not</emphasis> been defined as 'specifically requestable', |
| then no such text-box will appear. A request to set this flag cannot be made of |
| any specific individual, but must be asked <quote>to the wind</quote>. |
| A requester may <quote>ask the wind</quote> on any flag simply by leaving the text-box blank. |
| </para> |
| </section> |
| |
| <section id="flag-types"> |
| <title>Two Types of Flags</title> |
| |
| <para> |
| Flags can go in two places: on an attachment, or on a bug. |
| </para> |
| |
| <section id="flag-type-attachment"> |
| <title>Attachment Flags</title> |
| |
| <para> |
| Attachment flags are used to ask a question about a specific |
| attachment on a bug. |
| </para> |
| <para> |
| Many Bugzilla installations use this to |
| request that one developer <quote>review</quote> another |
| developer's code before they check it in. They attach the code to |
| a bug report, and then set a flag on that attachment called |
| <quote>review</quote> to |
| <computeroutput>review?boss@domain.com</computeroutput>. |
| boss@domain.com is then notified by email that |
| he has to check out that attachment and approve it or deny it. |
| </para> |
| |
| <para> |
| For a Bugzilla user, attachment flags show up in two |
| places: |
| <orderedlist> |
| <listitem> |
| <para> |
| On the list of attachments in the <quote>Show Bug</quote> |
| screen, you can see the current state of any flags that |
| have been set to ?, +, or -. You can see who asked about |
| the flag (the requester), and who is being asked (the |
| requestee). |
| </para> |
| </listitem> |
| <listitem> |
| <para> |
| When you <quote>Edit</quote> an attachment, you can |
| see any settable flag, along with any flags that have |
| already been set. This <quote>Edit Attachment</quote> |
| screen is where you set flags to ?, -, +, or unset them. |
| </para> |
| </listitem> |
| </orderedlist> |
| </para> |
| |
| </section> |
| |
| <section id="flag-type-bug"> |
| <title>Bug Flags</title> |
| |
| <para> |
| Bug flags are used to set a status on the bug itself. You can |
| see Bug Flags in the <quote>Show Bug</quote> screen |
| (<filename>editbug.cgi</filename>). |
| </para> |
| <para> |
| Only users with the ability to edit the bug may |
| set flags on bugs. This includes the assignee, reporter, and |
| any user with the <computeroutput>editbugs</computeroutput> |
| permission. |
| </para> |
| </section> |
| |
| </section> |
| |
| <section id="flags-admin"> |
| <title>Administering Flags</title> |
| |
| <para> |
| If you have the <quote>editcomponents</quote> permission, you will |
| have <quote>Edit: ... | Flags | ...</quote> in your page footer. |
| Clicking on that link will bring you to the <quote>Administer |
| Flag Types</quote> page. Here, you can select whether you want |
| to create (or edit) a Bug flag, or an Attachment flag. |
| </para> |
| <para> |
| No matter which you choose, the interface is the same, so we'll |
| just go over it once. |
| </para> |
| |
| <section id="flags-create"> |
| <title>Creating a Flag</title> |
| |
| <para> |
| When you click on the <quote>Create a Flag Type for...</quote> |
| link, you will be presented with a form. Here is what the fields in |
| the form mean: |
| </para> |
| |
| <section id="flags-create-field-name"> |
| <title>Name</title> |
| <para> |
| This is the name of the flag. This will be displayed |
| to Bugzilla users who are looking at or setting the flag. |
| The name may consist of any valid Unicode character. |
| </para> |
| </section> |
| |
| <section id="flags-create-field-description"> |
| <title>Description</title> |
| <para> |
| This describes the flag in more detail. At present, this doesn't |
| show up anywhere helpful; ideally, it would be nice to have |
| it show up as a tooltip. This field |
| can be as long as you like, and can contain any character you want. |
| </para> |
| </section> |
| |
| <section id="flags-create-field-category"> |
| <title>Category</title> |
| |
| <para> |
| Default behaviour for a newly-created flag is to appear on |
| products and all components, which is why <quote>__Any__:__Any__</quote> |
| is already entered in the <quote>Inclusions</quote> box. |
| If this is not your desired behaviour, you must either set some |
| exclusions (for products on which you don't want the flag to appear), |
| or you must remove <quote>__Any__:__Any__</quote> from the Inclusions box |
| and define products/components specifically for this flag. |
| </para> |
| |
| <para> |
| To create an Inclusion, select a Product from the top drop-down box. |
| You may also select a specific component from the bottom drop-down box. |
| (Setting <quote>__Any__</quote> for Product translates to, |
| <quote>all the products in this Bugzilla</quote>. |
| Selecting <quote>__Any__</quote> in the Component field means |
| <quote>all components in the selected product.</quote>) |
| Selections made, press <quote>Include</quote>, and your |
| Product/Component pairing will show up in the <quote>Inclusions</quote> box on the right. |
| </para> |
| |
| <para> |
| To create an Exclusion, the process is the same; select a Product from the |
| top drop-down box, select a specific component if you want one, and press |
| <quote>Exclude</quote>. The Product/Component pairing will show up in the |
| <quote>Exclusions</quote> box on the right. |
| </para> |
| |
| <para> |
| This flag <emphasis>will</emphasis> and <emphasis>can</emphasis> be set for any |
| products/components that appearing in the <quote>Inclusions</quote> box |
| (or which fall under the appropriate <quote>__Any__</quote>). |
| This flag <emphasis>will not</emphasis> appear (and therefore cannot be set) on |
| any products appearing in the <quote>Exclusions</quote> box. |
| <emphasis> IMPORTANT: Exclusions override inclusions.</emphasis> |
| </para> |
| |
| <para> |
| You may select a Product without selecting a specific Component, |
| but it is illegal to select a Component without a Product, or to select a |
| Component that does not belong to the named Product. Doing so as of |
| this writing (2.18rc3) will raise an error... even if all your products |
| have a component by that name. |
| </para> |
| |
| <para><emphasis>Example:</emphasis> Let's say you have a product called |
| <quote>Jet Plane</quote> that has thousands of components. You want |
| to be able to ask if a problem should be fixed in the next model of |
| plane you release. We'll call the flag <quote>fixInNext</quote>. |
| But, there's one component in <quote>Jet Plane,</quote> |
| called <quote>Pilot.</quote> It doesn't make sense to release a |
| new pilot, so you don't want to have the flag show up in that component. |
| So, you include <quote>Jet Plane:__Any__</quote> and you exclude |
| <quote>Jet Plane:Pilot</quote>. |
| </para> |
| </section> |
| |
| <section id="flags-create-field-sortkey"> |
| <title>Sort Key</title> |
| <para> |
| Flags normally show up in alphabetical order. If you want them to |
| show up in a different order, you can use this key set the order on each flag. |
| Flags with a lower sort key will appear before flags with a higher |
| sort key. Flags that have the same sort key will be sorted alphabetically, |
| but they will still be after flags with a lower sort key, and before flags |
| with a higher sort key. |
| </para> |
| <para> |
| <emphasis>Example:</emphasis> I have AFlag (Sort Key 100), BFlag (Sort Key 10), |
| CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in |
| the order: DFlag, BFlag, CFlag, AFlag. |
| </para> |
| </section> |
| |
| <section id="flags-create-field-active"> |
| <title>Active</title> |
| <para> |
| Sometimes, you might want to keep old flag information in the |
| Bugzilla database, but stop users from setting any new flags of this type. |
| To do this, uncheck <quote>active</quote>. Deactivated |
| flags will still show up in the UI if they are ?, +, or -, but they |
| may only be cleared (unset), and cannot be changed to a new value. |
| Once a deactivated flag is cleared, it will completely disappear from a |
| bug/attachment, and cannot be set again. |
| </para> |
| </section> |
| |
| <section id="flags-create-field-requestable"> |
| <title>Requestable</title> |
| <para> |
| New flags are, by default, <quote>requestable</quote>, meaning that they |
| offer users the <quote>?</quote> option, as well as <quote>+</quote> |
| and <quote>-</quote>. |
| To remove the ? option, uncheck <quote>requestable</quote>. |
| </para> |
| </section> |
| |
| <section id="flags-create-field-cclist"> |
| <title>CC List</title> |
| |
| <para> |
| If you want certain users to be notified every time this flag is |
| set to ?, -, +, or unset, add them here. This is a comma-separated |
| list of email addresses that need not be restricted to Bugzilla usernames.. |
| </para> |
| </section> |
| |
| <section id="flags-create-field-specific"> |
| <title>Specifically Requestable</title> |
| <para> |
| By default this box is checked for new flags, meaning that users may make |
| flag requests of specific individuals. Unchecking this box will remove the |
| text box next to a flag; if it is still requestable, then requests may |
| only be made <quote>to the wind.</quote> Removing this after specific |
| requests have been made will not remove those requests; that data will |
| stay in the database (though it will no longer appear to the user). |
| </para> |
| </section> |
| |
| <section id="flags-create-field-multiplicable"> |
| <title>Multiplicable</title> |
| <para> |
| Any flag with <quote>Multiplicable</quote> set (default for new flags is 'on') |
| may be set more than once. After being set once, an unset flag |
| of the same type will appear below it with <quote>addl.</quote> (short for |
| <quote>additional</quote>) before the name. There is no limit to the number of |
| times a Multiplicable flags may be set on the same bug/attachment. |
| </para> |
| </section> |
| |
| </section> <!-- flags-create --> |
| |
| <section id="flags-delete"> |
| <title>Deleting a Flag</title> |
| |
| <para> |
| When you are at the <quote>Administer Flag Types</quote> screen, |
| you will be presented with a list of Bug flags and a list of Attachment |
| Flags. |
| </para> |
| <para> |
| To delete a flag, click on the <quote>Delete</quote> link next to |
| the flag description. |
| </para> |
| <warning> |
| <para> |
| Once you delete a flag, it is <emphasis>gone</emphasis> from |
| your Bugzilla. All the data for that flag will be deleted. |
| Everywhere that flag was set, it will disappear, |
| and you cannot get that data back. If you want to keep flag data, |
| but don't want anybody to set any new flags or change current flags, |
| unset <quote>active</quote> in the flag Edit form. |
| </para> |
| </warning> |
| </section> |
| |
| <section id="flags-edit"> |
| <title>Editing a Flag</title> |
| <para> |
| To edit a flag's properties, just click on the <quote>Edit</quote> |
| link next to the flag's description. That will take you to the same |
| form described in the <quote>Creating a Flag</quote> section. |
| </para> |
| </section> |
| |
| </section> <!-- flags-admin --> |
| |
| <!-- XXX We should add a "Uses of Flags" section, here, with examples. --> |
| |
| </section> <!-- flags --> |
| |
| <section id="voting"> |
| <title>Voting</title> |
| |
| <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="quips"> |
| <title>Quips</title> |
| |
| <para> |
| Quips are small text messages that can be configured to appear |
| next to search results. A Bugzilla installation can have its own specific |
| quips. Whenever a quip needs to be displayed, a random selection |
| is made from the pool of already existing quips. |
| </para> |
| |
| <para> |
| Quips are controlled by the <emphasis>enablequips</emphasis> parameter. |
| It has several possible values: on, approved, frozen or off. |
| In order to enable quips approval you need to set this parameter |
| to "approved". In this way, users are free to submit quips for |
| addition but an administrator must explicitly approve them before |
| they are actually used. |
| </para> |
| |
| <para> |
| In order to see the user interface for the quips, it is enough to click |
| on a quip when it is displayed together with the search results. Or |
| it can be seen directly in the browser by visiting the quips.cgi URL |
| (prefixed with the usual web location of the Bugzilla installation). |
| Once the quip interface is displayed, it is enough to click the |
| "view and edit the whole quip list" in order to see the administration |
| page. A page with all the quips available in the database will |
| be displayed. |
| </para> |
| |
| <para> |
| Next to each tip there is a checkbox, under the |
| "Approved" column. Quips who have this checkbox checked are |
| already approved and will appear next to the search results. |
| The ones that have it unchecked are still preserved in the |
| database but they will not appear on search results pages. |
| User submitted quips have initially the checkbox unchecked. |
| </para> |
| |
| <para> |
| Also, there is a delete link next to each quip, |
| which can be used in order to permanently delete a quip. |
| </para> |
| </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> |
| |
| <para> |
| If the makeproductgroups param is on, a new group will be automatically |
| created for every new product. It is primarily available for backward |
| compatibility with older sites. |
| </para> |
| <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> |
| <note> |
| <para> |
| By default, bugs can also be seen by the Assignee, the Reporter, and |
| by everyone on the CC List, regardless of whether or not the bug would |
| typically be viewable by them. Visibility to the Reporter and CC List can |
| be overridden (on a per-bug basis) by bringing up the bug, finding the |
| section that starts with <quote>Users in the roles selected below...</quote> |
| and un-checking the box next to either 'Reporter' or 'CC List' (or both). |
| </para> |
| </note> |
| <section> |
| <title>Creating Groups</title> |
| <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> |
| <para>Users whose email addresses match the regular expression |
| will automatically be members of the group as long as their |
| email addresses continue to match the regular expression.</para> |
| <note> |
| <para>This is a change from 2.16 where the regular expression |
| resulted in a user acquiring permanent membership in a group. |
| To remove a user from a group the user was in due to a regular |
| expression in version 2.16 or earlier, the user must be explicitly |
| removed from the group. This can easily be done by pressing |
| buttons named 'Remove Memberships' or 'Remove Memberships |
| included in regular expression' under the table.</para> |
| </note> |
| <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>If you plan to use this group to directly control |
| access to bugs, check the "use for bugs" box. Groups |
| not used for bugs are still useful because other groups |
| can include the group as a whole.</para> |
| </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> |
| |
| </section> |
| <section> |
| <title>Assigning Users to Groups</title> |
| <para>Users can become a member of a group in several ways.</para> |
| <orderedlist> |
| <listitem> |
| <para>The user can be explicitly placed in the group by editing |
| the user's own profile</para> |
| </listitem> |
| <listitem> |
| <para>The group can include another group of which the user is |
| a member.</para> |
| </listitem> |
| <listitem> |
| <para>The user's email address can match a regular expression |
| that the group specifies to automatically grant membership to |
| the group.</para> |
| </listitem> |
| </orderedlist> |
| </section> |
| |
| <section> |
| <title>Assigning Group Controls to Products</title> |
| <para> |
| On the product edit page, there is a page to edit the |
| <quote>Group Controls</quote> |
| for a product. This allows you to |
| configure how a group relates to the product. |
| Groups may be applicable, default, |
| and mandatory as well as used to control entry |
| or used to make bugs in the product |
| totally read-only unless the group restrictions are met. |
| </para> |
| |
| <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> |
| <para>These controls are often described in this order, so a |
| product that requires a user to be a member of group "foo" |
| to enter a bug and then requires that the bug stay restricted |
| to group "foo" at all times and that only members of group "foo" |
| can edit the bug even if they otherwise could see the bug would |
| have its controls summarized by...</para> |
| <programlisting> |
| foo: ENTRY, MANDATORY/MANDATORY, CANEDIT |
| </programlisting> |
| |
| </section> |
| <section> |
| <title>Common Applications of Group Controls</title> |
| <section> |
| <title>General User Access With Security Group</title> |
| <para>To permit any user to file bugs in each product (A, B, C...) |
| and to permit any user to submit those bugs into a security |
| group....</para> |
| <programlisting> |
| Product A... |
| security: SHOWN/SHOWN |
| Product B... |
| security: SHOWN/SHOWN |
| Product C... |
| security: SHOWN/SHOWN |
| </programlisting> |
| </section> |
| <section> |
| <title>General User Access With A Security Product</title> |
| <para>To permit any user to file bugs in a Security product |
| while keeping those bugs from becoming visible to anyone |
| outside the securityworkers group unless a member of the |
| securityworkers group removes that restriction....</para> |
| <programlisting> |
| Product Security... |
| securityworkers: DEFAULT/MANDATORY |
| </programlisting> |
| </section> |
| <section> |
| <title>Product Isolation With Common Group</title> |
| <para>To permit users of product A to access the bugs for |
| product A, users of product B to access product B, and support |
| staff to access both, 3 groups are needed</para> |
| <orderedlist> |
| <listitem> |
| <para>Support: Contains members of the support staff.</para> |
| </listitem> |
| <listitem> |
| <para>AccessA: Contains users of product A and the Support group.</para> |
| </listitem> |
| <listitem> |
| <para>AccessB: Contains users of product B and the Support group.</para> |
| </listitem> |
| </orderedlist> |
| <para>Once these 3 groups are defined, the products group controls |
| can be set to..</para> |
| <programlisting> |
| Product A... |
| AccessA: ENTRY, MANDATORY/MANDATORY |
| Product B... |
| AccessB: ENTRY, MANDATORY/MANDATORY |
| </programlisting> |
| <para>Optionally, the support group could be permitted to make |
| bugs inaccessible to the users and could be permitted to publish |
| bugs relevant to all users in a common product that is read-only |
| to anyone outside the support group. That configuration could |
| be...</para> |
| <programlisting> |
| Product A... |
| AccessA: ENTRY, MANDATORY/MANDATORY |
| Support: SHOWN/NA |
| Product B... |
| AccessB: ENTRY, MANDATORY/MANDATORY |
| Support: SHOWN/NA |
| Product Common... |
| Support: ENTRY, DEFAULT/MANDATORY, CANEDIT |
| </programlisting> |
| </section> |
| </section> |
| </section> |
| |
| <section id="upgrading"> |
| <title>Upgrading to New Releases</title> |
| |
| <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 local changes (if any) have been made |
| </para> |
| </listitem> |
| </itemizedlist> |
| |
| <section id="upgrading-version-defns"> |
| <title>Version Definitions</title> |
| |
| <para> |
| Bugzilla displays the version you are using at the top of most |
| pages you load. It will look something like '2.16.7' or '2.18rc3' |
| or '2.19.1+'. The first number in this series is the Major Version. |
| This does not change very often (that is to say, almost never); |
| Bugzilla was 1.x.x when it was first created, and went to 2.x.x |
| when it was re-written in perl in Sept 1998. If/When the major version |
| is changed to 3.x.x, it will signify a significant structural change |
| and will be accompanied by much fanfare and many instructions on |
| how to upgrade, including a revision to this page. :) |
| </para> |
| |
| <para> |
| The second number in the version is called the 'minor number', and |
| a release that changes the minor number is called a 'point release'. |
| An even number in this position (2.14, 2.16, 2.18, 2.20, etc.) |
| represents a stable version, while an odd number (2.17, 2.19, etc.) |
| represents a development version. In the past, stable point releases |
| were feature-based, coming when certain enhancements had been |
| completed, or the Bugzilla development team felt that enough |
| progress had been made overall. As of version 2.18, however, |
| Bugzilla has moved to a time-based release schedule; current plans |
| are to create a stable point release every 6 months or so after |
| 2.18 is deployed. |
| </para> |
| |
| <para> |
| The third number in the Bugzilla version represents a bugfix version. |
| Bugfix Revisions are normally released only to address security |
| vulnerabilities; in the future, it is likely that the Bugzilla |
| development team will back-port bugfixes in a new point release to |
| the old point release for a limited period. Once enough of these |
| bugfixes have accumulated (or a new security vulnerability is |
| identified and closed), a bugfix release will be made. As an |
| example, 2.16.6 was a bugfix release, and improved on 2.16.5. |
| </para> |
| |
| <note> |
| <para> |
| When reading version numbers, everything separated by a point ('.') |
| should be read as a single number. It is <emphasis>not</emphasis> |
| the same as decimal. 2.14 is newer than 2.8 because minor version |
| 14 is greater than minor version 8. 2.24.11 would be newer than |
| 2.24.9 (because bugfix 11 is greater than bugfix 9. This is |
| confusing to some people who aren't used to dealing with software. |
| </para> |
| </note> |
| </section> |
| |
| <section id="upgrading-methods"> |
| <title>Upgrading - Methods and Procedure</title> |
| <para> |
| There are three different ways 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> |
| Each of these options has its own pros and cons; the one that's |
| right for you depends on how long it has been since you last |
| installed, the degree to which you have customized your installation, |
| and/or your network configuration. (Some discussion of the various |
| methods of updating compared with degree and methods of local |
| customization can be found in <xref linkend="template-method"/>.) |
| </para> |
| |
| <para> |
| The larger the jump you are trying to make, the more difficult it |
| is going to be to upgrade if you have made local customizations. |
| Upgrading from 2.18 to 2.18.1 should be fairly painless even if |
| you are heavily customized, but going from 2.14 to 2.18 is going |
| to mean a fair bit of work re-writing your local changes to use |
| the new files, logic, templates, etc. If you have done no local |
| changes at all, however, then upgrading should be approximately |
| the same amount of work regardless of how long it has been since |
| your version was released. |
| </para> |
| |
| <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> |
| The examples in the following sections are written as though the |
| user were updating to version 2.18.1, but the procedures are the |
| same regardless of whether one is updating to a new point release |
| or simply trying to obtain a new bugfix release. Also, in the |
| examples the user's Bugzilla installation is found at |
| <filename>/var/www/html/bugzilla</filename>. If that is not the |
| same as the location of your Bugzilla installation, simply |
| substitute the proper paths where appropriate. |
| </para> |
| |
| <section id="upgrade-cvs"> |
| <title>Upgrading using CVS</title> |
| |
| <para> |
| Every release of Bugzilla, whether it is a point release or a bugfix, |
| is tagged in CVS. Also, every tarball that has been distributed since |
| version 2.12 has been created in such a way that it can be used with |
| CVS once it is unpacked. Doing so, however, requires that you are able |
| to access cvs-mirror.mozilla.org on port 2401, which may not be an |
| option or a possibility for some users, especially those behind a |
| highly restrictive firewall. |
| </para> |
| |
| <tip> |
| <para> |
| If you can, updating using CVS is probably the most painless |
| method, especially if you have a lot of local changes. |
| </para> |
| </tip> |
| |
| <para> |
| The following shows the sequence of commands needed to update a |
| Bugzilla installation via CVS, and a typical series of results. |
| </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: <emphasis>('anonymous', or just leave it blank)</emphasis> |
| bash$ <command>cvs -q update -r BUGZILLA-2_18_1 -dP</command> |
| P checksetup.pl |
| P collectstats.pl |
| P globals.pl |
| P docs/rel_notes.txt |
| P template/en/default/list/quips.html.tmpl |
| <emphasis>(etc.)</emphasis> |
| </programlisting> |
| |
| <caution> |
| <para> |
| If a line in the output from <command>cvs update</command> begins |
| with a <computeroutput>C</computeroutput>, then 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> |
| </section> |
| |
| <section 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 obtain the latest tarball from the <ulink |
| url="http://www.bugzilla.org/download/">Download Page</ulink> and |
| create a new Bugzilla installation from that. |
| </para> |
| |
| <para> |
| This sequence of commands shows how to get the tarball from the |
| command-line; it is also possible to download it from the site |
| directly in a web browser. If you go that route, save the file |
| to the <filename class="directory">/var/www/html</filename> |
| directory (or its equivalent, if you use something else) and |
| omit the first three lines of the example. |
| </para> |
| |
| <programlisting> |
| bash$ <command>cd /var/www/html</command> |
| bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.1.tar.gz</command> |
| <emphasis>(Output omitted)</emphasis> |
| bash$ <command>tar xzvf bugzilla-2.18.1.tar.gz</command> |
| bugzilla-2.18.1/ |
| bugzilla-2.18.1/.cvsignore |
| bugzilla-2.18.1/1x1.gif |
| <emphasis>(Output truncated)</emphasis> |
| bash$ <command>cd bugzilla-2.18.1</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.18.1 bugzilla</command> |
| </programlisting> |
| |
| <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. |
| </para> |
| </warning> |
| |
| <para> |
| This upgrade method will give you a clean install of Bugzilla with the |
| same version as the tarball. That's fine if you don't have any local |
| customizations that you want to maintain, but if you do then you will |
| need to reapply them by hand to the appropriate files. |
| </para> |
| |
| <para> |
| It's worth noting that since 2.12, the Bugzilla tarballs come |
| CVS-ready, so if you decide at a later date that you'd rather use |
| CVS as an upgrade method, your code will already be set up for it. |
| </para> |
| </section> |
| |
| <section id="upgrade-patches"> |
| <title>Upgrading using patches</title> |
| |
| <para> |
| If you are doing a bugfix upgrade -- that is, one where only the |
| last number of the revision changes, such as from 2.16.6 to 2.16.7 |
| -- then you have the option of obtaining and applying a patch file |
| from the <ulink |
| url="http://www.bugzilla.org/download/">Download Page</ulink>. |
| This file is made available by the <ulink |
| url="http://www.bugzilla.org/developers/profiles.html">Bugzilla |
| Development Team</ulink>, and is a collection of all the bug fixes |
| and security patches that have been made since the last bugfix |
| release. If you are planning to upgrade via patches, it is safer |
| to grab this developer-made patch file than to read the patch |
| notes and apply all (or even just some of) the patches oneself, |
| as sometimes patches on bugs get changed before they get checked in. |
| </para> |
| |
| <para> |
| As above, this example starts with obtaining the file via the |
| command line. If you have already downloaded it, you can omit the |
| first two commands. |
| </para> |
| |
| <programlisting> |
| bash$ <command>cd /var/www/html/bugzilla</command> |
| bash$ <command>wget ftp://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-2.18.0-to-2.18.1.diff.gz</command> |
| <emphasis>(Output omitted)</emphasis> |
| bash$ <command>gunzip bugzilla-2.18.0-to-2.18.1.diff.gz</command> |
| bash$ <command>patch -p1 < bugzilla-2.18.0-to-2.18.1.diff</command> |
| patching file checksetup.pl |
| patching file collectstats.pl |
| patching file globals.pl |
| <emphasis>(etc.)</emphasis> |
| </programlisting> |
| |
| <warning> |
| <para> |
| Be aware that upgrading from a patch file does not change the |
| entries in your <filename class="directory">CVS</filename> directory. |
| This could make it more difficult to upgrade using CVS |
| (<xref linkend="upgrade-cvs"/>) in the future. |
| </para> |
| </warning> |
| |
| </section> |
| </section> |
| |
| <section id="upgrading-completion"> |
| <title>Completing Your Upgrade</title> |
| |
| <para> |
| Regardless of which upgrade method you choose, you will need to |
| run <command>./checksetup.pl</command> before your Bugzilla |
| upgrade will be complete. |
| </para> |
| |
| <programlisting> |
| bash$ <command>cd bugzilla</command> |
| bash$ <command>./checksetup.pl</command> |
| </programlisting> |
| |
| <warning> |
| <para> |
| The period at the beginning of the command |
| <command>./checksetup.pl</command> is important and can not |
| be omitted. |
| </para> |
| </warning> |
| |
| <para> |
| If you have done a lot of local modifications, it wouldn't hurt |
| to run the Bugzilla Testing suite. This is not a required step, |
| but it isn't going to hurt anything, and might help point out |
| some areas that could be improved. (More information on the |
| test suite can be had by following this link to the appropriate |
| section in the <ulink |
| url="http://www.bugzilla.org/docs/developer.html#testsuite">Developers' |
| Guide</ulink>.) |
| </para> |
| |
| </section> |
| </section> |
| </chapter> |
| |
| <!-- Keep this comment at the end of the file |
| Local variables: |
| mode: sgml |
| 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-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: |
| --> |
| |
