List:Commits« Previous MessageNext Message »
From:paul Date:January 4 2006 4:12am
Subject:svn commit - mysqldoc@docsrva: r661 - in trunk: . refman-common
View as plain text  
Author: paul
Date: 2006-01-04 05:12:52 +0100 (Wed, 04 Jan 2006)
New Revision: 661

Log:
 r5803@frost:  paul | 2006-01-03 21:41:00 -0600
 The bug report procedure isn't an "information source." Promote the
 section up a level.


Added:
   trunk/refman-common/bug-reports.xml
Modified:
   trunk/
   trunk/refman-common/information-sources.xml


Property changes on: trunk
___________________________________________________________________
Name: svk:merge
   - b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:5801
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1848
   + b5ec3a16-e900-0410-9ad2-d183a3acac99:/mysqldoc-local/mysqldoc/trunk:5803
bf112a9c-6c03-0410-a055-ad865cd57414:/mysqldoc-local/mysqldoc/trunk:1848

Added: trunk/refman-common/bug-reports.xml
===================================================================
--- trunk/refman-common/bug-reports.xml	2006-01-04 03:49:42 UTC (rev 660)
+++ trunk/refman-common/bug-reports.xml	2006-01-04 04:12:52 UTC (rev 661)
@@ -0,0 +1,615 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % fixedchars.entities  SYSTEM "fixedchars.ent">
+  %fixedchars.entities;
+  <!ENTITY % title.entities       SYSTEM "titles.en.ent">
+  %title.entities;
+]>
+<section id="bug-reports">
+
+  <title>&title-bug-reports;</title>
+
+  <indexterm type="concept">
+    <primary>reporting</primary>
+    <secondary>errors</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>errors</primary>
+    <secondary>reporting</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>searching</primary>
+    <secondary>MySQL Web pages</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>bug reports</primary>
+    <secondary>criteria for</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>bugs</primary>
+    <secondary>reporting</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>reporting</primary>
+    <secondary>bugs</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>problems</primary>
+    <secondary>reporting</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>errors</primary>
+    <secondary>reporting</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>creating</primary>
+    <secondary>bug reports</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>bugs.mysql.com</primary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>bugs database</primary>
+  </indexterm>
+
+  <para>
+    Before posting a bug report about a problem, please try to verify
+    that it is a bug and that it has not been reported already:
+  </para>
+
+  <itemizedlist>
+
+    <listitem>
+      <para>
+        Start by searching the MySQL online manual at
+        <ulink url="&base-url-docs;"/>. We try to keep the manual up to
+        date by updating it frequently with solutions to newly found
+        problems. The change history
+        (<ulink url="&base-url-docs;mysql/en/news.html"/>) can be
+        particularly useful since it is quite possible that a newer
+        version contains a solution to your problem.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If you get a parse error for a SQL statement, please check your
+        syntax closely. If you can't find something wrong with it, it's
+        extremely likely that your current version of MySQL Server
+        doesn't support the syntax you are using. If you are using the
+        current version and the manual doesn't cover the syntax that you
+        are using, MySQL Server doesn't support your statement. In this
+        case, your options are to implement the syntax yourself or email
+        <email>licensing@stripped</email> and ask for an offer to
+        implement it.
+      </para>
+
+      <para>
+        If the manual covers the syntax you are using, but you have an
+        older version of MySQL Server, you should check the MySQL change
+        history to see when the syntax was implemented. In this case,
+        you have the option of upgrading to a newer version of MySQL
+        Server.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        For solutions to some common problems, see
+        <xref linkend="problems"/>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Search the bugs database at
+        <ulink url="http://bugs.mysql.com/"/> to see whether the bug has
+        been reported and fixed.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Search the MySQL mailing list archives at
+        <ulink url="http://lists.mysql.com/"/>. See
+        <xref linkend="mailing-lists"/>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        You can also use <ulink url="http://www.mysql.com/search/"/> to
+        search all the Web pages (including the manual) that are located
+        at the MySQL AB Web site.
+      </para>
+    </listitem>
+
+  </itemizedlist>
+
+  <para>
+    If you can't find an answer in the manual, the bugs database, or the
+    mailing list archives, check with your local MySQL expert. If you
+    still can't find an answer to your question, please use the
+    following guidelines for reporting the bug.
+  </para>
+
+  <para>
+    The normal way to report bugs is to visit
+    <ulink url="http://bugs.mysql.com/"/>, which is the address for our
+    bugs database. This database is public and can be browsed and
+    searched by anyone. If you log in to the system, you can enter new
+    reports. If you have no Web access, you can generate a bug report by
+    using the <command>mysqlbug</command> script described at the end of
+    this section.
+  </para>
+
+  <para>
+    All bugs posted in the bugs database at
+    <ulink url="http://bugs.mysql.com/"/> are corrected or documented in
+    the next MySQL release. If only minor code changes are needed to
+    correct a problem, we may also post a patch that fixes the problem.
+  </para>
+
+  <para>
+    If you have found a sensitive security bug in MySQL, you can send
+    email to <email>security@stripped</email>.
+  </para>
+
+  <para>
+    To discuss problems with other users, you can use one of the MySQL
+    mailing lists. <xref linkend="mailing-lists"/>.
+  </para>
+
+  <para>
+    Writing a good bug report takes patience, but doing it right the
+    first time saves time both for us and for yourself. A good bug
+    report, containing a full test case for the bug, makes it very
+    likely that we will fix the bug in the next release. This section
+    helps you write your report correctly so that you don't waste your
+    time doing things that may not help us much or at all. Please read
+    this section carefully and make sure that all the information
+    described here is included in your report.
+  </para>
+
+  <para>
+    Preferably, you should test the problem using the latest production
+    or development version of MySQL Server before posting. Anyone should
+    be able to repeat the bug by just using <literal>mysql test &lt;
+    script_file</literal> on your test case or by running the shell or
+    Perl script that you include in the bug report. Any bug that we are
+    able to repeat has a high chance of being fixed in the next MySQL
+    release.
+  </para>
+
+  <para>
+    It is most helpful when a good description of the problem is
+    included in the bug report. That is, give a good example of
+    everything you did that led to the problem and describe, in exact
+    detail, the problem itself. The best reports are those that include
+    a full example showing how to reproduce the bug or problem. See
+    <xref linkend="reproduceable-test-case"/>.
+  </para>
+
+  <para>
+    Remember that it is possible for us to respond to a report
+    containing too much information, but not to one containing too
+    little. People often omit facts because they think they know the
+    cause of a problem and assume that some details don't matter. A good
+    principle to follow is that if you are in doubt about stating
+    something, state it. It is faster and less troublesome to write a
+    couple more lines in your report than to wait longer for the answer
+    if we must ask you to provide information that was missing from the
+    initial report.
+  </para>
+
+  <para>
+    The most common errors made in bug reports are (a) not including the
+    version number of the MySQL distribution that you use, and (b) not
+    fully describing the platform on which the MySQL server is installed
+    (including the platform type and version number). These are highly
+    relevant pieces of information, and in 99 cases out of 100, the bug
+    report is useless without them. Very often we get questions like,
+    <quote>Why doesn't this work for me?</quote> Then we find that the
+    feature requested wasn't implemented in that MySQL version, or that
+    a bug described in a report has been fixed in newer MySQL versions.
+    Errors often are platform-dependent. In such cases, it is next to
+    impossible for us to fix anything without knowing the operating
+    system and the version number of the platform.
+  </para>
+
+  <para>
+    If you compiled MySQL from source, remember also to provide
+    information about your compiler if it is related to the problem.
+    Often people find bugs in compilers and think the problem is
+    MySQL-related. Most compilers are under development all the time and
+    become better version by version. To determine whether your problem
+    depends on your compiler, we need to know what compiler you used.
+    Note that every compiling problem should be regarded as a bug and
+    reported accordingly.
+  </para>
+
+  <para>
+    If a program produces an error message, it is very important to
+    include the message in your report. If we try to search for
+    something from the archives, it is better that the error message
+    reported exactly matches the one that the program produces. (Even
+    the lettercase should be observed.) It is best to copy and paste the
+    entire error message into your report. You should never try to
+    reproduce the message from memory.
+  </para>
+
+  <para>
+    If you have a problem with Connector/ODBC (MyODBC), please try to
+    generate a trace file and send it with your report. See
+    <xref linkend="myodbc-bug-report"/>.
+  </para>
+
+  <para>
+    If your report includes long query output lines from test cases that
+    you run with the <command>mysql</command> command-line tool, you can
+    make the output more readable by using the
+    <option>--vertical</option> option or the <literal>\G</literal>
+    statement terminator. The <literal>EXPLAIN SELECT</literal> example
+    later in this section demonstrates the use of <literal>\G</literal>.
+  </para>
+
+  <para>
+    Please include the following information in your report:
+  </para>
+
+  <itemizedlist>
+
+    <listitem>
+      <para>
+        The version number of the MySQL distribution you are using (for
+        example, MySQL 5.0.19). You can find out which version you are
+        running by executing <command>mysqladmin version</command>. The
+        <command>mysqladmin</command> program can be found in the
+        <filename>bin</filename> directory under your MySQL installation
+        directory.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        The manufacturer and model of the machine on which you
+        experience the problem.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        The operating system name and version. If you work with Windows,
+        you can usually get the name and version number by
+        double-clicking your My Computer icon and pulling down the
+        <quote>Help/About Windows</quote> menu. For most Unix-like
+        operating systems, you can get this information by executing the
+        command <literal>uname -a</literal>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Sometimes the amount of memory (real and virtual) is relevant.
+        If in doubt, include these values.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If you are using a source distribution of the MySQL software,
+        include the name and version number of the compiler that you
+        used. If you have a binary distribution, include the
+        distribution name.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If the problem occurs during compilation, include the exact
+        error messages and also a few lines of context around the
+        offending code in the file where the error occurs.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If <command>mysqld</command> died, you should also report the
+        statement that crashed <command>mysqld</command>. You can
+        usually get this information by running
+        <command>mysqld</command> with query logging enabled, and then
+        looking in the log after <command>mysqld</command> crashes See
+        <xref linkend="using-log-files"/>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If a database table is related to the problem, include the
+        output from the <literal>SHOW CREATE TABLE
+        <replaceable>db_name</replaceable>.<replaceable>tbl_name</replaceable></literal>
+        statement in the bug report. This is a very easy way to get the
+        definition of any table in a database. The information helps us
+        create a situation matching the one that you have experienced.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        For performance-related bugs or problems with
+        <literal>SELECT</literal> statements, you should always include
+        the output of <literal>EXPLAIN SELECT ...</literal>, and at
+        least the number of rows that the <literal>SELECT</literal>
+        statement produces. You should also include the output from
+        <literal>SHOW CREATE TABLE
+        <replaceable>tbl_name</replaceable></literal> for each table
+        that is involved. The more information you provide about your
+        situation, the more likely it is that someone can help you.
+      </para>
+
+      <para>
+        The following is an example of a very good bug report. The
+        statements are run using the <command>mysql</command>
+        command-line tool. Note the use of the <literal>\G</literal>
+        statement terminator for statements that would otherwise provide
+        very long output lines that are difficult to read.
+      </para>
+
+<programlisting>
+mysql&gt; <userinput>SHOW VARIABLES;</userinput>
+mysql&gt; <userinput>SHOW COLUMNS FROM ...\G</userinput>
+       <replaceable>&lt;output from SHOW COLUMNS&gt;</replaceable>
+mysql&gt; <userinput>EXPLAIN SELECT ...\G</userinput>
+       <replaceable>&lt;output from EXPLAIN&gt;</replaceable>
+mysql&gt; <userinput>FLUSH STATUS;</userinput>
+mysql&gt; <userinput>SELECT ...;</userinput>
+       <replaceable>&lt;A short version of the output from SELECT,
+       including the time taken to run the query&gt;</replaceable>
+mysql&gt; <userinput>SHOW STATUS;</userinput>
+       <replaceable>&lt;output from SHOW STATUS&gt;</replaceable>
+</programlisting>
+    </listitem>
+
+    <listitem>
+      <para>
+        If a bug or problem occurs while running
+        <command>mysqld</command>, try to provide an input script that
+        reproduces the anomaly. This script should include any necessary
+        source files. The more closely the script can reproduce your
+        situation, the better. If you can make a reproducible test case,
+        you should upload it to be attached to the bug report.
+      </para>
+
+      <para>
+        If you can't provide a script, you should at least include the
+        output from <command>mysqladmin variables extended-status
+        processlist</command> in your report to provide some information
+        on how your system is performing.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If you can't produce a test case with only a few rows, or if the
+        test table is too big to be included in the bug report (more
+        than 10 rows), you should dump your tables using
+        <command>mysqldump</command> and create a
+        <filename>README</filename> file that describes your problem.
+        Create a compressed archive of your files using
+        <command>tar</command> and <command>gzip</command> or
+        <command>zip</command>, and use FTP to transfer the archive to
+        <ulink url="ftp://ftp.mysql.com/pub/mysql/upload/"/>. Then enter
+        the problem into our bugs database at
+        <ulink url="http://bugs.mysql.com/"/>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If you believe that the MySQL server produces a strange result
+        from a statement, include not only the result, but also your
+        opinion of what the result should be, and an explanation
+        describing the basis for your opinion.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        When you provide an example of the problem, it's better to use
+        the table names, variable names, and so forth that exist in your
+        actual situation than to come up with new names. The problem
+        could be related to the name of a table or variable. These cases
+        are rare, perhaps, but it is better to be safe than sorry. After
+        all, it should be easier for you to provide an example that uses
+        your actual situation, and it is by all means better for us. If
+        you have data that you don't want to be visible to others in the
+        bug report, you can use FTP to transfer it to
+        <ulink url="ftp://ftp.mysql.com/pub/mysql/upload/"/>. If the
+        information is really top secret and you don't want to show it
+        even to us, go ahead and provide an example using other names,
+        but please regard this as the last choice.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Include all the options given to the relevant programs, if
+        possible. For example, indicate the options that you use when
+        you start the <command>mysqld</command> server, as well as the
+        options that you use to run any MySQL client programs. The
+        options to programs such as <command>mysqld</command> and
+        <command>mysql</command>, and to the
+        <command>configure</command> script, are often key to resolving
+        problems and are very relevant. It is never a bad idea to
+        include them. If your problem involves a program written in a
+        language such as Perl or PHP, please include the language
+        processor's version number, as well as the version for any
+        modules that the program uses. For example, if you have a Perl
+        script that uses the <literal>DBI</literal> and
+        <literal>DBD::mysql</literal> modules, include the version
+        numbers for Perl, <literal>DBI</literal>, and
+        <literal>DBD::mysql</literal>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If your question is related to the privilege system, please
+        include the output of <command>mysqlaccess</command>, the output
+        of <command>mysqladmin reload</command>, and all the error
+        messages you get when trying to connect. When you test your
+        privileges, you should first run <command>mysqlaccess</command>.
+        After this, execute <command>mysqladmin reload version</command>
+        and try to connect with the program that gives you trouble.
+        <command>mysqlaccess</command> can be found in the
+        <filename>bin</filename> directory under your MySQL installation
+        directory.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If you have a patch for a bug, do include it. But don't assume
+        that the patch is all we need, or that we can use it, if you
+        don't provide some necessary information such as test cases
+        showing the bug that your patch fixes. We might find problems
+        with your patch or we might not understand it at all. If so, we
+        can't use it.
+      </para>
+
+      <para>
+        If we can't verify the exact purpose of the patch, we won't use
+        it. Test cases help us here. Show that the patch handles all the
+        situations that may occur. If we find a borderline case (even a
+        rare one) where the patch won't work, it may be useless.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Guesses about what the bug is, why it occurs, or what it depends
+        on are usually wrong. Even the MySQL team can't guess such
+        things without first using a debugger to determine the real
+        cause of a bug.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        Indicate in your bug report that you have checked the reference
+        manual and mail archive so that others know you have tried to
+        solve the problem yourself.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If the problem is that your data appears corrupt or you get
+        errors when you access a particular table, you should first
+        check your tables and then try to repair them with
+        <literal>CHECK TABLE</literal> and <literal>REPAIR
+        TABLE</literal> or with <command>myisamchk</command>. See
+        <xref linkend="database-administration"/>.
+      </para>
+
+      <para>
+        If you are running Windows, please verify the value of
+        <literal>lower_case_table_names</literal> using the
+        <literal>SHOW VARIABLES LIKE 'lower_case_table_names'</literal>
+        command.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If you often get corrupted tables, you should try to find out
+        when and why this happens. In this case, the error log in the
+        MySQL data directory may contain some information about what
+        happened. (This is the file with the <filename>.err</filename>
+        suffix in the name.) See <xref linkend="error-log"/>. Please
+        include any relevant information from this file in your bug
+        report. Normally <command>mysqld</command> should
+        <emphasis>never</emphasis> crash a table if nothing killed it in
+        the middle of an update. If you can find the cause of
+        <command>mysqld</command> dying, it's much easier for us to
+        provide you with a fix for the problem. See
+        <xref linkend="what-is-crashing"/>.
+      </para>
+    </listitem>
+
+    <listitem>
+      <para>
+        If possible, download and install the most recent version of
+        MySQL Server and check whether it solves your problem. All
+        versions of the MySQL software are thoroughly tested and should
+        work without problems. We believe in making everything as
+        backward-compatible as possible, and you should be able to
+        switch MySQL versions without difficulty. See
+        <xref linkend="which-version"/>.
+      </para>
+    </listitem>
+
+  </itemizedlist>
+
+  <indexterm type="concept">
+    <primary>technical support</primary>
+    <secondary>mailing address</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>support</primary>
+    <secondary>mailing address</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>customer support</primary>
+    <secondary>mailing address</secondary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>mailing address</primary>
+    <secondary>for customer support</secondary>
+  </indexterm>
+
+  <para>
+    If you are a support customer, please cross-post the bug report to
+    <email>mysql-support@stripped</email> for higher-priority
+    treatment, as well as to the appropriate mailing list to see whether
+    someone else has experienced (and perhaps solved) the problem.
+  </para>
+
+  <indexterm type="concept">
+    <primary><command>mysqlbug</command> script</primary>
+  </indexterm>
+
+  <indexterm type="concept">
+    <primary>scripts</primary>
+    <secondary><command>mysqlbug</command></secondary>
+  </indexterm>
+
+  <para>
+    If you have no Web access and cannot report a bug by visiting
+    <ulink url="http://bugs.mysql.com/"/>, you can use the
+    <command>mysqlbug</command> script to generate a bug report (or a
+    report about any problem). <command>mysqlbug</command> helps you
+    generate a report by determining much of the following information
+    automatically, but if something important is missing, please include
+    it with your message. <command>mysqlbug</command> can be found in
+    the <filename>scripts</filename> directory (source distribution) and
+    in the <filename>bin</filename> directory under your MySQL
+    installation directory (binary distribution).
+  </para>
+
+</section>

Modified: trunk/refman-common/information-sources.xml
===================================================================
--- trunk/refman-common/information-sources.xml	2006-01-04 03:49:42 UTC (rev 660)
+++ trunk/refman-common/information-sources.xml	2006-01-04 04:12:52 UTC (rev 661)
@@ -13,9 +13,8 @@
 
   <para>
     This section lists sources of additional information that you may
-    find helpful, such as the MySQL mailing lists, user forums, and
-    Internet Relay Chat. It also provides information on how to report
-    bugs.
+    find helpful, such as the MySQL mailing lists and user forums, and
+    Internet Relay Chat.
   </para>
 
   <section id="mailing-lists">
@@ -35,10 +34,6 @@
     </indexterm>
 
     <indexterm type="concept">
-      <primary>net etiquette</primary>
-    </indexterm>
-
-    <indexterm type="concept">
       <primary>mailing lists</primary>
       <secondary>archive location</secondary>
     </indexterm>
@@ -408,8 +403,8 @@
 
     <para>
       The forums at <ulink url="http://forums.mysql.com"/> are an
-      important community resource. A variety of forums is available,
-      grouped into these general categories:
+      important community resource. Many forums are available, grouped
+      into these general categories:
     </para>
 
     <itemizedlist>
@@ -491,9 +486,9 @@
     </indexterm>
 
     <para>
-      In addition to the various MySQL mailing lists, you can find
-      experienced community people on Internet Relay Chat (IRC). These
-      are the best networks/channels currently known to us:
+      In addition to the various MySQL mailing lists and forums, you can
+      find experienced community people on Internet Relay Chat (IRC).
+      These are the best networks/channels currently known to us:
     </para>
 
     <para>
@@ -530,633 +525,4 @@
 
   </section>
 
-  <section id="bug-reports">
-
-    <title>&title-bug-reports;</title>
-
-    <indexterm type="concept">
-      <primary>reporting</primary>
-      <secondary>errors</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>errors</primary>
-      <secondary>reporting</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>searching</primary>
-      <secondary>MySQL Web pages</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>bug reports</primary>
-      <secondary>criteria for</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>bugs</primary>
-      <secondary>reporting</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>reporting</primary>
-      <secondary>bugs</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>problems</primary>
-      <secondary>reporting</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>errors</primary>
-      <secondary>reporting</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>creating</primary>
-      <secondary>bug reports</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>bugs.mysql.com</primary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>bugs database</primary>
-    </indexterm>
-
-    <para>
-      Before posting a bug report about a problem, please try to verify
-      that it is a bug and that it has not been reported already:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          Start by searching the MySQL online manual at
-          <ulink url="&base-url-docs;"/>. We try to keep the manual up
-          to date by updating it frequently with solutions to newly
-          found problems. The change history
-          (<ulink url="&base-url-docs;mysql/en/news.html"/>) can be
-          particularly useful since it is quite possible that a newer
-          version contains a solution to your problem.
-        </para>
-
-        <para>
-          If you get a parse error for a SQL statement, please check
-          your syntax closely. If you can't find something wrong with
-          it, it's extremely likely that your current version of MySQL
-          Server doesn't support the syntax you are using. If you are
-          using the current version and the manual doesn't cover the
-          syntax that you are using, MySQL Server doesn't support your
-          statement. In this case, your options are to implement the
-          syntax yourself or email <email>licensing@stripped</email>
-          and ask for an offer to implement it.
-        </para>
-
-        <para>
-          If the manual covers the syntax you are using, but you have an
-          older version of MySQL Server, you should check the MySQL
-          change history to see when the syntax was implemented. In this
-          case, you have the option of upgrading to a newer version of
-          MySQL Server.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          For solutions to some common problems, see
-          <xref linkend="problems"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Search in the bugs database at
-          <ulink url="http://bugs.mysql.com/"/> to see whether the bug
-          has been reported and fixed.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Search the MySQL mailing list archives at
-          <ulink url="http://lists.mysql.com/"/>. See
-          <xref linkend="mailing-lists"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          You can also use <ulink url="http://www.mysql.com/search/"/>
-          to search all the Web pages (including the manual) that are
-          located at the MySQL AB Web site.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-    <para>
-      If you can't find an answer in the manual or the archives, check
-      with your local MySQL expert. If you still can't find an answer to
-      your question, please use the following guidelines for reporting
-      the bug.
-    </para>
-
-    <para>
-      The normal way to report bugs is to visit
-      <ulink url="http://bugs.mysql.com/"/>, which is the address for
-      our bugs database. This database is public, and can be browsed and
-      searched by anyone. If you log in to the system, you can enter new
-      reports.
-    </para>
-
-    <para>
-      If you have found a sensitive security bug in MySQL, you can send
-      email to <email>security@stripped</email>.
-    </para>
-
-    <para>
-      To report other problems, you can use one of the MySQL mailing
-      lists. <xref linkend="mailing-lists"/>.
-    </para>
-
-    <para>
-      Writing a good bug report takes patience, but doing it right the
-      first time saves time both for us and for yourself. A good bug
-      report, containing a full test case for the bug, makes it very
-      likely that we will fix the bug in the next release. This section
-      helps you write your report correctly so that you don't waste your
-      time doing things that may not help us much or at all. Please read
-      this section carefully and make sure that all the information
-      described here is included in your report.
-    </para>
-
-    <para>
-      If you have no Web access, you can generate a bug report by using
-      the <command>mysqlbug</command> script described at the end of
-      this section.
-    </para>
-
-    <para>
-      Preferably, you should test the problem using the latest
-      production or development version of MySQL Server before posting.
-      Anyone should be able to repeat the bug by just using
-      <literal>mysql test &lt; script_file</literal> on the included
-      test case or by running the shell or Perl script that you include
-      in the bug report. Any bug that we are able to repeat has a high
-      chance of being fixed in the next MySQL release.
-    </para>
-
-    <para>
-      All bugs posted in the bugs database at
-      <ulink url="http://bugs.mysql.com/"/> are corrected or documented
-      in the next MySQL release. If only minor code changes are needed
-      to correct a problem, we may also post a patch that fixes the
-      problem.
-    </para>
-
-    <para>
-      Remember that it is possible for us to respond to a message
-      containing too much information, but not to one containing too
-      little. People often omit facts because they think they know the
-      cause of a problem and assume that some details don't matter. A
-      good principle is this: If you are in doubt about stating
-      something, state it. It is faster and less troublesome to write a
-      couple more lines in your report than to wait longer for the
-      answer if we must ask you to provide information that was missing
-      from the initial report.
-    </para>
-
-    <para>
-      The most common errors made in bug reports are (a) not including
-      the version number of the MySQL distribution that you use, and (b)
-      not fully describing the platform on which the MySQL server is
-      installed (including the platform type and version number). These
-      are highly relevant pieces of information, and in 99 cases out of
-      100, the bug report is useless without them. Very often we get
-      questions like, <quote>Why doesn't this work for me?</quote> Then
-      we find that the feature requested wasn't implemented in that
-      MySQL version, or that a bug described in a report has been fixed
-      in newer MySQL versions. Sometimes the error is
-      platform-dependent. In such cases, it is next to impossible for us
-      to fix anything without knowing the operating system and the
-      version number of the platform.
-    </para>
-
-    <para>
-      If you compiled MySQL from source, remember also to provide
-      information about your compiler if it is related to the problem.
-      Often people find bugs in compilers and think the problem is
-      MySQL-related. Most compilers are under development all the time
-      and become better version by version. To determine whether your
-      problem depends on your compiler, we need to know what compiler
-      you use. Note that every compiling problem should be regarded as a
-      bug and reported accordingly.
-    </para>
-
-    <para>
-      It is most helpful when a good description of the problem is
-      included in the bug report. That is, give a good example of
-      everything you did that led to the problem and describe, in exact
-      detail, the problem itself. The best reports are those that
-      include a full example showing how to reproduce the bug or
-      problem. See <xref linkend="reproduceable-test-case"/>.
-    </para>
-
-    <para>
-      If a program produces an error message, it is very important to
-      include the message in your report. If we try to search for
-      something from the archives, it is better that the error message
-      reported exactly matches the one that the program produces. (Even
-      the lettercase should be observed.) It is best to copy and paste
-      the entire error message into your report. You should never try to
-      reproduce the message from memory.
-    </para>
-
-    <para>
-      If you have a problem with Connector/ODBC (MyODBC), please try to
-      generate a trace file and send it with your report. See
-      <xref linkend="myodbc-bug-report"/>.
-    </para>
-
-    <para>
-      If your report includes long query output lines from test cases
-      that you run with the <command>mysql</command> command-line tool,
-      you can make the output more readable by using the
-      <option>--vertical</option> option or the <literal>\G</literal>
-      statement terminator. The <literal>EXPLAIN SELECT</literal>
-      example later in this section demonstrates the use of
-      <literal>\G</literal>.
-    </para>
-
-    <para>
-      Please include the following information in your report:
-    </para>
-
-    <itemizedlist>
-
-      <listitem>
-        <para>
-          The version number of the MySQL distribution you are using
-          (for example, MySQL 5.0.19). You can find out which version
-          you are running by executing <command>mysqladmin
-          version</command>. The <command>mysqladmin</command> program
-          can be found in the <filename>bin</filename> directory under
-          your MySQL installation directory.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          The manufacturer and model of the machine on which you
-          experience the problem.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          The operating system name and version. If you work with
-          Windows, you can usually get the name and version number by
-          double-clicking your My Computer icon and pulling down the
-          <quote>Help/About Windows</quote> menu. For most Unix-like
-          operating systems, you can get this information by executing
-          the command <literal>uname -a</literal>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Sometimes the amount of memory (real and virtual) is relevant.
-          If in doubt, include these values.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If you are using a source distribution of the MySQL software,
-          include the name and version number of the compiler that you
-          used. If you have a binary distribution, include the
-          distribution name.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If the problem occurs during compilation, include the exact
-          error messages and also a few lines of context around the
-          offending code in the file where the error occurs.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If <command>mysqld</command> died, you should also report the
-          statement that crashed <command>mysqld</command>. You can
-          usually get this information by running
-          <command>mysqld</command> with query logging enabled, and then
-          looking in the log after <command>mysqld</command> crashes See
-          <xref linkend="using-log-files"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If a database table is related to the problem, include the
-          output from <command>mysqldump --no-data
-          <replaceable>db_name</replaceable>
-          <replaceable>tbl_name</replaceable> &gt;
-          <replaceable>file_name</replaceable></command>. This is very
-          easy to do and is a powerful way to get information about any
-          table in a database. The <command>mysqldump</command> command
-          generates a file that you can upload to be attached to the bug
-          report. The information helps us create a situation matching
-          the one that you have experienced.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          For performance-related bugs or problems with
-          <literal>SELECT</literal> statements, you should always
-          include the output of <literal>EXPLAIN SELECT ...</literal>,
-          and at least the number of rows that the
-          <literal>SELECT</literal> statement produces. You should also
-          include the output from <literal>SHOW CREATE TABLE
-          <replaceable>tbl_name</replaceable></literal> for each table
-          that is involved. The more information you provide about your
-          situation, the more likely it is that someone can help you.
-        </para>
-
-        <para>
-          The following is an example of a very good bug report. The
-          statements are run using the <command>mysql</command>
-          command-line tool. Note the use of the <literal>\G</literal>
-          statement terminator for statements that would otherwise
-          provide very long output lines that are difficult to read.
-        </para>
-
-<programlisting>
-mysql&gt; <userinput>SHOW VARIABLES;</userinput>
-mysql&gt; <userinput>SHOW COLUMNS FROM ...\G</userinput>
-       <replaceable>&lt;output from SHOW COLUMNS&gt;</replaceable>
-mysql&gt; <userinput>EXPLAIN SELECT ...\G</userinput>
-       <replaceable>&lt;output from EXPLAIN&gt;</replaceable>
-mysql&gt; <userinput>FLUSH STATUS;</userinput>
-mysql&gt; <userinput>SELECT ...;</userinput>
-       <replaceable>&lt;A short version of the output from SELECT,
-       including the time taken to run the query&gt;</replaceable>
-mysql&gt; <userinput>SHOW STATUS;</userinput>
-       <replaceable>&lt;output from SHOW STATUS&gt;</replaceable>
-</programlisting>
-      </listitem>
-
-      <listitem>
-        <para>
-          If a bug or problem occurs while running
-          <command>mysqld</command>, try to provide an input script that
-          reproduces the anomaly. This script should include any
-          necessary source files. The more closely the script can
-          reproduce your situation, the better. If you can make a
-          reproducible test case, you should upload it to be attached to
-          the bug report.
-        </para>
-
-        <para>
-          If you can't provide a script, you should at least include the
-          output from <command>mysqladmin variables extended-status
-          processlist</command> in your report to provide some
-          information on how your system is performing.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If you can't produce a test case with only a few rows, or if
-          the test table is too big to be included in the bug report
-          (more than 10 rows), you should dump your tables using
-          <command>mysqldump</command> and create a
-          <filename>README</filename> file that describes your problem.
-          Create a compressed archive of your files using
-          <command>tar</command> and <command>gzip</command> or
-          <command>zip</command>, and use FTP to transfer the archive to
-          <ulink url="ftp://ftp.mysql.com/pub/mysql/upload/"/>. Then
-          enter the problem into our bugs database at
-          <ulink url="http://bugs.mysql.com/"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If you believe that the MySQL server produces a strange result
-          from a statement, include not only the result, but also your
-          opinion of what the result should be, and an explanation
-          describing the basis for your opinion.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          When you provide an example of the problem, it's better to use
-          the table names, variable names, and so forth that exist in
-          your actual situation than to come up with new names. The
-          problem could be related to the name of a table or variable.
-          These cases are rare, perhaps, but it is better to be safe
-          than sorry. After all, it should be easier for you to provide
-          an example that uses your actual situation, and it is by all
-          means better for us. If you have data that you don't want to
-          be visible to others in the bug report, you can use FTP to
-          transfer it to
-          <ulink url="ftp://ftp.mysql.com/pub/mysql/upload/"/>. If the
-          information is really top secret and you don't want to show it
-          even to us, then go ahead and provide an example using other
-          names, but please regard this as the last choice.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Include all the options given to the relevant programs, if
-          possible. For example, indicate the options that you use when
-          you start the <command>mysqld</command> server, as well as the
-          options that you use to run any MySQL client programs. The
-          options to programs such as <command>mysqld</command> and
-          <command>mysql</command>, and to the
-          <command>configure</command> script, are often key to
-          resolving problems and are very relevant. It is never a bad
-          idea to include them. If you problem includes a programm
-          written in a language such as Perl or PHP, please include the
-          language processor's version number, as well as the version
-          for any modules that the program uses. For example, if you
-          have a Perl script that uses the <literal>DBI</literal> and
-          <literal>DBD::mysql</literal> modules, include the version for
-          Perl, <literal>DBI</literal>, and
-          <literal>DBD::mysql</literal>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If your question is related to the privilege system, please
-          include the output of <command>mysqlaccess</command>, the
-          output of <command>mysqladmin reload</command>, and all the
-          error messages you get when trying to connect. When you test
-          your privileges, you should first run
-          <command>mysqlaccess</command>. After this, execute
-          <command>mysqladmin reload version</command> and try to
-          connect with the program that gives you trouble.
-          <command>mysqlaccess</command> can be found in the
-          <filename>bin</filename> directory under your MySQL
-          installation directory.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If you have a patch for a bug, do include it. But don't assume
-          that the patch is all we need, or that we can use it, if you
-          don't provide some necessary information such as test cases
-          showing the bug that your patch fixes. We might find problems
-          with your patch or we might not understand it at all. If so,
-          we can't use it.
-        </para>
-
-        <para>
-          If we can't verify exactly what the purpose of the patch is,
-          we won't use it. Test cases help us here. Show that the patch
-          handles all the situations that may occur. If we find a
-          borderline case (even a rare one) where the patch won't work,
-          it may be useless.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Guesses about what the bug is, why it occurs, or what it
-          depends on are usually wrong. Even the MySQL team can't guess
-          such things without first using a debugger to determine the
-          real cause of a bug.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          Indicate in your bug report that you have checked the
-          reference manual and mail archive so that others know you have
-          tried to solve the problem yourself.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If your problem is that your data appears corrupt or you get
-          errors when you access a particular table, you should first
-          check your tables and then try to repair them with
-          <literal>CHECK TABLE</literal> and <literal>REPAIR
-          TABLE</literal> or with <command>myisamchk</command>. See
-          <xref linkend="database-administration"/>.
-        </para>
-
-        <para>
-          If you are running Windows, please verify the value of
-          <literal>lower_case_table_names</literal> using the
-          <literal>SHOW VARIABLES LIKE
-          'lower_case_table_names'</literal> command.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If you often get corrupted tables, you should try to find out
-          when and why this happens. In this case, the error log in the
-          MySQL data directory may contain some information about what
-          happened. (This is the file with the <filename>.err</filename>
-          suffix in the name.) See <xref linkend="error-log"/>. Please
-          include any relevant information from this file in your bug
-          report. Normally <command>mysqld</command> should
-          <emphasis>never</emphasis> crash a table if nothing killed it
-          in the middle of an update. If you can find the cause of
-          <command>mysqld</command> dying, it's much easier for us to
-          provide you with a fix for the problem. See
-          <xref linkend="what-is-crashing"/>.
-        </para>
-      </listitem>
-
-      <listitem>
-        <para>
-          If possible, download and install the most recent version of
-          MySQL Server and check whether it solves your problem. All
-          versions of the MySQL software are thoroughly tested and
-          should work without problems. We believe in making everything
-          as backward-compatible as possible, and you should be able to
-          switch MySQL versions without difficulty. See
-          <xref linkend="which-version"/>.
-        </para>
-      </listitem>
-
-    </itemizedlist>
-
-    <indexterm type="concept">
-      <primary>technical support</primary>
-      <secondary>mailing address</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>support</primary>
-      <secondary>mailing address</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>customer support</primary>
-      <secondary>mailing address</secondary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>mailing address</primary>
-      <secondary>for customer support</secondary>
-    </indexterm>
-
-    <para>
-      If you are a support customer, please cross-post the bug report to
-      <email>mysql-support@stripped</email> for higher-priority
-      treatment, as well as to the appropriate mailing list to see
-      whether someone else has experienced (and perhaps solved) the
-      problem.
-    </para>
-
-    <indexterm type="concept">
-      <primary><command>mysqlbug</command> script</primary>
-    </indexterm>
-
-    <indexterm type="concept">
-      <primary>scripts</primary>
-      <secondary><command>mysqlbug</command></secondary>
-    </indexterm>
-
-    <para>
-      If you have no Web access and cannot report a bug by visiting
-      <ulink url="http://bugs.mysql.com/"/>, you can use the
-      <command>mysqlbug</command> script to generate a bug report (or a
-      report about any problem). <command>mysqlbug</command> can be
-      found in the <filename>scripts</filename> directory (source
-      distribution) and in the <filename>bin</filename> directory under
-      your MySQL installation directory (binary distribution). If you
-      are unable to use <command>mysqlbug</command> (for example, if you
-      are running on Windows), it is still vital that you include all
-      the necessary information noted in this section (most importantly,
-      a description of the operating system and the MySQL version).
-    </para>
-
-    <para>
-      The <command>mysqlbug</command> script helps you generate a report
-      by determining much of the following information automatically,
-      but if something important is missing, please include it with your
-      message.
-    </para>
-
-  </section>
-
 </section>

Thread
svn commit - mysqldoc@docsrva: r661 - in trunk: . refman-commonpaul4 Jan