diff options
| -rw-r--r-- | docs/en/rel_notes.txt | 22 | ||||
| -rw-r--r-- | docs/en/xml/about.xml | 32 | ||||
| -rw-r--r-- | docs/en/xml/customization.xml | 384 | ||||
| -rw-r--r-- | docs/en/xml/introduction.xml | 2 | ||||
| -rw-r--r-- | docs/en/xml/patches.xml | 527 | ||||
| -rw-r--r-- | docs/en/xml/using.xml | 12 |
6 files changed, 158 insertions, 821 deletions
diff --git a/docs/en/rel_notes.txt b/docs/en/rel_notes.txt index 64212a292..47317d0a3 100644 --- a/docs/en/rel_notes.txt +++ b/docs/en/rel_notes.txt @@ -2387,7 +2387,7 @@ See also next section. 'letsubmitterchoosepriority' was off. (bug 63018) -- Most CGIs are now templatised. This helps to make it +- Most CGIs are now templatized. This helps to make it easier to remember to HTML filter values and easier to spot when they are not, preventing cross site scripting attacks. (bug 86168) @@ -2398,17 +2398,17 @@ See also next section. *** IMPORTANT CHANGES *** -- 2.16 introduces "templatisation", a new feature that allows - administrators to easily customise the HTML output (the "look and feel") +- 2.16 introduces "templatization", a new feature that allows + administrators to easily customize the HTML output (the "look and feel") of Bugzilla without altering Perl code. Bugzilla uses the - "Template Toolkit" for this. Please see the "Template Customisation" + "Template Toolkit" for this. Please see the "Template Customization" section of the Bugzilla Guide for more details. - Administrators who ran the 2.15 development version and customised + Administrators who ran the 2.15 development version with custom templates should check the templates are still valid, as file names and file paths have changed. - Most output is now templatised. This process will be complete next + Most output is now templatized. This process will be complete next milestone. For speed, compiled templates are cached on disk. If you modify the @@ -2462,7 +2462,7 @@ See also next section. lengthy delays in future if this problem reoccurs. (bug 106377) -- In parallel with templatisation, a lot of changes have been made to the HTML +- In parallel with templatization, a lot of changes have been made to the HTML output of the Bugzilla CGIs. This could break code that attempts to parse such code. For example, this breaks mozbot. (no bug number) @@ -2739,8 +2739,8 @@ known to us after the Bugzilla 2.14 release. *** SECURITY ISSUES RESOLVED *** -- Multiple instances of unauthorised access to confidential - bugs has been fixed. +- Multiple instances of unauthorized access to confidential + bugs have been fixed. (bug 39524, 39526, 39527, 39531, 39533, 70189, 82781) - Multiple instances of untrusted parameters not being @@ -2751,7 +2751,7 @@ known to us after the Bugzilla 2.14 release. - After logging in passwords no longer appear in the URL. (bug 15980) -- Procedures to prevent unauthorised access to confidential +- Procedures to prevent unauthorized access to confidential files are now simpler. In particular the shadow directory no longer exists and the data/comments file no longer needs to be directly accessible, so the entire data directory can @@ -2762,7 +2762,7 @@ known to us after the Bugzilla 2.14 release. - If they do not already exist, checksetup.pl will attempt to write Apache .htaccess files by default, to prevent - unauthorised access to confidential files. You can turn this + unauthorized access to confidential files. You can turn this off in the localconfig file. (bug 76154) diff --git a/docs/en/xml/about.xml b/docs/en/xml/about.xml index dcfee1325..30d61a350 100644 --- a/docs/en/xml/about.xml +++ b/docs/en/xml/about.xml @@ -1,6 +1,6 @@ <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook V4.1//EN" [ <!ENTITY conventions SYSTEM "conventions.xml"> ] > --> -<!-- $Id: about.xml,v 1.18 2008/04/04 06:48:10 jake%bugzilla.org Exp $ --> +<!-- $Id: about.xml,v 1.25 2008/04/04 06:48:17 timeless%mozdev.org Exp $ --> <chapter id="about"> <title>About This Guide</title> @@ -65,10 +65,8 @@ <para> This is the &bz-ver; version of The Bugzilla Guide. It is so named to match the current version of Bugzilla. - <![%bz-devel;[ - This version of the guide, like its associated Bugzilla version, is a - development version. - ]]> + <!-- BZ-DEVEL --> This version of the guide, like its associated Bugzilla version, is a + development version.<!-- /BZ-DEVEL --> </para> <para> The latest version of this guide can always be found at <ulink @@ -82,18 +80,25 @@ <para> The Bugzilla Guide, or a section of it, is also available in the following languages: - <ulink url="http://bugzilla-de.sourceforge.net/docs/html/">German</ulink>. + <ulink url="http://www.traduc.org/docs/guides/lecture/bugzilla/">French</ulink>, + <ulink url="http://bugzilla-de.sourceforge.net/docs/html/">German</ulink>, + <ulink url="http://www.bugzilla.jp/docs/2.18/">Japanese</ulink>. + Note that these may be outdated or not up to date. </para> <para> - In addition, there are Bugzilla template localisation projects in + In addition, there are Bugzilla template localization projects in the following languages. They may have translated documentation available: + <ulink url="http://sourceforge.net/projects/bugzilla-ar/">Arabic</ulink>, <ulink url="http://sourceforge.net/projects/bugzilla-be/">Belarusian</ulink>, + <ulink url="http://openfmi.net/projects/mozilla-bg/">Bulgarian</ulink>, <ulink url="http://sourceforge.net/projects/bugzilla-br/">Brazilian Portuguese</ulink>, <ulink url="http://sourceforge.net/projects/bugzilla-cn/">Chinese</ulink>, <ulink url="http://sourceforge.net/projects/bugzilla-fr/">French</ulink>, - <ulink url="http://sourceforge.net/projects/bugzilla-de/">German</ulink>, + <ulink url="http://germzilla.wurblzap.net/">German</ulink>, + <ulink url="http://sourceforge.net/projects/bugzilla-it/">Italian</ulink>, + <ulink url="http://www.bugzilla.jp/about/jp.html">Japanese</ulink>, <ulink url="http://sourceforge.net/projects/bugzilla-kr/">Korean</ulink>, <ulink url="http://sourceforge.net/projects/bugzilla-ru/">Russian</ulink> and <ulink url="http://sourceforge.net/projects/bugzilla-es/">Spanish</ulink>. @@ -102,7 +107,7 @@ <para> If you would like to volunteer to translate the Guide into additional languages, please contact - <ulink url="mailto:justdave@syndicomm.com">Dave Miller</ulink>. + <ulink url="mailto:justdave@bugzilla.org">Dave Miller</ulink>. </para> </section> @@ -120,7 +125,7 @@ <varlistentry> <term>Matthew P. Barnson <email>mbarnson@sisna.com</email></term> <listitem> - <para>for the Herculaean task of pulling together the Bugzilla Guide + <para>for the Herculean task of pulling together the Bugzilla Guide and shepherding it to 2.14. </para> </listitem> @@ -204,9 +209,10 @@ <para> Also, thanks are due to the members of the - <ulink url="news://news.mozilla.org/netscape.public.mozilla.webtools"> - netscape.public.mozilla.webtools</ulink> - newsgroup. Without your discussions, insight, suggestions, and patches, + <ulink url="news://news.mozilla.org/mozilla.support.bugzilla"> + mozilla.support.bugzilla</ulink> + newsgroup (and its predecessor, netscape.public.mozilla.webtools). + Without your discussions, insight, suggestions, and patches, this could never have happened. </para> </section> diff --git a/docs/en/xml/customization.xml b/docs/en/xml/customization.xml index 4a832c614..824b88de9 100644 --- a/docs/en/xml/customization.xml +++ b/docs/en/xml/customization.xml @@ -1,7 +1,43 @@ <!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> <chapter id="customization"> - <title>Customising Bugzilla</title> + <title>Customizing Bugzilla</title> + <section id="cust-skins"> + <title>Custom Skins</title> + + <para> + Bugzilla allows you to have multiple skins. These are custom CSS and possibly + also custom images for Bugzilla. To create a new custom skin, you have two + choices: + <itemizedlist> + <listitem> + <para> + Make a single CSS file, and put it in the + <filename>skins/contrib</filename> directory. + </para> + </listitem> + <listitem> + <para> + Make a directory that contains all the same CSS file + names as <filename>skins/standard/</filename>, and put + your directory in <filename>skins/contrib/</filename>. + </para> + </listitem> + </itemizedlist> + </para> + + <para> + After you put the file or the directory there, make sure to run checksetup.pl + so that it can reset the file permissions correctly. + </para> + <para> + After you have installed the new skin, it will show up as an option in the + user's General Preferences. If you would like to force a particular skin on all + users, just select it in the Default Preferences and then uncheck "Enabled" on + the preference. + </para> + </section> + <section id="cust-templates"> <title>Template Customization</title> @@ -402,9 +438,9 @@ <para>After untarring the localizations (or creating your own) in the <filename class="directory">BUGZILLA_ROOT/template</filename> directory, you must update the <option>languages</option> parameter to contain any - localizations you'd like to permit. You may also wish to set the - <option>defaultlanguage</option> parameter to something other than - <quote>en</quote> if you don't want English to be the default language. + localizations you'd like to permit. You may also wish to re-order + the <option>languages</option> parameter so that <quote>en</quote> + doesn't come first, if you don't want English to be the default language. </para> </section> @@ -458,7 +494,7 @@ <para> To use hooks to extend Bugzilla, first make sure there is a hook at the appropriate place within the source file or template you - want to extend. The exact appearence of a hook depends on if the hook + want to extend. The exact appearance of a hook depends on if the hook is a code hook or a template hook. </para> @@ -754,344 +790,6 @@ </para> </section> - <section id="dbdoc"> - <title>MySQL Bugzilla Database Introduction</title> - - <para>This information comes straight from my life. I was forced to learn - how Bugzilla organizes database because of nitpicky requests from users - for tiny changes in wording, rather than having people re-educate - themselves or figure out how to work our procedures around the tool. It - sucks, but it can and will happen to you, so learn how the schema works - and deal with it when it comes.</para> - - <para>So, here you are with your brand-new installation of Bugzilla. - You've got MySQL set up, Apache working right, Perl DBI and DBD talking - to the database flawlessly. Maybe you've even entered a few test bugs to - make sure email's working; people seem to be notified of new bugs and - changes, and you can enter and edit bugs to your heart's content. Perhaps - you've gone through the trouble of setting up a gateway for people to - submit bugs to your database via email, have had a few people test it, - and received rave reviews from your beta testers.</para> - - <para>What's the next thing you do? Outline a training strategy for your - development team, of course, and bring them up to speed on the new tool - you've labored over for hours.</para> - - <para>Your first training session starts off very well! You have a - captive audience which seems enraptured by the efficiency embodied in - this thing called "Bugzilla". You are caught up describing the nifty - features, how people can save favorite queries in the database, set them - up as headers and footers on their pages, customize their layouts, - generate reports, track status with greater efficiency than ever before, - leap tall buildings with a single bound and rescue Jane from the clutches - of Certain Death!</para> - - <para>But Certain Death speaks up -- a tiny voice, from the dark corners - of the conference room. "I have a concern," the voice hisses from the - darkness, "about the use of the word 'verified'."</para> - - <para>The room, previously filled with happy chatter, lapses into - reverential silence as Certain Death (better known as the Vice President - of Software Engineering) continues. "You see, for two years we've used - the word 'verified' to indicate that a developer or quality assurance - engineer has confirmed that, in fact, a bug is valid. I don't want to - lose two years of training to a new software product. You need to change - the bug status of 'verified' to 'approved' as soon as possible. To avoid - confusion, of course."</para> - - <para>Oh no! Terror strikes your heart, as you find yourself mumbling - "yes, yes, I don't think that would be a problem," You review the changes - with Certain Death, and continue to jabber on, "no, it's not too big a - change. I mean, we have the source code, right? You know, 'Use the - Source, Luke' and all that... no problem," All the while you quiver - inside like a beached jellyfish bubbling, burbling, and boiling on a hot - Jamaican sand dune...</para> - - <para>Thus begins your adventure into the heart of Bugzilla. You've been - forced to learn about non-portable enum() fields, varchar columns, and - tinyint definitions. The Adventure Awaits You!</para> - - <section> - <title>Bugzilla Database Basics</title> - - <para>If you were like me, at this point you're totally clueless about - the internals of MySQL, and if it weren't for this executive order from - the Vice President you couldn't care less about the difference between - a - <quote>bigint</quote> - - and a - <quote>tinyint</quote> - - entry in MySQL. I recommend you refer to the - <ulink url="http://www.mysql.com/documentation/">MySQL documentation</ulink> - . Below are the basics you need to know about the Bugzilla database. - Check the chart above for more details.</para> - - <para> - <orderedlist> - <listitem> - <para>To connect to your database:</para> - - <para> - <prompt>bash#</prompt> - - <command>mysql</command> - - <parameter>-u root</parameter> - </para> - - <para>If this works without asking you for a password, - <emphasis>shame on you</emphasis> - - ! You should have locked your security down like the installation - instructions told you to. You can find details on locking down - your database in the Bugzilla FAQ in this directory (under - "Security"), or more robust security generalities in the - <ulink url="http://www.mysql.com/php/manual.php3?section=Privilege_system">MySQL - searchable documentation</ulink>. - </para> - </listitem> - - <listitem> - <para>You should now be at a prompt that looks like this:</para> - - <para> - <prompt>mysql></prompt> - </para> - - <para>At the prompt, if - <quote>bugs</quote> - - is the name you chose in the - <filename>localconfig</filename> - - file for your Bugzilla database, type:</para> - - <para> - <prompt>mysql</prompt> - - <command>use bugs;</command> - </para> - - </listitem> - </orderedlist> - </para> - - <section> - <title>Bugzilla Database Tables</title> - - <para>Imagine your MySQL database as a series of spreadsheets, and - you won't be too far off. If you use this command:</para> - - <para> - <prompt>mysql></prompt> - <command>show tables from bugs;</command> - </para> - - <para>you'll be able to see the names of all the - <quote>spreadsheets</quote> - (tables) in your database.</para> - - <para>From the command issued above, you should have some - output that looks like this: -<programlisting> -+-------------------+ -| Tables in bugs | -+-------------------+ -| attachments | -| bugs | -| bugs_activity | -| cc | -| components | -| dependencies | -| fielddefs | -| groups | -| keyworddefs | -| keywords | -| logincookies | -| longdescs | -| milestones | -| namedqueries | -| products | -| profiles | -| profiles_activity | -| tokens | -| user_group_map | -| versions | -| votes | -| watch | -+-------------------+ -</programlisting> -</para> - -<literallayout> - Here's an overview of what each table does. Most columns in each table have -descriptive names that make it fairly trivial to figure out their jobs. - -attachments: This table stores all attachments to bugs. It tends to be your -largest table, yet also generally has the fewest entries because file -attachments are so (relatively) large. - -bugs: This is the core of your system. The bugs table stores most of the -current information about a bug, with the exception of the info stored in the -other tables. - -bugs_activity: This stores information regarding what changes are made to bugs -when -- a history file. - -cc: This tiny table simply stores all the CC information for any bug which has -any entries in the CC field of the bug. Note that, like most other tables in -Bugzilla, it does not refer to users by their user names, but by their unique -userid, stored as a primary key in the profiles table. - -components: This stores the programs and components (or products and -components, in newer Bugzilla parlance) for Bugzilla. Curiously, the "program" -(product) field is the full name of the product, rather than some other unique -identifier, like bug_id and user_id are elsewhere in the database. - -dependencies: Stores data about those cool dependency trees. - -fielddefs: A nifty table that defines other tables. For instance, when you -submit a form that changes the value of "AssignedTo" this table allows -translation to the actual field name "assigned_to" for entry into MySQL. - -groups: defines bitmasks for groups. A bitmask is a number that can uniquely -identify group memberships. For instance, say the group that is allowed to -tweak parameters is assigned a value of "1", the group that is allowed to edit -users is assigned a "2", and the group that is allowed to create new groups is -assigned the bitmask of "4". By uniquely combining the group bitmasks (much -like the chmod command in UNIX,) you can identify a user is allowed to tweak -parameters and create groups, but not edit users, by giving him a bitmask of -"5", or a user allowed to edit users and create groups, but not tweak -parameters, by giving him a bitmask of "6" Simple, huh? - If this makes no sense to you, try this at the mysql prompt: -mysql> select * from groups; - You'll see the list, it makes much more sense that way. - -keyworddefs: Definitions of keywords to be used - -keywords: Unlike what you'd think, this table holds which keywords are -associated with which bug id's. - -logincookies: This stores every login cookie ever assigned to you for every -machine you've ever logged into Bugzilla from. Curiously, it never does any -housecleaning -- I see cookies in this file I've not used for months. However, -since Bugzilla never expires your cookie (for convenience' sake), it makes -sense. - -longdescs: The meat of bugzilla -- here is where all user comments are stored! -You've only got 2^24 bytes per comment (it's a mediumtext field), so speak -sparingly -- that's only the amount of space the Old Testament from the Bible -would take (uncompressed, 16 megabytes). Each comment is keyed to the -bug_id to which it's attached, so the order is necessarily chronological, for -comments are played back in the order in which they are received. - -milestones: Interesting that milestones are associated with a specific product -in this table, but Bugzilla does not yet support differing milestones by -product through the standard configuration interfaces. - -namedqueries: This is where everybody stores their "custom queries". Very -cool feature; it beats the tar out of having to bookmark each cool query you -construct. - -products: What products you have, whether new bug entries are allowed for the -product, what milestone you're working toward on that product, votes, etc. It -will be nice when the components table supports these same features, so you -could close a particular component for bug entry without having to close an -entire product... - -profiles: This table contains details for the current user accounts, -including the crypted hashes of the passwords used, the associated -login names, and the real name of the users. - -profiles_activity: Need to know who did what when to who's profile? This'll -tell you, it's a pretty complete history. - -user_group_map: This table stores which user belongs to which group, -whether the user can bless others, and how the users obtained the -membership of the group. - -versions: Version information for every product - -votes: Who voted for what when - -watch: Who (according to userid) is watching who's bugs (according to their -userid). - - -=== -THE DETAILS -=== - - Ahh, so you're wondering just what to do with the information above? At the -mysql prompt, you can view any information about the columns in a table with -this command (where "table" is the name of the table you wish to view): - -mysql> show columns from table; - - You can also view all the data in a table with this command: - -mysql> select * from table; - - -- note: this is a very bad idea to do on, for instance, the "bugs" table if -you have 50,000 bugs. You'll be sitting there a while until you ctrl-c or -50,000 bugs play across your screen. - - You can limit the display from above a little with the command, where -"column" is the name of the column for which you wish to restrict information: - -mysql> select * from table where (column = "some info"); - - -- or the reverse of this - -mysql> select * from table where (column != "some info"); - - Let's take our example from the introduction, and assume you need to change -the word "verified" to "approved" in the resolution field. We know from the -above information that the resolution is likely to be stored in the "bugs" -table. Note we'll need to change a little perl code as well as this database -change, but I won't plunge into that in this document. Let's verify the -information is stored in the "bugs" table: - -mysql> show columns from bugs - - (exceedingly long output truncated here) -| bug_status| enum('UNCONFIRMED','NEW','ASSIGNED','REOPENED','RESOLVED','VERIFIED','CLOSED')||MUL | UNCONFIRMED|| - - Sorry about that long line. We see from this that the "bug status" column is -an "enum field", which is a MySQL peculiarity where a string type field can -only have certain types of entries. While I think this is very cool, it's not -standard SQL. Anyway, we need to add the possible enum field entry -'APPROVED' by altering the "bugs" table. - -mysql> ALTER table bugs CHANGE bug_status bug_status - -> enum("UNCONFIRMED", "NEW", "ASSIGNED", "REOPENED", "RESOLVED", - -> "VERIFIED", "APPROVED", "CLOSED") not null; - - (note we can take three lines or more -- whatever you put in before the -semicolon is evaluated as a single expression) - -Now if you do this: - -mysql> show columns from bugs; - - you'll see that the bug_status field has an extra "APPROVED" enum that's -available! Cool thing, too, is that this is reflected on your query page as -well -- you can query by the new status. But how's it fit into the existing -scheme of things? - Looks like you need to go back and look for instances of the word "verified" -in the perl code for Bugzilla -- wherever you find "verified", change it to -"approved" and you're in business (make sure that's a case-insensitive search). -Although you can query by the enum field, you can't give something a status -of "APPROVED" until you make the perl changes. Note that this change I -mentioned can also be done by editing checksetup.pl, which automates a lot of -this. But you need to know this stuff anyway, right? - </literallayout> - </section> - </section> - </section> - <!-- Integrating Bugzilla with Third-Party Tools --> &integration; diff --git a/docs/en/xml/introduction.xml b/docs/en/xml/introduction.xml index 5cf4a5599..3968702c6 100644 --- a/docs/en/xml/introduction.xml +++ b/docs/en/xml/introduction.xml @@ -68,7 +68,7 @@ </listitem> <listitem> - <para>Completely customisable and/or localisable web user + <para>Completely customizable and/or localizable web user interface</para> </listitem> diff --git a/docs/en/xml/patches.xml b/docs/en/xml/patches.xml index 31d867e86..12efb0ca4 100644 --- a/docs/en/xml/patches.xml +++ b/docs/en/xml/patches.xml @@ -1,481 +1,113 @@ -<!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> - +<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> --> <appendix id="patches" xreflabel="Useful Patches and Utilities for Bugzilla"> - <title>Useful Patches and Utilities for Bugzilla</title> - - <para>Are you looking for a way to put your Bugzilla into overdrive? Catch some of the niftiest tricks here in this section.</para> - - <section id="rewrite" xreflabel="Apache mod_rewrite magic"> - <title>Apache <filename>mod_rewrite</filename> magic</title> - <para>Apache's <filename>mod_rewrite</filename> module lets you do some truly amazing things with URL rewriting. Here are a couple of examples of what you can do.</para> - <orderedlist> - <listitem> - <para> - Make it so if someone types - <computeroutput>http://www.foo.com/12345</computeroutput>, - 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:</para> - <programlisting> -<![CDATA[ -<VirtualHost 12.34.56.78> -RewriteEngine On -RewriteRule ^/([0-9]+)$ http://foo.bar.com/show_bug.cgi?id=$1 [L,R] -</VirtualHost> -]]> - </programlisting> + <title>Contrib</title> - </listitem> - <listitem> - <para>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 <ulink - url="http://www.apache.org">http://www.apache.org</ulink></para> - </listitem> - </orderedlist> - </section> - -<section id="setperl" xreflabel="The setperl.csh Utility"> - <title>The setperl.csh Utility</title> - <para> 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! - </para> - <procedure> - <step> - <para> - Download the "setperl.csh" utility to your Bugzilla - directory and make it executable. - </para> - <substeps> - <step> - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>cd /your/path/to/bugzilla</command> - </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> <prompt>bash#</prompt> <command>wget -O - setperl.csh - 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=10795'</command> </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> <prompt>bash#</prompt> <command>chmod - u+x setperl.csh</command> </computeroutput> - </para> - </step> - </substeps> - </step> - <step> - <para> - Prepare (and fix) Bugzilla file permissions. - </para> - <substeps> - <step> - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>chmod u+w *</command> - </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> <prompt>bash#</prompt> <command>chmod - u+x duplicates.cgi</command> </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> - <prompt>bash#</prompt> - <command>chmod a-x bug_status.html</command> - </computeroutput> - </para> - </step> - </substeps> - </step> - <step> - <para> - Run the script: - </para> - <para> - <computeroutput> <prompt>bash#</prompt> - <command>./setperl.csh /your/path/to/perl</command> - </computeroutput> -<example> - <title>Using Setperl to set your perl path</title> - <para> - <computeroutput> <prompt>bash#</prompt> - <command>./setperl.csh /usr/bin/perl</command> - </computeroutput> - </para> - </example> - </para> - </step> - </procedure> - </section> + <para> + There are a number of unofficial Bugzilla add-ons in the + <filename class="directory">$BUGZILLA_ROOT/contrib/</filename> + directory. This section documents them. + </para> <section id="cmdline"> - <title>Command-line Bugzilla Queries</title> + <title>Command-line Search Interface</title> + <para> - Users can query Bugzilla from the command line using this suite - of utilities. + There are a suite of Unix utilities for searching Bugzilla from the + command line. They live in the + <filename class="directory">contrib/cmdline</filename> directory. + There are three files - <filename>query.conf</filename>, + <filename>buglist</filename> and <filename>bugs</filename>. </para> + + <warning> + <para> + These files pre-date the templatization work done as part of the + 2.16 release, and have not been updated. + </para> + </warning> + <para> - 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" + <filename>query.conf</filename> contains the mapping from + options to field names and comparison types. Quoted option names + are <quote>grepped</quote> 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 <quote>option</quote>. </para> + <para> - 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=". + <filename>buglist</filename> is a shell script that submits a + Bugzilla query and writes the resulting HTML page to stdout. + It supports both short options, (such as <quote>-Afoo</quote> + or <quote>-Rbar</quote>) and long options (such + as <quote>--assignedto=foo</quote> or <quote>--reporter=bar</quote>). + If the first character of an option is not <quote>-</quote>, it is + treated as if it were prefixed with <quote>--default=</quote>. </para> + <para> - 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 - <command>grep COLUMLIST ~/.netscape/cookies</command> to see - your current COLUMNLIST setting. + The column list is taken from the COLUMNLIST environment variable. + This is equivalent to the <quote>Change Columns</quote> option + that is available when you list bugs in buglist.cgi. If you have + already used Bugzilla, grep for COLUMNLIST in your cookies file + to see your current COLUMNLIST setting. </para> + <para> - 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 <command>sed -e 's/,/ /g' | wc | - awk '{printf $2 "\n"}'</command> + <filename>bugs</filename> is a simple shell script which calls + <filename>buglist</filename> and extracts the + bug numbers from the output. Adding the prefix + <quote>http://bugzilla.mozilla.org/buglist.cgi?bug_id=</quote> + turns the bug list into a working link if any bugs are found. + Counting bugs is easy. Pipe the results through + <command>sed -e 's/,/ /g' | wc | awk '{printf $2 "\n"}'</command> </para> + <para> - Akkana says she has good results piping buglist output through + Akkana Peck says she has good results piping + <filename>buglist</filename> output through <command>w3m -T text/html -dump</command> </para> - <procedure> - <step> - <para> - Download three files: - </para> - <substeps> - <step> - <para> - <computeroutput> <prompt>bash$</prompt> <command>wget -O - query.conf - 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26157'</command> </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> <prompt>bash$</prompt> <command>wget -O - buglist - 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26944'</command> </computeroutput> - </para> - </step> - <step> - <para> - <computeroutput> <prompt>bash#</prompt> <command>wget -O - bugs - 'http://bugzilla.mozilla.org/showattachment.cgi?attach_id=26215'</command> </computeroutput> - </para> - </step> - </substeps> - </step> - <step> - <para> - Make your utilities executable: - <computeroutput> - <prompt>bash$</prompt> - <command>chmod u+x buglist bugs</command> - </computeroutput> - </para> - </step> - </procedure> + </section> - <section id="quicksearch"> - <title>The Quicksearch Utility</title> - <para> - 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" - </para> - <para> - The index.html page has been updated to include the QuickSearch - text box. - </para> - <para> - 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. - </para> + <section id="cmdline-bugmail"> + <title>Command-line 'Send Unsent Bug-mail' tool</title> + <para> - 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". + Within the <filename class="directory">contrib</filename> directory + exists a utility with the descriptive (if compact) name + of <filename>sendunsentbugmail.pl</filename>. The purpose of this + script is, simply, to send out any bug-related mail that should + have been sent by now, but for one reason or another has not. </para> + <para> - Workarounds for Bugzilla users: - <simplelist> - <member>search for '!foo' (this will find only bugs with the - keyword "foo"</member> - <member>search 'foo,!foo' (equivalent to 'foo OR - keyword:foo')</member> - </simplelist> + To accomplish this task, <filename>sendunsentbugmail.pl</filename> uses + the same mechanism as the <filename>sanitycheck.cgi</filename> script; + it scans through the entire database looking for bugs with changes that + were made more than 30 minutes ago, but where there is no record of + anyone related to that bug having been sent mail. Having compiled a list, + it then uses the standard rules to determine who gets mail, and sends it + out. </para> + <para> - When this tool is ported from client-side JavaScript to - server-side Perl, the requirement for hard-coding keywords can - be fixed. <ulink - url="http://bugzilla.mozilla.org/show_bug.cgi?id=70907">This bug</ulink> has details. + As the script runs, it indicates the bug for which it is currently + sending mail; when it has finished, it gives a numerical count of how + many mails were sent and how many people were excluded. (Individual + user names are not recorded or displayed.) If the script produces + no output, that means no unsent mail was detected. </para> - </section> - <section id="bzhacking"> - <title>Hacking Bugzilla</title> <para> - 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. + <emphasis>Usage</emphasis>: move the sendunsentbugmail.pl script + up into the main directory, ensure it has execute permission, and run it + from the command line (or from a cron job) with no parameters. </para> - <section> - <title>Things that have caused problems and should be avoided</title> - <orderedlist> - <listitem> - <para> - Usage of variables in Regular Expressions - </para> - <para> - 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: - </para> - <para> - <programlisting> -grep ($_ eq $value, @array); - </programlisting> - </para> - <para> - -- NOT THIS -- - </para> - <para> - <programlisting> -grep (/$value/, @array); - </programlisting> - </para> - <note> - <para> - If you need to use a non-expression variable inside of an expression, be - sure to quote it properly (using <function>\Q..\E</function>). - </para> - </note> - </listitem> - </orderedlist> - </section> - <section> - <title>Coding Style for Bugzilla</title> - <para> - 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 :). - </para> - <para> - The Bugzilla development team has decided to adopt the perl style guide as - published by Larry Wall. This giude can be found in <quote>Programming - Perl</quote> (the camel book) or by typing <command>man perlstyle</command> at - your favorite shell prompt. - </para> - <para> - 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. - </para> - <itemizedlist> - <listitem> - <para> - Whitespace - </para> - <para> - Bugzilla's preferred indentation is 4 spaces (no tabs, please). - </para> - </listitem> - <listitem> - <para> - Curly braces. - </para> - <para> - 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: - </para> - <para> - <programlisting> -if ($var) { - print "The variable is true"; -} -else { - print "Try again"; -} - </programlisting> - </para> - <para> - -- NOT THIS -- - </para> - <para> - <programlisting> -if ($var) -{ - print "The variable is true"; -} -else -{ - print "Try again"; -} - </programlisting> - </para> - </listitem> - - <listitem> - <para> - Cookies - </para> - <para> - Bugzilla uses cookies to ease the user experience, but no new patches - should <emphasis>require</emphasis> user-side cookies. - </para> - </listitem> - - <listitem> - <para> - File Names - </para> - <para> - File names for bugzilla code and support documention should be legal across - multiple platforms. <computeroutput>\ / : * ? " < ></computeroutput> - and <computeroutput>|</computeroutput> 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. - </para> - </listitem> - - <listitem> - <para> - Javascript dependencies - </para> - <para> - While Bugzilla uses Javascript to make the user experience easier, no patch - to Bugzilla should <emphasis>require</emphasis> Javascript. - </para> - </listitem> - - <listitem> - <para> - Patch Format - </para> - <para> - All patches submitted for inclusion into Bugzilla should be in the form of a - <quote>unified diff</quote>. This comes from using <quote>diff -u</quote> - instead of simply <quote>diff</quote> when creating your patch. This will - result in quicker acceptance of the patch. - </para> - </listitem> - - <listitem> - <para> - Schema Changes - </para> - <para> - If you make schema changes, you should modify <filename>sanitycheck.cgi</filename> - to support the new schema. All referential columns should be checked. - </para> - </listitem> - - <listitem> - <para> - Taint Mode - </para> - <para> - 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. - </para> - </listitem> - - <listitem> - <para> - Templatization - </para> - <para> - Patches to Bugzilla need to support templates so they do not force user interface choices - on Bugzilla administrators. - </para> - </listitem> - - <listitem> - <para> - Variable Names - </para> - <para> - If a variable is scoped globally (<computeroutput>$::variable</computeroutput>) - 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, - <computeroutput>$ret</computeroutput> could be used as a staging variable for a - routine's return value as the line <computeroutput>return $ret;</computeroutput> - will make it blatantly obvious what the variable holds and most likely be shown - on the same screen as <computeroutput>my $ret = "";</computeroutput>. - </para> - </listitem> - - <listitem> - <para> - Cross Database Compatability - </para> - <para> - 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 - <function>encrypt()</function>. - </para> - </listitem> - <listitem> - <para> - Cross Platform Compatability - </para> - <para> - 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. - </para> - </listitem> - </itemizedlist> - </section> </section> </appendix> - <!-- Keep this comment at the end of the file Local variables: mode: sgml @@ -491,8 +123,9 @@ sgml-local-ecat-files:nil sgml-minimize-attributes:nil sgml-namecase-general:t sgml-omittag:t -sgml-parent-document:("Bugzilla-Guide.sgml" "book" "chapter") +sgml-parent-document:("Bugzilla-Guide.xml" "book" "chapter") sgml-shorttag:t sgml-tag-region-if-active:t End: --> + diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml index 6d2b86a94..3c200a30a 100644 --- a/docs/en/xml/using.xml +++ b/docs/en/xml/using.xml @@ -72,7 +72,7 @@ <para> By default, you have 3 days to confirm your registration. Past this timeframe, the token is invalidated and the registration is - automatically cancelled. You can also cancel this registration sooner + automatically canceled. You can also cancel this registration sooner by using the appropriate URL in the email you got. </para> </listitem> @@ -243,7 +243,7 @@ <listitem> <para> <emphasis>Priority:</emphasis> - The bug assignee uses this field to prioritise his or her bugs. + The bug assignee uses this field to prioritize his or her bugs. It's a good idea not to change this on other people's bugs.</para> </listitem> @@ -402,8 +402,8 @@ have them show up in your personal Bugzilla footer along with your own Saved Searches. If somebody is sharing a Search with a group she or he is allowed to - <link linkend="groups">assign users to</link>, it will show up in the - group's direct members' footers by default. + <link linkend="groups">assign users to</link>, the sharer may opt to have + the Search show up in the group's direct members' footers by default. </para> <section id="boolean"> @@ -458,7 +458,7 @@ to whom each bug is assigned). When the operator is either "equals" or "notequals", the value can be "%reporter%", "%assignee%", "%qacontact%", or "%user%." The user pronoun - referes to the user who is executing the query or, in the case + refers to the user who is executing the query or, in the case of whining reports, the user who will be the recipient of the report. The reporter, assignee, and qacontact pronouns refer to the corresponding fields in the bug. @@ -1064,7 +1064,7 @@ <section id="userpreferences"> <title>User Preferences</title> - <para>Once you have logged in, you can customise various aspects of + <para>Once you have logged in, you can customize various aspects of Bugzilla via the "Edit prefs" link in the page footer. The preferences are split into three tabs:</para> |