<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
<chapter id="customization">
- <title>Customizing Bugzilla</title>
+ <title>Customising Bugzilla</title>
<section id="cust-skins">
<title>Custom Skins</title>
<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 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.
+ 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.
</para>
</section>
<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 appearance of a hook depends on if the hook
+ want to extend. The exact appearence of a hook depends on if the hook
is a code hook or a template hook.
</para>
</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;
projects / thirdparty / bugzilla.git / commitdiff
