Bug 233523: Remove the obsolete section about MySQL and enum() fields - Patch by Frédéric Buclin <LpSolit@gmail.com> r=justdave

1 files changed, 0 insertions, 338 deletions

diff --git a/docs/xml/customization.xml b/docs/xml/customization.xml
index 20924f5f5..180021468 100644
--- a/docs/xml/customization.xml
+++ b/docs/xml/customization.xml
@@ -790,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;