Skip to content

bugzilla
bugzilla
Commit d8c3c733 authored by timeless%mozdev.org's avatar timeless%mozdev.org
Browse files
Options

Bug 364361 The word "Customising" in chapter 6 title is spelled wrong in all documentation

r=colin.ogilvie, kevin.benton
parent fcece8cd
Show whitespace changes
Inline Side-by-side
Showing with 147 additions and 810 deletions
docs/en/rel_notes.txt
View file @ d8c3c733
......@@ -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)
......
docs/en/xml/about.xml
View file @ d8c3c733
<!-- <!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>
......
docs/en/xml/customization.xml
View file @ d8c3c733
<!-- <!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&gt;</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&gt;</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;
......
docs/en/xml/introduction.xml
View file @ d8c3c733
......@@ -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>
......
docs/en/xml/patches.xml
View file @ d8c3c733
<!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>
There are a number of unofficial Bugzilla add-ons in the
<filename class="directory">$BUGZILLA_ROOT/contrib/</filename>
directory. This section documents them.
</para>
</example>
</para>
</step>
</procedure>
</section>
<section id="cmdline">
<title>Command-line Bugzilla Queries</title>
<para>
Users can query Bugzilla from the command line using this suite
of utilities.
</para>
<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"
</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=".
</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.
</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>
</para>
<para>
Akkana says she has good results piping buglist 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>
<title>Command-line Search Interface</title>
<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.
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>
<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".
</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>
</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.
</para>
</section>
<section id="bzhacking">
<title>Hacking Bugzilla</title>
<warning>
<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.
These files pre-date the templatization work done as part of the
2.16 release, and have not been updated.
</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>
</warning>
<listitem>
<para>
Cookies
</para>
<para>
Bugzilla uses cookies to ease the user experience, but no new patches
should <emphasis>require</emphasis> user-side cookies.
<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>
</listitem>
<listitem>
<para>
File Names
<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>
File names for bugzilla code and support documention should be legal across
multiple platforms. <computeroutput>\ / : * ? &quot; &lt; &gt;</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.
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>
</listitem>
<listitem>
<para>
Patch Format
<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>
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.
Akkana Peck says she has good results piping
<filename>buglist</filename> output through
<command>w3m -T text/html -dump</command>
</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>
</section>
<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>
<section id="cmdline-bugmail">
<title>Command-line 'Send Unsent Bug-mail' tool</title>
<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>.
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>
</listitem>
<listitem>
<para>
Cross Database Compatability
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>
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
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>
<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.
<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>
</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:
-->
docs/en/xml/using.xml
View file @ d8c3c733
......@@ -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>
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment