<step>
<para>
- <command>makeproductgroups</command>:
- This dictates whether or not to automatically create groups
- when new products are created.
- </para>
+ <command>usebuggroups</command>:
+ This dictates whether or not to implement group-based security for
+ Bugzilla. If set, Bugzilla bugs can have an associated 'group',
+ defining which users are allowed to see and edit the
+ bug.</para>
+
+ <para>Set "usebuggroups" to "on"
+ <emphasis>only</emphasis>
+ if you may wish to restrict access to particular bugs to certain
+ groups of users. I suggest leaving
+ this parameter <emphasis>off</emphasis>
+ while initially testing your Bugzilla.</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>
+ <command>usebuggroupsentry</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 places all newly-created bugs in the
+ group for their product immediately.</para>
</step>
<step>
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>
+ complete. 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.
high-traffic Bugzilla databases.</para>
<para>
- As a guide, on reasonably old hardware, mozilla.org began needing
+ As a guide, 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>
+ shadow bug database.
+ Set "shadowdb" to e.g. "bug_shadowdb" if you will be running a
+ *very* large installation of Bugzilla.
+ <note>
+ <para>Enabling "shadowdb" can adversely affect the stability of
+ your installation of Bugzilla. You should regularly check that your
+ database is in sync. It is often advisable to force a shadow
+ database sync nightly via
+ <quote>cron</quote>.
+ </para>
+ </note>
+ </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>
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>:
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>If you wish to add more administrative users, you must use the
+ MySQL interface. Run "mysql" from the command line, and use these
+ commands:
+ <simplelist>
+ <member>
+ <prompt>mysql></prompt>
+ <command>use bugs;</command>
+ </member>
+
+ <member>
+ <prompt>mysql></prompt>
+
+ <command>
+ update profiles set groupset=0x7ffffffffffffff where login_name =
+ "(user's login name)";
+ </command>
+ </member>
+ </simplelist>
</para>
+
+ <para>Yes, that is
+ <emphasis>fourteen</emphasis>
+
+ <quote>f</quote>
+
+ 's. A whole lot of f-ing going on if you want to create a new
+ administator.</para>
</tip>
</section>
they attempt to perform these actions, and should explain
why the account was disabled.
<warning>
- <para>Don't disable all the administrator accounts!</para>
+ <para>Don't disable the administrator account!</para>
</warning>
<note>
</section>
</section>
- <section id="products">
- <title>Products</title>
+ <section id="programadmin">
+ <title>Product, Component, Milestone, and Version Administration</title>
- <para>
- <glossterm linkend="gloss-product" baseform="product">
- Products</glossterm>
+ <section id="products">
+ <title>Products</title>
- 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>
+ <glossterm linkend="gloss-product" baseform="product">
+ Products</glossterm>
- <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>
+ 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>To create a new product:</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>
- <orderedlist>
- <listitem>
- <para>Select "products" from the footer</para>
+ <para>To create a new product:</para>
- </listitem>
+ <orderedlist>
+ <listitem>
+ <para>Select "products" from the footer</para>
- <listitem>
- <para>Select the "Add" link in the bottom right</para>
- </listitem>
+ </listitem>
- <listitem>
- <para>Enter the name of the product and a description. The
- Description field may contain HTML.</para>
- </listitem>
- </orderedlist>
+ <listitem>
+ <para>Select the "Add" link in the bottom right</para>
+ </listitem>
- <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>
+ <listitem>
+ <para>Enter the name of the product and a description. The
+ Description field may contain HTML.</para>
+ </listitem>
+ </orderedlist>
- <section id="components">
- <title>Components</title>
+ <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>
- <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>
+ <section id="components">
+ <title>Components</title>
- <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>
+ <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>
+ <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>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>
+ <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>
+ <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>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 most recent version with
+ the bug.
+ </para>
- <para>To create and edit Versions:</para>
+
<para>To create and edit Versions:</para>
- <orderedlist>
- <listitem>
- <para>From the "Edit product" screen, select "Edit Versions"</para>
- </listitem>
+ <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>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>
+ <listitem>
+
<para>Enter the name of the Version. This field takes text only.
+ Then click the "Add" button.</para>
+ </listitem>
- </orderedlist>
- </section>
+ </orderedlist>
+ </section>
- <section id="milestones">
- <title>Milestones</title>
+ <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>
+
<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>
+ <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>
+
<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>
+ <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>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>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>
+ <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>
+
+ <tip>
+ <para>If you want your milestone document to be restricted so
+ that it can only be viewed by people in a particular Bugzilla
+ group, the best way is to attach the document to a bug in that
+ group, and make the URL the URL of that attachment.</para>
+ </tip>
+ </listitem>
+ </orderedlist>
+ </section>
</section>
<section id="voting">
<listitem>
<para><emphasis>Maximum Votes a person can put on a single
- bug</emphasis>:
+ 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
</orderedlist>
</section>
- <section id="quips">
- <title>Quips</title>
+ <section id="groups">
+ <title>Groups and Group Security</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>Groups allow the administrator
+ to isolate bugs or products that should only be seen by certain people.
+ There are two types of group - Generic Groups, and Product-Based Groups.
</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.
+ Product-Based Groups are matched with products, and allow you to restrict
+ access to bugs on a per-product basis. They are enabled using the
+ usebuggroups Param. Turning on the usebuggroupsentry
+ Param will mean bugs automatically get added to their product group when
+ filed.
</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.
+ Generic Groups have no special relationship to products;
+ you create them, and put bugs in them
+ as required. One example of the use of Generic Groups
+ is Mozilla's "Security" group,
+ into which security-sensitive bugs are placed until fixed. Only the
+ Mozilla Security Team are members of this group.
</para>
+
+ <para>To create Generic Groups:</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>
+ <orderedlist>
+ <listitem>
+ <para>Select the "groups"
+ link in the footer.</para>
+ </listitem>
- <section id="groups">
- <title>Groups and Group Security</title>
+ <listitem>
+ <para>Take a moment to understand the instructions on the "Edit
+ Groups" screen, then select the "Add Group" link.</para>
+ </listitem>
- <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>
+ <listitem>
+ <para>Fill out the "New Name", "New Description", and
+ "New User RegExp" fields. "New User RegExp" allows you to automatically
+ place all users who fulfill the Regular Expression into the new group.
+ When you have finished, click "Add".</para>
+ </listitem>
+ </orderedlist>
+
+ <para>To use Product-Based Groups:</para>
+
+ <orderedlist>
+ <listitem>
+ <para>Turn on "usebuggroups" and "usebuggroupsentry" in the "Edit
+ Parameters" screen.</para>
+
+ <warning>
+ <para>XXX is this still true?
+ "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>In future, when you create a Product, a matching group will be
+ automatically created. If you need to add a Product Group to
+ a Product which was created before you turned on usebuggroups,
+ then simply create a new group, as outlined above, with the
+ same name as the Product.</para>
+ </listitem>
+ </orderedlist>
+
+ <warning>
+ <para>Bugzilla currently has a limit of 64 groups per installation. If
+ you have more than about 50 products, you should consider
+ running multiple Bugzillas. Ask in the newsgroup for other
+ suggestions for working around this restriction.</para>
+ </warning>
- <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.
+ reason, to see that bug.
</para>
- <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.</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 resticted
- 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>
+
+ <section id="security">
+ <title>Bugzilla Security</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>
+ <para>Poorly-configured MySQL and Bugzilla 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>
</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>
+ <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>
- <itemizedlist>
+ <para>To secure your installation:
+
+ <orderedlist>
<listitem>
- <para>If the new version is a revision or a new point release</para>
+ <para>Ensure you are running at least MysQL version 3.22.32 or newer.
+ Earlier versions had notable security holes and (from a security
+ point of view) poor default configuration choices.</para>
</listitem>
+
<listitem>
- <para>How many, if any, local changes have been made</para>
- </listitem>
- </itemizedlist>
+ <para>
+ <emphasis>There is no substitute for understanding the tools on your
+ system!</emphasis>
- <para>There are also three different methods to upgrade your installation.
- </para>
+ Read
+ <ulink url="http://www.mysql.com/doc/P/r/Privilege_system.html">
+ The MySQL Privilege System</ulink>
+ until you can recite it from memory!</para>
+ </listitem>
- <orderedlist>
<listitem>
- <para>Using CVS (<xref linkend="upgrade-cvs"/>)</para>
+ <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>Downloading a new tarball (<xref linkend="upgrade-tarball"/>)</para>
+ <para>Do not run Apache as
+ <quote>nobody</quote>
+
+ . 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.
+ <note>
+ <para>
+ <quote>nobody</quote>
+
+ is a real user on UNIX systems. Having a process run as user id
+ <quote>nobody</quote>
+
+ is absolutely no protection against system crackers versus using
+ any other user account. As a general security measure, I recommend
+ you create unique user ID's for each daemon running on your system
+ and, if possible, use "chroot" to jail that process away from the
+ rest of your system.</para>
+ </note>
+ </para>
</listitem>
+
<listitem>
- <para>Applying the relevant patches (<xref linkend="upgrade-patches"/>)</para>
- </listitem>
- </orderedlist>
+ <para>Ensure you have adequate access controls for the
+ $BUGZILLA_HOME/data/ directory, as well as the
+ $BUGZILLA_HOME/localconfig file.
+ The localconfig file stores your "bugs" database account password.
+ In addition, some
+ files under $BUGZILLA_HOME/data/ store sensitive information.
+ </para>
- <para>Which options are available to you may depend on how large a jump
- you are making and/or your network configuration.
- </para>
+ <para>Bugzilla provides default .htaccess files to protect the most
+ common Apache installations. However, you should verify these are
+ adequate according to the site-wide security policy of your web
+ server, and ensure that the .htaccess files are allowed to
+ "override" default permissions set in your Apache configuration
+ files. Covering Apache security is beyond the scope of this Guide;
+ please consult the Apache documentation for details.</para>
+
+ <para>If you are using a web server that does not support the
+ .htaccess control method,
+ <emphasis>you are at risk!</emphasis>
+
+ After installing, check to see if you can view the file
+ "localconfig" in your web browser (e.g.:
+ <ulink url="http://bugzilla.mozilla.org/localconfig">
+ http://bugzilla.mozilla.org/localconfig</ulink>
+
+ ). If you can read the contents of this file, your web server has
+ not secured your bugzilla directory properly and you must fix this
+ problem before deploying Bugzilla. If, however, it gives you a
+ "Forbidden" error, then it probably respects the .htaccess
+ conventions and you are good to go.</para>
+
+ <para>When you run checksetup.pl, the script will attempt to modify
+ various permissions on files which Bugzilla uses. If you do not have
+ a webservergroup set in the localconfig file, then Bugzilla will have
+ to make certain files world readable and/or writable.
+ <emphasis>THIS IS INSECURE!</emphasis>
+
+ . This means that anyone who can get access to your system can do
+ whatever they want to your Bugzilla installation.</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.6 was released, it was a revision to 2.16.5.
- </para>
+ <note>
+ <para>This also means that if your webserver runs all cgi scripts
+ as the same user/group, anyone on the system who can run cgi
+ scripts will be able to take control of your Bugzilla
+ installation.</para>
+ </note>
- <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.18.0 is a newer point
- release than 2.16.5.
- </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>
- <para>The examples in this section are written as if you were updating
- to version 2.18.1. 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>
+ 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/ directory.</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>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.
+ </listitem>
+ </orderedlist>
</para>
+ </section>
- <example id="upgrade-cvs">
- <title>Upgrading using CVS</title>
+ <section id="cust-templates">
+ <title>Template Customisation</title>
+
+ <para>
+ One of the large changes for 2.16 was the templatisation of the
+ entire user-facing UI, using the
+ <ulink url="http://www.template-toolkit.org">Template Toolkit</ulink>.
+ Administrators can now configure the look and feel of Bugzilla without
+ having to edit Perl files or face the nightmare of massive merge
+ conflicts when they upgrade to a newer version in the future.
+ </para>
+
+ <para>
+ Templatisation also makes localised versions of Bugzilla possible,
+ for the first time. In the future, a Bugzilla installation may
+ have templates installed for multiple localisations, and select
+ which ones to use based on the user's browser language setting.
+ </para>
+
+ <section>
+ <title>What to Edit</title>
+ <para>
+ There are two different ways of editing of Bugzilla's templates,
+ and which you use depends mainly on how you upgrade Bugzilla. The
+ template directory structure is that there's a top level directory,
+ <filename>template</filename>, which contains a directory for
+ each installed localisation. The default English templates are
+ therefore in <filename>en</filename>. Underneath that, there
+ is the <filename>default</filename> directory and optionally the
+ <filename>custom</filename> directory. The <filename>default</filename>
+ directory contains all the templates shipped with Bugzilla, whereas
+ the <filename>custom</filename> directory does not exist at first and
+ must be created if you want to use it.
+ </para>
- <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.
+ <para>
+ The first method of making customisations is to directly edit the
+ templates in <filename>template/en/default</filename>. This is
+ probably the best method for small changes if you are going to use
+ the CVS method of upgrading, because if you then execute a
+ <command>cvs update</command>, any template fixes will get
+ automagically merged into your modified versions.
+ </para>
- <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>
+ If you use this method, your installation will break if CVS conflicts
+ occur.
</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_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
- </programlisting>
+ <para>
+ The other method is to copy the templates into a mirrored directory
+ structure under <filename>template/en/custom</filename>. The templates
+ in this directory automatically override those in default.
+ This is the technique you
+ need to use if you use the overwriting method of upgrade, because
+ otherwise your changes will be lost. This method is also better if
+ you are using the CVS method of upgrading and are going to make major
+ changes, because it is guaranteed that the contents of this directory
+ will not be touched during an upgrade, and you can then decide whether
+ to continue using your own templates, or make the effort to merge your
+ changes into the new versions by hand.
+ </para>
<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>
+ If you use this method, your installation may break if incompatible
+ changes are made to the template interface. If such changes are made
+ they will be documented in the release notes, provided you are using a
+ stable release of Bugzilla. If you use using unstable code, you will
+ need to deal with this one yourself, although if possible the changes
+ will be mentioned before they occur in the deprecations section of the
+ previous stable release's release notes.
+ </para>
- <note>
- <para>You also need to run <command>./checksetup.pl</command>
- before your Bugzilla upgrade will be complete.
- </para>
- </note>
+ <note>
+ <para>
+ Don't directly edit the compiled templates in
+ <filename class="directory">data/template/*</filename> - your
+ changes will be lost when Template Toolkit recompiles them.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>How To Edit Templates</title>
+
+ <para>
+ The syntax of the Template Toolkit language is beyond the scope of
+ this guide. It's reasonably easy to pick up by looking at the current
+ templates; or, you can read the manual, available on the
+ <ulink url="http://www.template-toolkit.org">Template Toolkit home
+ page</ulink>. However, you should particularly remember (for security
+ reasons) to always HTML filter things which come from the database or
+ user input, to prevent cross-site scripting attacks.
+ </para>
+
+ <para>
+ However, one thing you should take particular care about is the need
+ to properly HTML filter data that has been passed into the template.
+ This means that if the data can possibly contain special HTML characters
+ such as <, and the data was not intended to be HTML, they need to be
+ converted to entity form, ie &lt;. You use the 'html' filter in the
+ Template Toolkit to do this. If you fail to do this, you may open up
+ your installation to cross-site scripting attacks.
</para>
- </example>
- <example id="upgrade-tarball">
- <title>Upgrading using the tarball</title>
+ <para>
+ Also note that Bugzilla adds a few filters of its own, that are not
+ in standard Template Toolkit. In particular, the 'url_quote' filter
+ can convert characters that are illegal or have special meaning in URLs,
+ such as &, to the encoded form, ie %26. This actually encodes most
+ characters (but not the common ones such as letters and numbers and so
+ on), including the HTML-special characters, so there's never a need to
+ HTML filter afterwards.
+ </para>
+
+ <para>
+ Editing templates is a good way of doing a "poor man's custom fields".
+ For example, if you don't use the Status Whiteboard, but want to have
+ a free-form text entry box for "Build Identifier", then you can just
+ edit the templates to change the field labels. It's still be called
+ status_whiteboard internally, but your users don't need to know that.
+ </para>
+
+ <note>
+ <para>
+ If you are making template changes that you intend on submitting back
+ for inclusion in standard Bugzilla, you should read the relevant
+ sections of the
+ <ulink url="http://www.bugzilla.org/developerguide.html">Developers'
+ Guide</ulink>.
+ </para>
+ </note>
+ </section>
+
+
+ <section>
+ <title>Template Formats</title>
+
+ <para>
+ Some CGIs have the ability to use more than one template. For
+ example, buglist.cgi can output bug lists as RDF or two
+ different forms of HTML (complex and simple). (Try this out
+ by appending <filename>&format=simple</filename> to a buglist.cgi
+ URL on your Bugzilla installation.) This
+ mechanism, called template 'formats', is extensible.
+ </para>
+
+ <para>
+ To see if a CGI supports multiple output formats, grep the
+ CGI for "ValidateOutputFormat". If it's not present, adding
+ multiple format support isn't too hard - see how it's done in
+ other CGIs.
+ </para>
+
+ <para>
+ To make a new format template for a CGI which supports this,
+ open a current template for
+ that CGI and take note of the INTERFACE comment (if present.) This
+ comment defines what variables are passed into this template. If
+ there isn't one, I'm afraid you'll have to read the template and
+ the code to find out what information you get.
+ </para>
+
+ <para>
+ Write your template in whatever markup or text style is appropriate.
+ </para>
+
+ <para>
+ You now need to decide what content type you want your template
+ served as. Open up the <filename>localconfig</filename> file and find the
+ <filename>$contenttypes</filename>
+ variable. If your content type is not there, add it. Remember
+ the three- or four-letter tag assigned to you content type.
+ This tag will be part of the template filename.
+ </para>
+
+ <para>
+ Save the template as <filename><stubname>-<formatname>.<contenttypetag>.tmpl</filename>.
+ Try out the template by calling the CGI as
+ <filename><cginame>.cgi?format=<formatname></filename> .
+ </para>
+ </section>
+
+
+ <section>
+ <title>Particular Templates</title>
+
+ <para>
+ There are a few templates you may be particularly interested in
+ customising for your installation.
+ </para>
+
+ <para>
+ <command>index.html.tmpl</command>:
+ This is the Bugzilla front page.
+ </para>
- <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>
+ <command>global/header.html.tmpl</command>:
+ This defines the header that goes on all Bugzilla pages.
+ The header includes the banner, which is what appears to users
+ and is probably what you want to edit instead. However the
+ header also includes the HTML HEAD section, so you could for
+ example add a stylesheet or META tag by editing the header.
</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>
-bash$ <command>cd bugzilla</command>
-bash$ <command>./checksetup.pl</command>
-<emphasis>Output omitted</emphasis>
- </programlisting>
+ <para>
+ <command>global/banner.html.tmpl</command>:
+ This contains the "banner", the part of the header that appears
+ at the top of all Bugzilla pages. The default banner is reasonably
+ barren, so you'll probably want to customise this to give your
+ installation a distinctive look and feel. It is recommended you
+ preserve the Bugzilla version number in some form so the version
+ you are running can be determined, and users know what docs to read.
+ </para>
<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>
+ <command>global/footer.html.tmpl</command>:
+ This defines the footer that goes on all Bugzilla pages. Editing
+ this is another way to quickly get a distinctive look and feel for
+ your Bugzilla installation.
+ </para>
- <note>
- <para>You will now have to reapply any changes you have made to your
- local installation manually.
- </para>
- </note>
+ <para>
+ <command>bug/create/user-message.html.tmpl</command>:
+ This is a message that appears near the top of the bug reporting page.
+ By modifying this, you can tell your users how they should report
+ bugs.
+ </para>
+
+ <para>
+ <command>bug/create/create.html.tmpl</command> and
+ <command>bug/create/comment.txt.tmpl</command>:
+ You may wish to get bug submitters to give certain bits of structured
+ information, each in a separate input widget, for which there is not a
+ field in the database. The bug entry system has been designed in an
+ extensible fashion to enable you to define arbitrary fields and widgets,
+ and have their values appear formatted in the initial
+ Description, rather than in database fields. An example of this
+ is the mozilla.org
+ <ulink url="http://bugzilla.mozilla.org/enter_bug.cgi?format=guided">guided
+ bug submission form</ulink>.
</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>
+ To make this work, create a custom template for
+ <filename>enter_bug.cgi</filename> (the default template, on which you
+ could base it, is <filename>create.html.tmpl</filename>),
+ and either call it <filename>create.html.tmpl</filename> or use a format and
+ call it <filename>create-<formatname>.html.tmpl</filename>.
+ Put it in the <filename class="directory">custom/bug/create</filename>
+ directory. In it, add widgets for each piece of information you'd like
+ collected - such as a build number, or set of steps to reproduce.
</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
- </programlisting>
+ <para>
+ Then, create a template like
+ <filename>custom/bug/create/comment.txt.tmpl</filename>, also named
+ after your format if you are using one, which
+ references the form fields you have created. When a bug report is
+ submitted, the initial comment attached to the bug report will be
+ formatted according to the layout of this template.
+ </para>
<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>
+ For example, if your enter_bug template had a field
+ <programlisting><input type="text" name="buildid" size="30"></programlisting>
+ and then your comment.txt.tmpl had
+ <programlisting>BuildID: [% form.buildid %]</programlisting>
+ then
+ <programlisting>BuildID: 20020303</programlisting>
+ would appear in the initial checkin comment.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="cust-change-permissions">
+ <title>Change Permission Customisation</title>
+
+ <warning>
+ <para>
+ This feature should be considered experimental; the Bugzilla code you
+ will be changing is not stable, and could change or move between
+ versions. Be aware that if you make modifications to it, you may have
+ to re-make them or port them if Bugzilla changes internally between
+ versions.
</para>
- </example>
+ </warning>
+
+ <para>
+ Companies often have rules about which employees, or classes of employees,
+ are allowed to change certain things in the bug system. For example,
+ only the bug's designated QA Contact may be allowed to VERIFY the bug.
+ Bugzilla has been
+ designed to make it easy for you to write your own custom rules to define
+ who is allowed to make what sorts of value transition.
+ </para>
+
+ <para>
+ For maximum flexibility, customising this means editing Bugzilla's Perl
+ code. This gives the administrator complete control over exactly who is
+ allowed to do what. The relevant function is called
+ <filename>CheckCanChangeField()</filename>,
+ and is found in <filename>process_bug.cgi</filename> in your
+ Bugzilla directory. If you open that file and grep for
+ "sub CheckCanChangeField", you'll find it.
+ </para>
+
+ <para>
+ This function has been carefully commented to allow you to see exactly
+ how it works, and give you an idea of how to make changes to it. Certain
+ marked sections should not be changed - these are the "plumbing" which
+ makes the rest of the function work. In between those sections, you'll
+ find snippets of code like:
+ <programlisting> # Allow the owner to change anything.
+ if ($ownerid eq $whoid) {
+ return 1;
+ }</programlisting>
+ It's fairly obvious what this piece of code does.
+ </para>
+
+ <para>
+ So, how does one go about changing this function? Well, simple changes
+ can be made just be removing pieces - for example, if you wanted to
+ prevent any user adding a comment to a bug, just remove the lines marked
+ "Allow anyone to change comments." And if you want the reporter to have
+ no special rights on bugs they have filed, just remove the entire section
+ which refers to him.
+ </para>
+
+ <para>
+ More complex customisations are not much harder. Basically, you add
+ a check in the right place in the function, i.e. after all the variables
+ you are using have been set up. So, don't look at $ownerid before
+ $ownerid has been obtained from the database. You can either add a
+ positive check, which returns 1 (allow) if certain conditions are true,
+ or a negative check, which returns 0 (deny.) E.g.:
+ <programlisting> if ($field eq "qacontact") {
+ if (UserInGroup("quality_assurance")) {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }</programlisting>
+ This says that only users in the group "quality_assurance" can change
+ the QA Contact field of a bug. Getting more weird:
+ <programlisting> if (($field eq "priority") &&
+ ($vars->{'user'}{'login'} =~ /.*\@example\.com$/))
+ {
+ if ($oldvalue eq "P1") {
+ return 1;
+ }
+ else {
+ return 0;
+ }
+ }</programlisting>
+ This says that if the user is trying to change the priority field,
+ and their email address is @example.com, they can only do so if the
+ old value of the field was "P1". Not very useful, but illustrative.
+ </para>
+
+ <para>
+ For a list of possible field names, look in
+ <filename>data/versioncache</filename> for the list called
+ <filename>@::log_columns</filename>. If you need help writing custom
+ rules for your organisation, ask in the newsgroup.
+ </para>
+ </section>
+
+ <section id="upgrading">
+ <title>Upgrading to New Releases</title>
+ <para>A plain Bugzilla is fairly easy to upgrade from one version to a
+ newer one. Always read the release notes to see if there are any issues
+ that you might need to take note of. It is recommended that you take a
+ backup of your database and your entire Bugzilla installation before attempting an
+ upgrade. You can upgrade a 'clean' installation by untarring a new
+ tarball over the old installation. If you are upgrading from 2.12 or
+ later, and have cvs installed, you can type <filename>cvs -z3 update</filename>,
+ and resolve conflicts if there are any.
+ </para>
+
+ <para>However, things get a bit more complicated if you've made
+ changes to Bugzilla's code. In this case, you may have to re-make or
+ reapply those changes. One good method is to take a diff of your customised
+ version against the original, so you can survey all that you've changed.
+ Hopefully, templatisation will reduce the need for
+ this in the future.</para>
+
+ <para>From version 2.8 onwards, Bugzilla databases can be automatically
+ carried forward during an upgrade. However, because the developers of
+ Bugzilla are constantly adding new
+ tables, columns and fields, you'll probably get SQL errors if you just
+ update the code and attempt to use Bugzilla. Always run the
+ <filename>checksetup.pl</filename>
+ script whenever you upgrade your installation.</para>
+
+ <para>If you are running Bugzilla version 2.8 or lower, and wish to
+ upgrade to the latest version, please consult the file,
+ "UPGRADING-pre-2.8" in the Bugzilla root directory after untarring the
+ archive.</para>
</section>
+
+ <!-- Integrating Bugzilla with Third-Party Tools -->
+ &integration;
+
</chapter>
<!-- Keep this comment at the end of the file
sgml-minimize-attributes:nil
sgml-namecase-general:t
sgml-omittag:t
-sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter")
+sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter")
sgml-shorttag:t
sgml-tag-region-if-active:t
End:
projects / thirdparty / bugzilla.git / commitdiff
