diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/en/xml/Bugzilla-Guide.xml | 12 | ||||
| -rw-r--r-- | docs/en/xml/about.xml | 10 | ||||
| -rw-r--r-- | docs/en/xml/administration.xml | 97 | ||||
| -rw-r--r-- | docs/en/xml/installation.xml | 160 | ||||
| -rw-r--r-- | docs/en/xml/integration.xml | 8 | ||||
| -rw-r--r-- | docs/en/xml/patches.xml | 98 | ||||
| -rw-r--r-- | docs/en/xml/using.xml | 85 |
7 files changed, 411 insertions, 59 deletions
diff --git a/docs/en/xml/Bugzilla-Guide.xml b/docs/en/xml/Bugzilla-Guide.xml index 59befaf0a..8f2136bd8 100644 --- a/docs/en/xml/Bugzilla-Guide.xml +++ b/docs/en/xml/Bugzilla-Guide.xml @@ -26,7 +26,7 @@ <!ENTITY bzg-ver "2.14"> <!ENTITY bzg-cvs-ver "2.15.0"> <!ENTITY bzg-auth "Matthew P. Barnson"> -<!ENTITY bzg-auth-email "<email>barnboy@NOSPAM.trilobyte.net</email>"> +<!ENTITY bzg-auth-email "<email>barnboy@trilobyte.net</email>"> <!ENTITY mysql "http://www.mysql.com/"> <!ENTITY perl-ver "5.6.1"> @@ -126,14 +126,14 @@ try to avoid clutter and feel free to waste space in the code to make it more re <othername>P.</othername> <surname>Barnson</surname> <affiliation> - <address><email>barnboy@NOSPAM.trilobyte.net</email></address> + <address><email>barnboy@trilobyte.net</email></address> </affiliation> </author> <collab> <collabname>Zach Lipton</collabname> <affiliation> - <address><email>zach@NOSPAM.zachlipton.com</email></address> + <address><email>zach AT zachlipton DOT com</email></address> </affiliation> </collab> @@ -196,6 +196,9 @@ try to avoid clutter and feel free to waste space in the code to make it more re <!-- The Future of Bugzilla --> &future; +<!-- Major Bugzilla Variants --> +&variants; + <!-- Appendix: The Frequently Asked Questions --> &faq; @@ -205,9 +208,6 @@ try to avoid clutter and feel free to waste space in the code to make it more re <!-- Appendix: The Database Schema --> &database; -<!-- Appendix: Major Bugzilla Variants --> -&variants; - <!-- Appendix: Custom Patches --> &patches; diff --git a/docs/en/xml/about.xml b/docs/en/xml/about.xml index 89f7bb127..04e054bc2 100644 --- a/docs/en/xml/about.xml +++ b/docs/en/xml/about.xml @@ -70,8 +70,7 @@ <para> If you have any questions regarding this document, its copyright, or publishing this document in non-electronic form, - please contact &bzg-auth;. Remove "NOSPAM" from email address - to send. + please contact &bzg-auth;. </para> </section> @@ -172,8 +171,8 @@ </para> <para> <ulink url="mailto://terry@mozilla.org">Terry Weissman</ulink> - for initially converting Bugzilla from BugSplat! and writing the - README upon which this documentation is largely based. + for initially writing Bugzilla and creating the + README upon which the UNIX installation documentation is largely based. </para> <para> <ulink url="mailto://tara@tequilarista.org">Tara @@ -204,7 +203,8 @@ documentation (in no particular order): </para> <para> - Andrew Pearson, Spencer Smith, Eric Hanson, Kevin Brannen, Ron Teitelbaum + Andrew Pearson, Spencer Smith, Eric Hanson, Kevin Brannen, Ron + Teitelbaum, Jacob Steenhagen, Joe Robins </para> </section> <section id="feedback"> diff --git a/docs/en/xml/administration.xml b/docs/en/xml/administration.xml index 54f984fbc..98e726312 100644 --- a/docs/en/xml/administration.xml +++ b/docs/en/xml/administration.xml @@ -1192,6 +1192,103 @@ </para> </listitem> </orderedlist> + <para> + You may find this example illustrative for how bug groups work. + <example> + <title>Bugzilla Groups</title> + <literallayout> +Bugzilla Groups example +----------------------- + +For this example, let us suppose we have four groups, call them +Group1, Group2, Group3, and Group4. + +We have 5 users, User1, User2, User3, User4, User5. + +We have 8 bugs, Bug1, ..., Bug8. + +Group membership is defined by this chart: +(X denotes that user is in that group.) +(I apologize for the nasty formatting of this table. Try viewing +it in a text-based browser or something for now. -MPB) + + G G G G + r r r r + o o o o + u u u u + p p p p + 1 2 3 4 + +-+-+-+-+ +User1|X| | | | + +-+-+-+-+ +User2| |X| | | + +-+-+-+-+ +User3|X| |X| | + +-+-+-+-+ +User4|X|X|X| | + +-+-+-+-+ +User5| | | | | + +-+-+-+-+ + +Bug restrictions are defined by this chart: +(X denotes that bug is restricted to that group.) + + G G G G + r r r r + o o o o + u u u u + p p p p + 1 2 3 4 + +-+-+-+-+ +Bug1| | | | | + +-+-+-+-+ +Bug2| |X| | | + +-+-+-+-+ +Bug3| | |X| | + +-+-+-+-+ +Bug4| | | |X| + +-+-+-+-+ +Bug5|X|X| | | + +-+-+-+-+ +Bug6|X| |X| | + +-+-+-+-+ +Bug7|X|X|X| | + +-+-+-+-+ +Bug8|X|X|X|X| + +-+-+-+-+ + +Who can see each bug? + +Bug1 has no group restrictions. Therefore, Bug1 can be seen by any +user, whatever their group membership. This is going to be the only +bug that User5 can see, because User5 isn't in any groups. + +Bug2 can be seen by anyone in Group2, that is User2 and User4. + +Bug3 can be seen by anyone in Group3, that is User3 and User4. + +Bug4 can be seen by anyone in Group4. Nobody is in Group4, so none of +these users can see Bug4. + +Bug5 can be seen by anyone who is in _both_ Group1 and Group2. This +is only User4. User1 cannot see it because he is not in Group2, and +User2 cannot see it because she is not in Group1. + +Bug6 can be seen by anyone who is in both Group1 and Group3. This +would include User3 and User4. Similar to Bug5, User1 cannot see Bug6 +because he is not in Group3. + +Bug7 can be seen by anyone who is in Group1, Group2, and Group3. This +is only User4. All of the others are missing at least one of those +group priveleges, and thus cannot see the bug. + +Bug8 can be seen by anyone who is in Group1, Group2, Group3, and +Group4. There is nobody in all four of these groups, so nobody can +see Bug8. It doesn't matter that User4 is in Group1, Group2, and +Group3, since he isn't in Group4. + </literallayout> + </example> + </para> </section> </section> diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index 547d466ba..9cf100fdb 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -616,6 +616,15 @@ bash# mkdir /usr/bonsaitools/bin bash# ln -s /usr/bin/perl /usr/bosaitools/bin/perl </programlisting> </para> + <para> + Alternately, you can simply run this perl one-liner to + change your path to perl in all the files in your Bugzilla + installation: + <programlisting> +perl -pi -e 's@#!/usr/bonsaitools/bin/perl@/usr/bin/perl@' *cgi *pl Bug.pm + </programlisting> + Change the second path to perl to match your installation. + </para> </example> <tip> <para> @@ -1241,7 +1250,7 @@ bash# cd $BUGZILLA_HOME; for i in `ls *.cgi`; \ </section> - <section> + <section id="unixhistory"> <title>UNIX Installation Instructions History</title> <para> This document was originally adapted from the Bonsai @@ -1252,9 +1261,8 @@ bash# cd $BUGZILLA_HOME; for i in `ls *.cgi`; \ The February 25, 1999 re-write of this page was done by Ry4an Brase <ry4an@ry4an.org>, with some edits by Terry Weissman, Bryce Nesbitt, Martin Pool, & Dan Mosedale (But - don't send bug reports to them; report them using bugzilla, at - http://bugzilla.mozilla.org/enter_bug.cgi , project Webtools, - component Bugzilla). + don't send bug reports to them; report them using bugzilla, at <ulink + url="http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla">http://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla</ulink> ). </para> <para> This document was heavily modified again Wednesday, March 07 @@ -1696,16 +1704,46 @@ exit; <step> <para> - Modify the invocation of all system() calls in all perl scripts in your Bugzilla directory. For instance, change this line in processmail: - <programlisting> -system ("./processmail.pl",@ARGLIST); - </programlisting> -to - <programlisting> + Modify the invocation of all system() calls in all perl + scripts in your Bugzilla directory. For instance, change + this line in processmail: + <programlisting> +system ("./processmail.pl",@ARGLIST); + </programlisting> to + <programlisting> system ("perl processmail.pl",@ARGLIST); </programlisting> </para> </step> + <step> + <para> + Add <function>binmode()</function> calls so attachments + will work (<ulink + url="http://bugzilla.mozilla.org/show_bug.cgi?id=62000">bug 62000</ulink>). + </para> + <para> + Because Microsoft Windows based systems handle binary + files different than Unix based systems, you need to add + the following lines to + <filename>createattachment.cgi</filename> and + <filename>showattachment.cgi</filename> before the + <function>require 'CGI.pl';</function> line. +</para> +<para> +<programlisting> +<![CDATA[ +binmode(STDIN); +binmode(STDOUT); +]]> +</programlisting> + </para> + <note> + <para> + According to <ulink + url="http://bugzilla.mozilla.org/show_bug.cgi?id=62000">bug 62000</ulink>, the perl documentation says that you should always use <function>binmode()</function> when dealing with binary files, but never when dealing with text files. That seems to suggest that rather than aribtrarily putting <function>binmode()</function> at the begining of the attachment files, there should be logic to determine if <function>binmode()</function> is needed or not. + </para> + </note> + </step> </procedure> <tip> @@ -1714,6 +1752,8 @@ system ("perl processmail.pl",@ARGLIST); relationships to Properties -> Home directory (tab) -> Application Settings (section) -> Configuration (button), such as: + </para> + <para> <programlisting> .cgi to: <perl install directory>\perl.exe %s %s .pl to: <perl install directory>\perl.exe %s %s @@ -1742,7 +1782,9 @@ GET,HEAD,POST registry at the following location: </para> <para> - HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap + <programlisting> +HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\W3SVC\Parameters\ScriptMap + </programlisting> </para> <para> The keys should be called ".pl" and ".cgi", and both @@ -1761,26 +1803,102 @@ GET,HEAD,POST If attempting to run Bugzilla 2.12 or older, you will need to remove encrypt() calls from the Perl source. This is <emphasis>not necessary</emphasis> for Bugzilla 2.13 and - later. + later, which includes the current release, Bugzilla + &bz-ver;. <example> <title>Removing encrypt() for Windows NT Bugzilla version 2.12 or earlier</title> <para> - Replace this: - <programlisting> -SendSQL("SELECT encrypt(" . SqlQuote($enteredpwd) . ", " . SqlQuote(substr($realcryptpwd, 0, 2)) . ")"); -my $enteredcryptpwd = FetchOneColumn(); - </programlisting> - with this: - <programlisting> -my $enteredcryptpwd = $enteredpwd - </programlisting> + Replace this: + <programlisting> +SendSQL("SELECT encrypt(" . SqlQuote($enteredpwd) . ", " . SQLQuote(substr($realcryptpwd, 0, 2)) . ")"); +my $enteredcryptpwd = FetchOneColumn(); + </programlisting> +with this: + <programlisting> +my $enteredcryptpwd = $enteredpwd + </programlisting> in cgi.pl. </para> </example> </para> </tip> </section> + + <section id="bzldap"> + <title>Bugzilla LDAP Integration</title> + <para> + What follows is some late-breaking information on using the + LDAP authentication options with Bugzilla. The author has not + tested these (nor even formatted this section!) so please + contribute feedback to the newsgroup. + </para> + <literallayout> +Mozilla::LDAP module + +The Mozilla::LDAP module allows you to use LDAP for authentication to +the Bugzilla system. This module is not required if you are not using +LDAP. + +Mozilla::LDAP (aka PerLDAP) is available for download from +http://www.mozilla.org/directory. + +NOTE: The Mozilla::LDAP module requires Netscape's Directory SDK. +Follow the link for "Directory SDK for C" on that same page to +download the SDK first. After you have installed this SDK, then +install the PerLDAP module. +---------------------------------------------------------------------- + +Post-Installation Checklist +---------------------------------------------------------------------- +Set useLDAP to "On" **only** if you will be using an LDAP directory +for authentication. Be very careful when setting up this parameter; +if you set LDAP authentication, but do not have a valid LDAP directory +set up, you will not be able to log back in to Bugzilla once you log +out. (If this happens, you can get back in by manually editing the +data/params file, and setting useLDAP back to 0.) + +If using LDAP, you must set the three additional parameters: + +Set LDAPserver to the name (and optionally port) of your LDAP server. +If no port is specified, it defaults to the default port of 389. (e.g +"ldap.mycompany.com" or "ldap.mycompany.com:1234") + +Set LDAPBaseDN to the base DN for searching for users in your LDAP +directory. (e.g. "ou=People,o=MyCompany") uids must be unique under +the DN specified here. + +Set LDAPmailattribute to the name of the attribute in your LDAP +directory which contains the primary email address. On most directory +servers available, this is "mail", but you may need to change this. +---------------------------------------------------------------------- + +(Not sure where this bit should go, but it's important that it be in +there somewhere...) +---------------------------------------------------------------------- +Using LDAP authentication for Bugzilla: + +The existing authentication scheme for Bugzilla uses email addresses +as the primary user ID, and a password to authenticate that user. All +places within Bugzilla where you need to deal with user ID (e.g +assigning a bug) use the email address. + +The LDAP authentication builds on top of this scheme, rather than +replacing it. The initial log in is done with a username and password +for the LDAP directory. This then fetches the email address from LDAP +and authenticates seamlessly in the standard Bugzilla authentication +scheme using this email address. If an account for this address +already exists in your Bugzilla system, it will log in to that +account. If no account for that email address exists, one is created +at the time of login. (In this case, Bugzilla will attempt to use the +"displayName" or "cn" attribute to determine the user's full name.) + +After authentication, all other user-related tasks are still handled +by email address, not LDAP username. You still assign bugs by email +address, query on users by email address, etc. +---------------------------------------------------------------------- + </literallayout> + </section> </section> </chapter> diff --git a/docs/en/xml/integration.xml b/docs/en/xml/integration.xml index e0547c365..36cc617e2 100644 --- a/docs/en/xml/integration.xml +++ b/docs/en/xml/integration.xml @@ -35,6 +35,14 @@ an @resolution field, you can even change the Bugzilla bug state. </para> + <para> + There is also a project, based upon somewhat dated Bugzilla + code, to integrate CVS and Bugzilla through CVS' ability to + email. Check it out at: + <ulink url="http://homepages.kcbbs.gen.nz/~tonyg/"> + http://homepages.kcbbs.gen.nz/~tonyg/</ulink>, under the + <quote>cvszilla</quote> link. + </para> </section> <section id="scm" xreflabel="Perforce SCM (Fast Software Configuration Management System, a powerful commercial alternative to CVS"> diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml index 3a1ce90d2..3f49255f2 100644 --- a/docs/en/xml/patches.xml +++ b/docs/en/xml/patches.xml @@ -247,6 +247,104 @@ RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R] </para> </section> + <section id="bzhacking"> + <title>Hacking Bugzilla</title> + <para> + What follows are some general guidelines for changing Bugzilla, and adhering to good coding practice while doing so. We've had some checkins in the past which ruined Bugzilla installations because of disregard for these conventions. Sorry for the lack of formatting; I got this info into the Guide on the day of 2.14 release and haven't formatted it yet. + </para> + <literallayout> + +The following is a guide for reviewers when checking code into Bugzilla's +CVS repostory at mozilla.org. If you wish to submit patches to Bugzilla, +you should follow the rules and style conventions below. Any code that +does not adhere to these basic rules will not be added to Bugzilla's +codebase. + + 1. Usage of variables in Regular Expressions + + It is very important that you don't use a variable in a regular + expression unless that variable is supposed to contain an expression. + This especially applies when using grep. You should use: + + grep ($_ eq $value, @array); + + - NOT - + + grep (/$value/, @array); + + If you need to use a non-expression variable inside of an expression, be + sure to quote it properly (using \Q..\E). + +Coding Style for Bugzilla +------------------------- + +While it's true that not all of the code currently in Bugzilla adheres to +this styleguide, it is something that is being worked toward. Therefore, +we ask that all new code (submitted patches and new files) follow this guide +as closely as possible (if you're only changing 1 or 2 lines, you don't have +to reformat the entire file :). + + 1. Whitespace + + Bugzilla's prefered indentation is 4 spaces (no tabs, please). + + 2. Curly braces. + + The opening brace of a block should be on the same line as the statement + that is causing the block and the closing brace should be at the same + indentation level as that statement, for example: + + if ($var) { + print "The variable is true"; + } else { + print "Try again"; + } + + - NOT - + + if ($var) + { + print "The variable is true"; + } + else + { + print "Try again"; + } + + 3. File Names + + File names for bugzilla code and support documention should be legal across + multiple platforms. \ / : * ? " < > and | are all illegal characters for + filenames on various platforms. Also, file names should not have spaces in + them as they can cause confusion in CVS and other mozilla.org utilities. + + 4. Variable Names + + If a variable is scoped globally ($::variable) its name should be descriptive + of what it contains. Local variables can be named a bit looser, provided the + context makes their content obvious. For example, $ret could be used as a + staging variable for a routine's return value as the line |return $ret;| will + make it blatently obvious what the variable holds and most likely be shown + on the same screen as |my $ret = "";|. + + 5. Cross Database Compatability + + Bugzilla was originally written to work with MySQL and therefore took advantage + of some of its features that aren't contained in other RDBMS software. These + should be avoided in all new code. Examples of these features are enums and + encrypt(). + + 6. Cross Platform Compatability + + While Bugzilla was written to be used on Unix based systems (and Unix/Linux is + still the only officially supported platform) there are many who desire/need to + run Bugzilla on Microsoft Windows boxes. Whenever possible, we should strive + not to make the lives of these people any more complicated and avoid doing things + that break Bugzilla's ability to run on multiple operating systems. + + </literallayout> + </section> + </appendix> diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml index 91a7658cd..934817081 100644 --- a/docs/en/xml/using.xml +++ b/docs/en/xml/using.xml @@ -399,13 +399,13 @@ system against which all others are measured. our Bugzilla database. Please notice the box is a <emphasis>scrollbox</emphasis>. Using the down arrow on the scrollbox, scroll down until you can see an entry - called "Webtools". Select this entry. + called "Bugzilla". Select this entry. </para> </listitem> <listitem> <para> Did you notice that some of the boxes to the right changed - when you selected "Webtools"? Every Program (or Product) + when you selected "Bugzilla"? Every Program (or Product) has different Versions, Components, and Target Milestones associated with it. A "Version" is the number of a software program. @@ -452,36 +452,67 @@ system against which all others are measured. Normally, a Component has a single Owner, who is responsible for overseeing efforts to improve that Component. <example> - <title>Mozilla Webtools Components</title> + <title>Mozilla's Bugzilla Components</title> <informalexample> <para> - Mozilla's "Webtools" Product is composed of several pieces (Components): + Mozilla's "Bugzilla" Product is composed of several pieces (Components): <simplelist> - <member><emphasis>Bonsai</emphasis>, - a tool to show recent changes to Mozilla</member> - <member><emphasis>Bugzilla</emphasis>, - a defect-tracking tool</member> - <member><emphasis>Build</emphasis>, - a tool to automatically compile source code - into machine-readable form</member> - <member><emphasis>Despot</emphasis>, - a program that controls access to the other Webtools</member> - <member><emphasis>LXR</emphasis>, - a utility that automatically marks up text files - to make them more readable</member> - <member><emphasis>MozBot</emphasis>, - a "robot" that announces changes to Mozilla in Chat</member> - <member><emphasis>TestManager</emphasis>, - a tool to help find bugs in Mozilla</member> - <member><emphasis>Tinderbox</emphasis>, - which displays reports from Build</member> + <member><emphasis>Administration</emphasis>, + Administration of a bugzilla installation, including + <filename>editcomponents.cgi</filename>, + <filename>editgroups.cgi</filename>, + <filename>editkeywords.cgi</filename>, + <filename>editparams.cgi</filename>, + <filename>editproducts.cgi</filename>, + <filename>editusers.cgi</filename>, + <filename>editversions.cgi,</filename> and + <filename>sanitycheck.cgi</filename>. + </member> + <member><emphasis>Bugzilla-General</emphasis>, + Anything that doesn't fit in the other components, or spans + multiple components. + </member> + <member><emphasis>Creating/Changing Bugs</emphasis>, + Creating, changing, and viewing bugs. + <filename>enter_bug.cgi</filename>, + <filename>post_bug.cgi</filename>, + <filename>show_bug.cgi</filename> and + <filename>process_bug.cgi</filename>. + </member> + <member><emphasis>Documentation</emphasis>, + The bugzilla documentation, including anything in the + <filename>docs/</filename> directory and The Bugzilla Guide + (This document :) + </member> + <member><emphasis>Email</emphasis>, + Anything to do with email sent by Bugzilla. + <filename>processmail</filename> + </member> + <member><emphasis>Installation</emphasis>, + The installation process of Bugzilla. This includes + <filename>checksetup.pl</filename> and whatever else it evolves into. + </member> + <member><emphasis>Query/Buglist</emphasis>, + Anything to do with searching for bugs and viewing the buglists. + <filename>query.cgi</filename> and + <filename>buglist.cgi</filename> + </member> + <member><emphasis>Reporting/Charting</emphasis>, + Getting reports from Bugzilla. + <filename>reports.cgi</filename> and + <filename>duplicates.cgi</filename> + </member> + <member><emphasis>User Accounts</emphasis>, + Anything about managing a user account from the user's perspective. + <filename>userprefs.cgi</filename>, saved queries, creating accounts, + changing passwords, logging in, etc. + </member> + <member><emphasis>User Interface</emphasis>, + General issues having to do with the user interface cosmetics (not + functionality) including cosmetic issues, HTML templates, etc. + </member> </simplelist> </para> - <para> - A different person is responsible for each of these Components. - Tara Hernandez keeps - the "Bugzilla" component up-to-date. - </para> </informalexample> </example> </para> |