summaryrefslogtreecommitdiffstats
path: root/docs/xml
diff options
context:
space:
mode:
Diffstat (limited to 'docs/xml')
-rw-r--r--docs/xml/administration.xml463
1 files changed, 252 insertions, 211 deletions
diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml
index 67f818e1f..3b84f40c8 100644
--- a/docs/xml/administration.xml
+++ b/docs/xml/administration.xml
@@ -16,244 +16,285 @@
<primary>checklist</primary>
</indexterm>
- <procedure>
- <step>
- <para>
- <command>maintainer</command>:
-
- The maintainer parameter is the email address of the person
- responsible for maintaining this Bugzilla installation.
- The address need not be that of a valid Bugzilla account.
- </para>
- </step>
-
- <step>
- <para>
- <command>urlbase</command>:
-
- This parameter defines the fully qualified domain name and web
- server path to your Bugzilla installation.
- </para>
+ <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>
- <para>
- For example, if your Bugzilla query page is
- <filename>http://www.foo.com/bugzilla/query.cgi</filename>,
- set your <quote>urlbase</quote>
- to <filename>http://www.foo.com/bugzilla/</filename>.
- </para>
- </step>
+ <varlistentry>
+ <term>
+ urlbase
+ </term>
+ <listitem>
+ <para>
+ This parameter defines the fully qualified domain name and web
+ server path to your Bugzilla installation.
+ </para>
- <step>
- <para>
- <command>makeproductgroups</command>:
+ <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>
- This dictates whether or not to automatically create groups
- when new products are created.
- </para>
- </step>
+ <varlistentry>
+ <term>
+ makeproductgroups
+ </term>
+ <listitem>
+ <para>
+ This dictates whether or not to automatically create groups
+ when new products are created.
+ </para>
+ </listitem>
+ </varlistentry>
- <step>
- <para>
- <command>useentrygroupdefault</command>:
-
- Bugzilla products can have a group associated with them, so that
- certain users can only see bugs in certain products. When this
- parameter is set to <quote>on</quote>, this
- causes the initial group controls on newly created products
- to place all newly-created bugs in the group
- having the same name as the product immediately.
- After a product is initially created, the group controls
- can be further adjusted without interference by
- this mechanism.
- </para>
- </step>
+ <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>
- <step>
- <para>
- <command>shadowdb</command>:
-
- You run into an interesting problem when Bugzilla reaches a
- high level of continuous activity. MySQL supports only table-level
- write locking. What this means is that if someone needs to make a
- change to a bug, they will lock the entire table until the operation
- is complete. Locking for write also blocks reads until the write is
- complete. Note that more recent versions of mysql support row level
- locking using different table types. These types are slower than the
- standard type, and Bugzilla does not yet take advantage of features
- such as transactions which would justify this speed decrease. The
- Bugzilla team are, however, happy to hear about any experiences with
- row level locking and Bugzilla.
- </para>
+ <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>
+ The <quote>shadowdb</quote> parameter was designed to get around
+ this limitation. While only a single user is allowed to write to
+ a table at a time, reads can continue unimpeded on a read-only
+ shadow copy of the database. Although your database size will
+ double, a shadow database can cause an enormous performance
+ improvement when implemented on extremely high-traffic Bugzilla
+ databases.
+ </para>
- <para>
- As a guide, on reasonably old hardware, mozilla.org began needing
- <quote>shadowdb</quote> when they reached around 40,000 Bugzilla
- users with several hundred Bugzilla bug changes and comments per day.
- </para>
-
- <para>
- The value of the parameter defines the name of the shadow bug
- database. You will need to set the host and port settings from
- the params page, and set up replication in your database server
- so that updates reach this readonly mirror. Consult your database
- documentation for more detail.
- </para>
- </step>
-
- <step>
- <para>
- <command>shutdownhtml</command>:
-
- If you need to shut down Bugzilla to perform administration, enter
- some descriptive 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).
+ 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>
- </note>
- </step>
-
- <step>
- <para>
- <command>passwordmail</command>:
-
- Every time a user creates an account, the text of this parameter
- (with substitutions) is sent to the new user along with their
- password message.
- </para>
- <para>
- Add any text you wish to the "passwordmail" parameter box. For
- instance, many people choose to use this box to give a quick
- training blurb about how to use Bugzilla at your site.
- </para>
- </step>
-
-
- <step>
- <para>
- <command>movebugs</command>:
-
- This option is an undocumented feature to allow moving bugs
- between separate Bugzilla installations. You will need to understand
- the source code in order to use this feature. Please consult
- <filename>movebugs.pl</filename> in your Bugzilla source tree for
- further documentation, such as it is.
- </para>
- </step>
+ <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>
- <step>
- <para>
- <command>useqacontact</command>:
+ <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>
- This allows you to define an email address for each component,
- in addition to that of the default owner, who will be sent
- carbon copies of incoming bugs.
- </para>
- </step>
+ <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>
- <step>
- <para>
- <command>usestatuswhiteboard</command>:
+ <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>
- This defines whether you wish to have a free-form, overwritable field
- associated with each bug. The advantage of the Status Whiteboard is
- that it can be deleted or modified with ease, and provides an
- easily-searchable field for indexing some bugs that have some trait
- in common.
- </para>
- </step>
+ <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>
- <step>
- <para>
- <command>whinedays</command>:
+ <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>
- Set this to the number of days you want to let bugs go
- in the NEW or REOPENED state before notifying people they have
- untouched new bugs. If you do not plan to use this feature, simply
- do not set up the whining cron job described in the installation
- instructions, or set this value to "0" (never whine).
- </para>
- </step>
+ <varlistentry>
+ <term>
+ useqacontact
+ </term>
+ <listitem>
+ <para>
+ This allows you to define an email address for each component,
+ in addition to that of the default owner, who will be sent
+ carbon copies of incoming bugs.
+ </para>
+ </listitem>
+ </varlistentry>
- <step>
- <para>
- <command>commenton*</command>:
-
- All these fields allow you to dictate what changes can pass
- without comment, and which must have a comment from the
- person who changed them. Often, administrators will allow
- users to add themselves to the CC list, accept bugs, or
- change the Status Whiteboard without adding a comment as to
- their reasons for the change, yet require that most other
- changes come with an explanation.
- </para>
+ <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>
- <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>
+ <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>
- <note>
+ <varlistentry>
+ <term>
+ commenton*
+ </term>
+ <listitem>
<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!)
+ 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>
- </note>
- </step>
- <step>
- <para>
- <command>supportwatchers</command>:
+ <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>
- 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>
- </step>
+ <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>
- <step>
- <para>
- <command>noresolveonopenblockers</command>:
- 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>
- </step>
+ <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>
- </procedure>
+ </variablelist>
</section>
<section id="useradmin">