From: travis%sedsystems.ca <> Date: Sat, 12 Feb 2005 02:26:22 +0000 (+0000) Subject: Bug 274173 : The Params that are listed in section 3.1 (parameters) should use a... X-Git-Tag: bugzilla-2.16.9~11 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=24a7eabaeaab2a3c4f1e43cb743bff443dd498c3;p=thirdparty%2Fbugzilla.git Bug 274173 : The Params that are listed in section 3.1 (parameters) should use a Patch by Shane H. W. Travis r=colin.ogilvie --- diff --git a/docs/xml/administration.xml b/docs/xml/administration.xml index 8f94e383d5..328c3884a0 100644 --- a/docs/xml/administration.xml +++ b/docs/xml/administration.xml @@ -16,252 +16,291 @@ checklist - - - - maintainer: - - 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. - - - - - - urlbase: - - This parameter defines the fully qualified domain name and web - server path to your Bugzilla installation. - - - - For example, if your Bugzilla query page is - http://www.foo.com/bugzilla/query.cgi, - set your urlbase - to http://www.foo.com/bugzilla/. - - - - - - usebuggroups: - - 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. - + + + + maintainer + + + + 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. + + + - - Set usebuggroups to on - only if you may wish to restrict access - to particular bugs to certain groups of users. I suggest leaving - this parameter off - while initially testing your Bugzilla. - + + + urlbase + + + + This parameter defines the fully qualified domain name and web + server path to your Bugzilla installation. + - - For more information see . - - + + For example, if your Bugzilla query page is + http://www.foo.com/bugzilla/query.cgi, + set your urlbase + to http://www.foo.com/bugzilla/. + + + - - - usebuggroupsentry: + + + usebuggroups + + + + 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. + - 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 on, this places all - newly-created bugs in the group for their product immediately. - - + + Set usebuggroups to on + only if you may wish to restrict access + to particular bugs to certain groups of users. I suggest leaving + this parameter off + while initially testing your Bugzilla. + - - - shadowdb: - - 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. - + + For more information see . + + + - - The shadowdb 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. - - - - As a guide, on reasonably old hardware, mozilla.org began needing - shadowdb when they reached around 40,000 Bugzilla - users with several hundred Bugzilla bug changes and comments per day. - + + + usebuggroupsentry + + + + 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 on, this places all + newly-created bugs in the group for their product immediately. + + + - - The value of the parameter defines the name of the shadow bug - database. Set "shadowdb" to e.g. "bug_shadowdb" if you will be - running a *very* large installation of Bugzilla. - + + + shadowdb + + + + 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. + - - 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 cron. + The shadowdb 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. - - - 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! - - - - - - shutdownhtml: - - 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. - - - - 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 editparams.cgi (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 + shadowdb when they reached around 40,000 Bugzilla + users with several hundred Bugzilla bug changes and comments per day. - - - - - passwordmail: + + The value of the parameter defines the name of the shadow bug + database. Set "shadowdb" to e.g. "bug_shadowdb" if you will be + running a *very* large installation of Bugzilla. + - 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. - + + + 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 cron. + + + + + 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! + + + - - 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. - - + + + shutdownhtml + + + + 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. + - - - movebugs: + + + 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 editparams.cgi (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). + + + + - 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 - movebugs.pl in your Bugzilla source tree for - further documentation, such as it is. - - + + + passwordmail + + + + 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. + - - - useqacontact: + + 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. + + + - 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. - - + + + movebugs + + + + 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 + movebugs.pl in your Bugzilla source tree for + further documentation, such as it is. + + + - - - usestatuswhiteboard: + + + useqacontact + + + + 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. + + + - 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. - - + + + usestatuswhiteboard + + + + 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. + + + - - - whinedays: + + + whinedays + + + + 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). + + + - 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). - - + + + commenton* + + + + 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. + - - - commenton*: - - 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. - + + 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. + - - 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. - + + + 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!) + + + + - + + + supportwatchers + + - 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!) + 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 watchers will only be + copied on emails from bugs they would normally be allowed to view. - - - - - - supportwatchers: - - 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 watchers will only be - copied on emails from bugs they would normally be allowed to view. - - - + + +