From 74bcd6f1f81aa9d6cc06de9e22ca4922a9e36b89 Mon Sep 17 00:00:00 2001
From: "gerv%gerv.net" <>
Date: Thu, 9 May 2002 06:19:08 +0000
Subject: More documentation updates.
---
docs/sgml/patches.sgml | 664 ++++++++++++++++++-------------------------------
1 file changed, 236 insertions(+), 428 deletions(-)
(limited to 'docs/sgml/patches.sgml')
diff --git a/docs/sgml/patches.sgml b/docs/sgml/patches.sgml
index 31d867e86..540109feb 100644
--- a/docs/sgml/patches.sgml
+++ b/docs/sgml/patches.sgml
@@ -1,480 +1,287 @@
-
- Useful Patches and Utilities for Bugzilla
+ Useful Patches and Utilities for Bugzilla
- Are you looking for a way to put your Bugzilla into overdrive? Catch some of the niftiest tricks here in this section.
+ Are you looking for a way to put your Bugzilla into overdrive? Catch
+ some of the niftiest tricks here in this section.
- Apache <filename>mod_rewrite</filename> magic
- Apache's mod_rewrite module lets you do some truly amazing things with URL rewriting. Here are a couple of examples of what you can do.
+ Apache
+ <filename>mod_rewrite</filename>
+
+ magic
+
+ Apache's
+ mod_rewrite
+
+ module lets you do some truly amazing things with URL rewriting. Here are
+ a couple of examples of what you can do.
+
-
- Make it so if someone types
- http://www.foo.com/12345,
- Bugzilla spits back
- http://www.foo.com/show_bug.cgi?id=12345. Try setting up
- your VirtualHost section for Bugzilla with a rule like
- this:
-
+ Make it so if someone types
+ http://www.foo.com/12345
+
+ , Bugzilla spits back http://www.foo.com/show_bug.cgi?id=12345. Try
+ setting up your VirtualHost section for Bugzilla with a rule like
+ this:
+
+
RewriteEngine On
RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R]
]]>
-
-
+
+
- There are many, many more things you can do with
- mod_rewrite. As time goes on, I will include many more in
- the Guide. For now, though, please refer to the mod_rewrite
- documentation at http://www.apache.org
+ There are many, many more things you can do with mod_rewrite.
+ As time goes on, I will include many more in the Guide. For now,
+ though, please refer to the mod_rewrite documentation at
+ http://www.apache.org
+
-
+
The setperl.csh Utility
- You can use the "setperl.csh" utility to quickly and
- easily change the path to perl on all your Bugzilla files. This
- is a C-shell script; if you do not have "csh" or "tcsh" in the
- search path on your system, it will not work!
-
+
+ You can use the "setperl.csh" utility to quickly and easily change
+ the path to perl on all your Bugzilla files. This is a C-shell script; if
+ you do not have "csh" or "tcsh" in the search path on your system, it
+ will not work!
+
-
- Download the "setperl.csh" utility to your Bugzilla
- directory and make it executable.
-
-
-
-
-
- bash#
- cd /your/path/to/bugzilla
-
-
-
-
-
- bash# wget -O
- setperl.csh
- 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=10795'
-
-
-
-
- bash# chmod
- u+x setperl.csh
-
-
-
+ Download the "setperl.csh" utility to your Bugzilla directory
+ and make it executable.
+
+
+
+
+
+ bash#
+
+ cd /your/path/to/bugzilla
+
+
+
+
+
+
+
+ bash#
+
+ wget -O setperl.csh
+ 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=10795'
+
+
+
+
+
+
+
+ bash#
+
+ chmod u+x setperl.csh
+
+
+
+
+
-
- Prepare (and fix) Bugzilla file permissions.
-
-
-
-
-
- bash#
- chmod u+w *
-
-
-
-
-
- bash# chmod
- u+x duplicates.cgi
-
-
-
-
-
- bash#
- chmod a-x bug_status.html
-
-
-
-
+ Prepare (and fix) Bugzilla file permissions.
+
+
+
+
+
+ bash#
+
+ chmod u+w *
+
+
+
+
+
+
+
+ bash#
+
+ chmod u+x duplicates.cgi
+
+
+
+
+
+
+
+ bash#
+
+ chmod a-x bug_status.html
+
+
+
+
+
-
- Run the script:
-
-
- bash#
- ./setperl.csh /your/path/to/perl
-
-
- Using Setperl to set your perl path
-
- bash#
- ./setperl.csh /usr/bin/perl
-
+ Run the script:
+
+
+
+ bash#
+
+ ./setperl.csh /your/path/to/perl
+
+
+
+ Using Setperl to set your perl path
+
+
+
+ bash#
+
+ ./setperl.csh /usr/bin/perl
+
-
-
+
+
Command-line Bugzilla Queries
-
- Users can query Bugzilla from the command line using this suite
- of utilities.
-
-
- The query.conf file contains the mapping from options to field
- names and comparison types. Quoted option names are "grepped"
- for, so it should be easy to edit this file. Comments (#) have
- no effect; you must make sure these lines do not contain any
- quoted "option"
-
-
- buglist is a shell script which submits a Bugzilla query and
- writes the resulting HTML page to stdout. It supports both
- short options, (such as "-Afoo" or "-Rbar") and long options
- (such as "--assignedto=foo" or "--reporter=bar"). If the first
- character of an option is not "-", it is treated as if it were
- prefixed with "--default=".
-
-
- The columlist is taken from the COLUMNLIST environment variable.
- This is equivalent to the "Change Columns" option when you list
- bugs in buglist.cgi. If you have already used Bugzilla, use
- grep COLUMLIST ~/.netscape/cookies to see
- your current COLUMNLIST setting.
-
-
- bugs is a simple shell script which calls buglist and extracts
- the bug numbers from the output. Adding the prefix
- "http://bugzilla.mozilla.org/buglist.cgi?bug_id=" turns the bug
- list into a working link if any bugs are found. Counting bugs is
- easy. Pipe the results through sed -e 's/,/ /g' | wc |
- awk '{printf $2 "\n"}'
+
+ Users can query Bugzilla from the command line using this suite of
+ utilities.
+
+ The query.conf file contains the mapping from options to field
+ names and comparison types. Quoted option names are "grepped" for, so it
+ should be easy to edit this file. Comments (#) have no effect; you must
+ make sure these lines do not contain any quoted "option"
+
+ buglist is a shell script which submits a Bugzilla query and writes
+ the resulting HTML page to stdout. It supports both short options, (such
+ as "-Afoo" or "-Rbar") and long options (such as "--assignedto=foo" or
+ "--reporter=bar"). If the first character of an option is not "-", it is
+ treated as if it were prefixed with "--default=".
+
+ The columlist is taken from the COLUMNLIST environment variable.
+ This is equivalent to the "Change Columns" option when you list bugs in
+ buglist.cgi. If you have already used Bugzilla, use
+ grep COLUMLIST ~/.netscape/cookies
+
+ to see your current COLUMNLIST setting.
+
+ bugs is a simple shell script which calls buglist and extracts the
+ bug numbers from the output. Adding the prefix
+ "http://bugzilla.mozilla.org/buglist.cgi?bug_id=" turns the bug list into
+ a working link if any bugs are found. Counting bugs is easy. Pipe the
+ results through
+ sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'
-
- Akkana says she has good results piping buglist output through
- w3m -T text/html -dump
+
+ Akkana says she has good results piping buglist output through
+ w3m -T text/html -dump
+
-
- Download three files:
-
-
-
-
- bash$ wget -O
- query.conf
- 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26157'
-
-
-
-
- bash$ wget -O
- buglist
- 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26944'
-
-
-
-
- bash# wget -O
- bugs
- 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26215'
-
-
-
+ Download three files:
+
+
+
+
+
+ bash$
+
+ wget -O query.conf
+ 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26157'
+
+
+
+
+
+
+
+ bash$
+
+ wget -O buglist
+ 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26944'
+
+
+
+
+
+
+
+ bash#
+
+ wget -O bugs
+ 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26215'
+
+
+
+
+
-
- Make your utilities executable:
-
- bash$
- chmod u+x buglist bugs
-
-
+ Make your utilities executable:
+
+ bash$
+
+ chmod u+x buglist bugs
+
+
The Quicksearch Utility
-
- Quicksearch is a new, experimental feature of the 2.12 release.
- It consist of two Javascript files, "quicksearch.js" and
- "localconfig.js", and two documentation files,
- "quicksearch.html" and "quicksearchhack.html"
-
-
- The index.html page has been updated to include the QuickSearch
- text box.
-
-
- To take full advantage of the query power, the Bugzilla
- maintainer must edit "localconfig.js" according to the value
- sets used in the local installation.
-
-
- Currently, keywords must be hard-coded in localconfig.js. If
- they are not, keywords are not automatically recognized. This
- means, if localconfig.js is left unconfigured, that searching
- for a bug with the "foo" keyword will only find bugs with "foo"
- in the summary, status whiteboard, product or component name,
- but not those with the keyword "foo".
-
-
- Workarounds for Bugzilla users:
-
- search for '!foo' (this will find only bugs with the
- keyword "foo"
- search 'foo,!foo' (equivalent to 'foo OR
- keyword:foo')
-
-
-
- When this tool is ported from client-side JavaScript to
- server-side Perl, the requirement for hard-coding keywords can
- be fixed. This bug has details.
-
-
-
- Hacking Bugzilla
-
- 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.
+ Quicksearch is a new, experimental feature of the 2.12 release. It
+ consist of two Javascript files, "quicksearch.js" and "localconfig.js",
+ and two documentation files, "quicksearch.html" and
+ "quicksearchhack.html"
+
+ The index.html page has been updated to include the QuickSearch
+ text box.
+
+ To take full advantage of the query power, the Bugzilla maintainer
+ must edit "localconfig.js" according to the value sets used in the local
+ installation.
+
+ Currently, keywords must be hard-coded in localconfig.js. If they
+ are not, keywords are not automatically recognized. This means, if
+ localconfig.js is left unconfigured, that searching for a bug with the
+ "foo" keyword will only find bugs with "foo" in the summary, status
+ whiteboard, product or component name, but not those with the keyword
+ "foo".
+
+ Workarounds for Bugzilla users:
+
+ search for '!foo' (this will find only bugs with the keyword
+ "foo"
+
+ search 'foo,!foo' (equivalent to 'foo OR keyword:foo')
+
-
- Things that have caused problems and should be avoided
-
-
-
- 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 THIS --
-
-
-
-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 (or any) 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 :).
-
-
- The Bugzilla development team has decided to adopt the perl style guide as
- published by Larry Wall. This giude can be found in Programming
- Perl
(the camel book) or by typing man perlstyle at
- your favorite shell prompt.
-
-
- What appears below if a brief summary, please refer to the perl style
- guide if you don't see your question covered here. It is much better to submit
- a patch which fails these criteria than no patch at all, but please try to meet
- these minimum standards when submitting code to Bugzilla.
-
-
-
-
- Whitespace
-
-
- Bugzilla's preferred indentation is 4 spaces (no tabs, please).
-
-
-
-
- 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 THIS --
-
-
-
-if ($var)
-{
- print "The variable is true";
-}
-else
-{
- print "Try again";
-}
-
-
-
-
-
-
- Cookies
-
-
- Bugzilla uses cookies to ease the user experience, but no new patches
- should require user-side cookies.
-
-
-
-
-
- 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.
-
-
-
-
-
- Javascript dependencies
-
-
- While Bugzilla uses Javascript to make the user experience easier, no patch
- to Bugzilla should require Javascript.
-
-
-
-
-
- Patch Format
-
-
- All patches submitted for inclusion into Bugzilla should be in the form of a
- unified diff
. This comes from using diff -u
- instead of simply diff
when creating your patch. This will
- result in quicker acceptance of the patch.
-
-
-
-
-
- Schema Changes
-
-
- If you make schema changes, you should modify sanitycheck.cgi
- to support the new schema. All referential columns should be checked.
-
-
-
-
-
- Taint Mode
-
-
- All new cgis must run in Taint mode (Perl taint and DBI taint), and existing cgi's
- which run in taint mode must not have taint mode turned off.
-
-
-
-
-
- Templatization
-
-
- Patches to Bugzilla need to support templates so they do not force user interface choices
- on Bugzilla administrators.
-
-
-
-
-
- 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 blatantly obvious what the variable holds and most likely be shown
- on the same screen as my $ret = "";.
-
-
-
-
-
- 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().
-
-
-
-
- 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.
-
-
-
-
-
-
+ When this tool is ported from client-side JavaScript to server-side
+ Perl, the requirement for hard-coding keywords can be fixed.
+ This
+ bug
+ has details.
+
+
+
--
cgit v1.2.3-24-g4f1b