<!--
$Header: /usr/prj/pg/cvsroot/doc/doc/src/sgml/problems.sgml,v 1.7 2001/08/28 03:39:50 i-kaori Exp $
-->

<sect1 id="bug-reporting">
 <!--<title>Bug Reporting Guidelines</title>-->
 <title>バグレポートガイドライン</title>
<indexterm><primary>バグレポート</primary></indexterm>

 <para>
  <!--When you find a bug in <productname>PostgreSQL</productname> we want to
  hear about it. Your bug reports play an important part in making
  <productname>PostgreSQL</productname> more reliable because even the utmost
  care cannot guarantee that every part of PostgreSQL will work on every
  platform under every circumstance.-->

  <productname>PostgreSQL</productname>に関してバグを発見した場合、ぜひ連絡してください。すべてのプラットフォーム、すべての環境でPostgreSQLの機能すべてが正常に動くことを保証できないので、バグレポートは<productname>PostgreSQL</productname>をより信頼性の高いものにするために、大変有効になります。
 </para>

 <para>
  <!--The following suggestions are intended to assist you in forming bug reports
  that can be handled in an effective fashion. No one is required to follow
  them but it tends to be to everyone's advantage.-->

  下記の記述は、バグレポートが有効的に活用されるためのものです。これに従う義務はありませんが、沿った方がより有益なものとなるでしょう。
 </para>

 <para>
  <!--We cannot promise to fix every bug right away. If the bug is obvious, critical,
  or affects a lot of users, chances are good that someone will look into it. It
  could also happen that we tell you to update to a newer version to see if the
  bug happens there. Or we might decide that the bug
  cannot be fixed before some major rewrite we might be planning is done. Or
  perhaps it is simply too hard and there are more important things on the agenda.
  If you need help immediately, consider obtaining a commercial support contract.-->

  発見されたバグはただちに修正されるとは限りません。そのバグが明確で、重大で、他の多くのユーザーにも影響を与えるものであれば、すぐに修正される可能性が高いでしょう。また、より新しいバージョンに変えて、そこでも同じようなことが起こるかを確認してもらうようにお勧めする場合もあります。あるいは、現在計画中の大きな変更が終了するまでバグが修正しないと判断される場合もあります。また、そのバグ修正はとても難易度が高いもので、後まわしになることも考えられます。早急に処置が必要な場合は、商用サポートの購入を検討してください。
 </para>

 <sect2>
  <!--<title>Identifying Bugs</title>-->
  <title>バグの特定</title>

  <para>
   <!--Before you report a bug, please read and re-read the
   documentation to verify that you can really do whatever it is you are
   trying. If it is not clear from the documentation whether you can do
   something or not, please report that too; it is a bug in the documentation.
   If it turns out that the program does something different from what the
   documentation says, that is a bug. That might include, but is not limited to,
   the following circumstances:-->

   バグ報告を行う前に、ドキュメントを再度読み返し、実行しようとしている処理が実行可能かを確認してください。実行可能かどうかが不明な場合は、その旨を報告してください（それはある意味ドキュメントのバグです）。また、ドキュメントに書かれていることと実際の結果が異なる場合はそれはバグとなります。それらの一部の例を下記に記します。</para>

   <itemizedlist>
    <listitem>
     <para>
      <!--A program terminates with a fatal signal or an operating system
      error message that would point to a problem in the program. (A
      counterexample might be a <quote>disk full</quote> message,
      since you have to fix that yourself.)-->

      プログラムが致命的なシグナル、またはオペレーティングシステムのエラーメッセージで終了し、それがプログラムの問題を指す場合（逆に、<quote>disk full</quote>のようなメッセージはプログラムの問題ではありませんので、この場合は自分で修正してください）。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--A program produces the wrong output for any given input.-->
      あるプログラムで、入力された値に対して必ず間違った結果を返す場合。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--A program refuses to accept valid input (as defined in the documentation).-->
      （ドキュメントで定義されている）有効な値を入力してもプログラムで受け付けない場合。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--A program accepts invalid input without a notice or error message.
      Keep in mind that your idea of invalid input might be our idea of
      an extension or compatibility with traditional practice.-->

      無効な値を入力し、エラーメッセージなどを表示させずにプログラムがその値を受け入れる場合（しかし、無効な入力と思われているものでも、実際には伝統的な理由による実装の拡張や互換性のために有効としている可能性もありますので注意してください）。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--<productname>PostgreSQL</productname> fails to compile, build, or
      install according to the instructions on supported platforms.-->

      サポートされているプラットフォームで、<productname>PostgreSQL</productname>がコンパイル、ビルド、インストールできない場合。
     </para>
    </listitem>
   </itemizedlist>

   <!--Here <quote>program</quote> refers to any executable, not only the backend server.-->

<para>ここでは、<quote>プログラム</quote>とはバックエンドサーバーだけではなく、実行可能なものを意味します。
  </para>

  <para>
   <!--Being slow or resource-hogging is not necessarily a bug. Read the documentation
   or ask on one of the mailing lists for help in tuning your applications. Failing
   to comply to <acronym>SQL</acronym> is not a bug unless compliance for the
   specific feature is explicitly claimed.-->

   プログラムの実行が遅かったり、リソースを大量に使用するのは必ずしもバグではありません。アプリケーションを改善するためには、ドキュメントを読んだり、メーリングリストで尋ねてみたりしてください。<acronym>SQL</acronym>の要求に応じない場合、問題点が明確に特定できない限り、それはバグとはいえません。
  </para>

  <para>
   <!--Before you continue, check on the TODO list and in the FAQ to see if your bug is
   already known. If you cannot decode the information on the TODO list, report your
   problem. The least we can do is make the TODO list clearer.-->

   また、TODOリストや、FAQなどで、そのバグがすでに認知されているかの確認をしてください。もしTODOリストに書かれていなければ、報告してください。
  </para>
 </sect2>

 <sect2>
  <!--<title>What to report</title>-->
  <title>報告すべきこと</title>

  <para>
   <!--The most important thing to remember about bug reporting is to state all
   the facts and only facts. Do not speculate what you think went wrong, what
   "it seemed to do", or which part of the program has a fault.
   If you are not familiar with the implementation you would probably guess
   wrong and not help us a bit. And even if you are, educated explanations are
   a great supplement to but no substitute for facts. If we are going to fix
   the bug we still have to see it happen for ourselves first.
   Reporting the bare facts
   is relatively straightforward (you can probably copy and paste them from the
   screen) but all too often important details are left out because someone
   thought it does not matter or the report would be understood
   anyway.-->

   バグ報告でもっとも重要なことは、すべての事実を明確に記述し、また、記述されたものは事実のみである、ということです。何が起こったのか、または、プログラムのどこが問題か、「何々が起こっているようだ」などの憶測や推測を記述しないでください。実装にさほど詳しくない方の推測は正しくない場合があり、有効なバグ報告になりません。実装に精通している方の場合でも、根拠のある説明は参考情報となりますが、やはり正しい事実が一番役に立ちます。バグを修正するためには、まず開発者自身がそのバグを再現する必要があります。ありのままの事実を報告するのは単刀直入ですが（多くの場合画面からメッセージをコピー&amp;ペーストを行うのみ）、多くの場合、それだけでは情報が不十分で、たとえばたいして重要でないだろうと想像したり、省いても理解してもらえるだろうと思いこむことにより重要な情報が洩れてしまっています。
  </para>

  <para>
   <!--The following items should be contained in every bug report:-->
   すべてのバグ報告では、下記の内容が記述されていなければいけません。</para>

   <itemizedlist>
    <listitem>
     <para>
      <!--The exact sequence of steps <emphasis>from program start-up</emphasis>
      necessary to reproduce the problem. This should be self-contained;
      it is not enough to send in a bare select statement without the
      preceding create table and insert statements, if the output should
      depend on the data in the tables. We do not have the time
      to reverse-engineer your database schema, and if we are supposed to make
      up our own data we would probably miss the problem.
      The best format for a test case for
      query-language related problems is a file that can be run through the
      <application>psql</application> frontend
      that shows the problem. (Be sure to not have anything in your
      <filename>~/.psqlrc</filename> start-up file.)  An easy start at this
      file is to use <application>pg_dump</application> to dump out the table
      declarations and data needed to set the scene, then add the problem
      query.
      You are encouraged to
      minimize the size of your example, but this is not absolutely necessary.
      If the bug is reproduceable, we will find it either way.-->

      問題を再現できるように、<emphasis>プログラムの起動から</emphasis>行った作業を順序どおりに記述してください。たとえば、結果が、テーブルのデータに依存するならば、単にselect文を記述していても、それ以前に行われた、テーブルの作成やinsert文が記述されていなければ十分とはいえません。データベースの概要を分解模倣する時間のロスや、データを開発者が作成したら同じ現象が起こらないかもしれない、などのことが発生します。問い合わせ関連のテストケースのもっともよいとされるバグ報告方法は、フロントエンドである<application>psql</application>に直接読み込ませられるファイルを用意することです（<filename>~/.psqlrc</filename>の起動ファイルに何も書かれていないことに注意してください）。このファイルを簡単に取得するには、<application>pg_dump</application>を使ってテーブル定義とその状況を再現させるために必要なデータを取り出し、問題の起こった問い合わせを追加します。例の数を減らすことは推奨されますが、必ずしも必要ではありません。どの方法をとっても、バグが再現できればよいのです。
     </para>

     <para>
      <!--If your application uses some other client interface, such as PHP, then
      please try to isolate the offending queries. We will probably not set up a
      web server to reproduce your problem. In any case remember to provide
      the exact input files, do not guess that the problem happens for
      "large files" or "mid-size databases", etc. since this
      information is too inexact to be of use.-->

      アプリケーションがPHPなどの、他のクライアントインターフェイスを使用する場合、問い合わせからそれらを分離させてください。問題を再現するために新たにWebサーバーを立ち上げることはまずありません。どのような場合においても、正確な入力ファイルを作成して報告してください。「大きいファイルで起こる」、「中規模データベースで起こる」などは正確な情報ではないので、このように推測はしないでください。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--The output you got. Please do not say that it <quote>didn't work</quote> or
      <quote>crashed</quote>. If there is an error message,
      show it, even if you do not understand it. If the program terminates with
      an operating system error, say which. If nothing at all happens, say so.
      Even if the result of your test case is a program crash or otherwise obvious
      it might not happen on our platform. The easiest thing is to copy the output
      from the terminal, if possible.-->

      得た結果に関しては、<quote>うまくいかなかった</quote>や<quote>クラッシュした</quote>などの報告はしないでください。エラーメッセージがあるならば、たとえ意味が理解できなくてもそれを報告してください。オペレーティングシステムのエラーでプログラムが強制終了してしまったら、どのエラーでそうなったのかを報告してください。何も起こらない場合も、その旨を報告してください。たとえテストケースの結果がプログラムのクラッシュなどの場合は、再現できない場合があります。もっとも容易な方法は、結果をターミナルからコピーするものです。
     </para>
     <note>
      <para>
       <!--In case of fatal errors, the error message provided by the client might
       not contain all the information available. In that case, also look at the
       log output of the database server. If you do not keep your server
       output, this would be a good time to start doing so.-->

       致命的なエラーが起こった場合、クライアントから送られてきたエラーメッセージは必要な情報すべてが書かれているとは限りません。この場合、データベースサーバーのログを見てみてください。もしログを取っていないならば、取る習慣を付けてください。
      </para>
     </note>
    </listitem>

    <listitem>
     <para>
      <!--The output you expected is very important to state. If you just write
      "This command gives me that output." or "This is not
      what I expected.", we might run it ourselves, scan the output, and
      think it looks okay and is exactly what we expected. We should not have to
      spend the time to decode the exact semantics behind your commands.
      Especially refrain from merely saying that "This is not what SQL says/Oracle
      does." Digging out the correct behavior from <acronym>SQL</acronym>
      is not a fun undertaking, nor do we all know how all the other relational
      databases out there behave. (If your problem is a program crash you can
      obviously omit this item.)-->

      どのような結果を望んでいたのかも記述してください。ただ単に「このコマンドはこのような結果を返した」や、「このような結果を望んでいなかった」だけでは、再現し、結果を検証したときに、開発者にとってはそれは正しい結果である可能性があります。送られてきたコマンドの背後にある意味をすべて把握することはできません。また、特に「SQLではこう書かれていない」や「Oracleではこのようにならない」というコメントは遠慮願います。<acronym>SQL</acronym>の正確な動作を捜し出すのは楽しい作業ではありませんし、また、世にある他のリレーショナルデータベースの動作すべてをPostgreSQLの開発者が把握しているわけでもありません。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--Any command line options and other start-up options, including concerned
      environment variables or configuration files that you changed from the
      default. Again, be exact. If you are using a pre-packaged
      distribution that starts the database server at boot time, you should try
      to find out how that is done.-->

      コマンドラインと起動の際のあらゆるオプションとデフォルトから変更した環境変数や設定も正確に記述してください。前もってパッケージされたディストリビューションを使用し、OSの起動時にデータベースサーバーを起動する場合はそれらがどのように実行されているかを確認する必要があります。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--Anything you did at all differently from the installation instructions.-->

      インストール説明とは異なった方法で行った作業をすべて記述してください。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--The <productname>PostgreSQL</productname> version. You can run the command
      <literal>SELECT version();</literal> to
      find out the version of the server you are connected to.  Most executable
      programs also support a -->

      <literal>SELECT version();</literal>で、接続している<productname>PostgreSQL</productname>のバージョンを調べ、それも記述してください。多くの実行可能なプログラムでは<option>--version</option>オプションも使用できます。

      <!--at least
      <literal>postmaster &bsol;-&bsol;-version</literal> and <literal>psql &bsol;-&bsol;-version</literal>
      should work.-->

      少なくとも<literal>postmaster --version</literal>と<literal>psql --version</literal>は実行できるはずです。


      <!--If the function or the options do not exist then your version is probably
      old enough.  You can also look into the <filename>README</filename> file
      in the source directory or at the
      name of your distribution file or package name.
      If you run a pre-packaged version, such as RPMs, say so, including any
      subversion the package may have. If you are talking about a CVS
      snapshot, mention that, including its date and time.-->

      それらの機能やオプションが使用できない場合は、そのバージョンはとても古いものであるといえます。また、ソースディレクトリ、<filename>README</filename>ファイル、ディストリビューションファイルの名前やパッケージ名を参照してください。
     </para>

     <para>
      <!--If your version is older than &version; we will almost certainly tell
      you to upgrade. There are tons
      of bug fixes in each new release, that is why we make new releases.-->

      &version;よりもバージョンが古い場合、アップグレードすることをお勧めします。新しいリリースでは多くのバグが修正されてるからです。新しいバージョンをリリースするのにはバグを修正するという目的もあるのです。
     </para>
    </listitem>

    <listitem>
     <para>
      <!--Platform information. This includes the kernel name and version, C library,
      processor, memory information. In most cases it is sufficient to report
      the vendor and version, but do not assume everyone knows what exactly
      "Debian" contains or that everyone runs on Pentiums. If
      you have installation problems then information about compilers, make,
      etc. is also necessary.-->

      プラットフォーム情報をカーネル名とバージョン、Cライブラリ、プロセッサ、メモリ情報も含めて報告してください。多くの場合、ベンダー名とそのバージョンを明記するだけで十分ですが、開発者がその「Debian」に何が含まれているかや、どのPentiumを使用しているなどのことを把握してはいないことを覚えておいてください。インストールの問題がある場合はコンパイラやmakeの情報も必要となります。
     </para>
    </listitem>
   </itemizedlist>

   <!--Do not be afraid if your bug report becomes rather lengthy. That is a fact of life.
   It is better to report everything the first time than us having to squeeze the
   facts out of you. On the other hand, if your input files are huge, it is
   fair to ask first whether somebody is interested in looking into it.-->

<para>バグ報告が長文になってもそれは仕方がないことなので、気にしないでください。一度にすべての情報を入手できる方が、開発者から情報を催促するよりも手間暇がかかりません。その一方、ファイルが大きいならば、その情報に誰か興味があるかを尋ねるのが得策かもしれません。
  </para>

  <para>
   <!--Do not spend all your time to figure out which changes in the input make
   the problem go away. This will probably not help solving it. If it turns
   out that the bug cannot be fixed right away, you will still have time to
   find and share your work around. Also, once again, do not waste your time
   guessing why the bug exists. We will find that out soon enough.-->

   問題が解決するために時間をかけて入力値をさまざまと変えてみてるのは問題を解決するには得策とはいえません。バグが即座に修正されない場合、その間を利用してさまざまと試してみてください。バグがなぜあるのかを解明するのに余計な時間を取る必要はありません。
  </para>

  <para>
   <!--When writing a bug report, please choose non-confusing terminology.
   The software package as such is called "PostgreSQL",
   sometimes "Postgres" for short. (Sometimes
   the abbreviation "Pgsql" is used but don't do that.) When you
   are specifically talking about the backend server, mention that, do not
   just say "Postgres crashes". The interactive frontend is called
   "psql" and is for all intends and purposes completely separate
   from the backend.-->

   バグ報告をする際、理解しやすい用語を使用してください。このソフトウェアパッケージは「PostgreSQL」と呼ばれていますが、略して「Postgres」とも呼ばれます（「Pgsql」とも略される場合がありますが、使用しないでください）。特にバックエンドサーバーに関して述べるときは、そのように明記し、「Postgresがクラッシュする」とだけは明記しないでください。インタラクティブなフロントエンドは「psql」と呼ばれ、バックエンドから切り離す目的で使用します。
  </para>
 </sect2>

 <sect2>
  <!--<title>Where to report bugs</title>-->
  <title>バグ報告する場所</title>

  <para>
   <!--In general, send bug reports to the bug report mailing list at
   <email>pgsql-bugs@postgresql.org</email>.
   You are invited to find a descriptive subject for your email
   message, perhaps parts of the error message.-->

   一般的には、<email>pgsql-bugs@postgresql.org</email>のバグ報告用メーリングリストにバグ報告を送ってください。バグ報告の題名には、エラーメッセージの一部分などを使ってください。
  </para>

  <para> 
   <!--Do not send bug reports to any of the user mailing lists, such as
   <email>pgsql-sql@postgresql.org</email> or
   <email>pgsql-general@postgresql.org</email>.
   These mailing lists are for answering
   user questions and their subscribers normally do not wish to receive
   bug reports. More importantly, they are unlikely to fix them.-->

   <email>pgsql-sql@postgresql.org</email>や<email>pgsql-general@postgresql.org</email>には決してバグ報告を送らないでください。これらのメーリングリストはバグ報告を必要としないユーザーの場となっています。また、多くの場合、そのメーリングリストに参加している人はバグを修正してくれる可能性は低いでしょう。
  </para>

  <para>
   <!--Also, please do <emphasis>not</emphasis> send reports to
   the developers' mailing list <email>pgsql-hackers@postgresql.org</email>.
   This list is for discussing the
   development of <productname>PostgreSQL</productname> and it would be nice
   if we could keep the bug reports separate. We might choose to take up a
   discussion
   about your bug report on it, if the bug needs more review.-->

   また、<email>pgsql-hackers@postgresql.org</email>にもバグ報告を<emphasis>送らない</emphasis>でください。ここは<productname>PostgreSQL</productname>の開発に関して議論する場で、バグ報告とは切り離している方がよいとされています（後で、そのバグ報告がこのメーリングリストで議論される場合は十分ありえますが）。
  </para>

  <para>
   <!--If you have a problem with the documentation, send email to
   the documentation mailing list <email>pgsql-docs@postgresql.org</email>.
   Mention the document, chapter, and sections in your problem report.-->

   ドキュメントに関して問題がある場合は、ドキュメント用のメーリングリスト、<email>pgsql-docs@postgresql.org</email>に報告してください。その際、ドキュメント名、章、節を明記してください。
  </para>
 
  <para>
   <!--If your bug is a portability problem on a non-supported platform,
   send mail to <email>pgsql-ports@postgresql.org</email>,
   so we (and you) can work on
   porting <productname>PostgreSQL</productname> to your platform.-->

   また、サポートされていないプラットフォームへの移植に関係するバグ報告である場合は<email>pgsql-ports@postgresql.org</email>に報告してください。そのプラットフォームへ<productname>PostgreSQL</productname>を移植するように最善の努力をします。
  </para>

  <note>
   <para>
    <!--Due to the unfortunate amount of spam going around, all of the above
    email addresses are closed mailing lists. That is, you need to be
    subscribed to a list to be allowed to post on it. If you simply
    want to send mail but do not want to receive list traffic, you can
    subscribe and set your subscription option to <literal>nomail</>.
    For more information send mail to
    <email>majordomo@postgresql.org</email>
    with the single word <literal>help</> in the body of the message.-->

    spamメールを防止するために、残念なことに、これらのメーリングリストはclosedとなっています。つまり、これらのメーリングリストに投稿するには、講読しなければいけません。単にメールを送りたい場合は、購読し、講読オプションを<literal>nomail</literal>に設定してください。より詳細については<email>majordomo@postgresql.org</email>宛に本文には<literal>help</literal>とだけ書いてメールを送ってください。
   </para>
  </note>
 </sect2>
</sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode:sgml
sgml-omittag:nil
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
sgml-parent-document:nil
sgml-default-dtd-file:"./reference.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:("/usr/lib/sgml/catalog")
sgml-local-ecat-files:nil
End:
-->
