Postgresql 中文操作指南
5. Bug Reporting Guidelines #
当您在 PostgreSQL 中发现错误时，我们希望听到您的声音。您的错误报告在使 PostgreSQL 更加可靠方面发挥着重要作用，因为即使是最谨慎的人也无法保证 PostgreSQL 的每个部分都可以在任何平台上的任何情况下运行。
When you find a bug in PostgreSQL we want to hear about it. Your bug reports play an important part in making PostgreSQL more reliable because even the utmost care cannot guarantee that every part of PostgreSQL will work on every platform under every circumstance.
以下建议旨在帮助你以有效的方式提交可以处理的错误报告。没有人需要遵循这些建议，但这样做往往对每个人都有好处。
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 doing so tends to be to everyone’s advantage.
我们无法保证立即修复每个错误。如果错误很明显、很关键或影响了很多用户，很可能会有人来调查。还可能发生这种情况：我们告诉你更新到一个较新的版本，看看那里是否会出现错误。或者我们可能会决定在完成我们可能正在计划进行的某些重大改写之前无法修复该错误。或者它可能只是太困难，并且议程上有更重要的事情。如果你需要立即获得帮助，请考虑获得商业支持合同。
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.
5.1. Identifying Bugs #
在你报告错误之前，请阅读并重新阅读文档，以验证你确实可以执行尝试执行的任何操作。如果从文档中无法明确判断你是否可以做某事，请报告该问题；这是文档中的错误。如果某个程序与文档所说的不同，那就是一个错误。这可能包括但不限于以下情况：
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 a program does something different from what the documentation says, that is a bug. That might include, but is not limited to, the following circumstances:
此处“程序”指的是任何可执行文件，而不仅仅是后端进程。
Here “program” refers to any executable, not only the backend process.
运行缓慢或占用大量资源不一定是错误。请阅读文档或在某个邮件列表中提出问题，以获得帮助来调整你的应用程序。如果不符合 SQL 标准也不一定是错误，除非明确声称特定功能的兼容性。
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 the SQL standard is not necessarily a bug either, unless compliance for the specific feature is explicitly claimed.
在你继续之前，请查看 TODO 列表和常见问题解答，看看你的错误是否已经知道。如果你无法解码 TODO 列表上的信息，请报告你的问题。我们至少可以明确 TODO 列表。
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.
5.2. What to Report #
关于错误报告，要记住的最重要的一点是陈述所有事实，而且只陈述事实。不要猜测你认为出了什么问题，“它似乎做了什么”，或者程序的哪一部分有故障。如果你不熟悉该实施，你可能会猜错，一点儿也帮不了我们。即使你知道，受教育的解释是事实的一个很好补充，但不能代替事实。如果我们要修复该错误，我们仍然必须自己先看到它。报告基本事实相对简单（你或许可以从屏幕上复制粘贴它们），但重要细节经常会被遗漏，因为有人认为它无关紧要或报告会被理解。
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.
以下项目应包含在每个错误报告中：
The following items should be contained in every bug report:
Note
如果您要报告错误消息，请获取消息的最详细形式。在 psql 中，事先说_\set VERBOSITY verbose_。如果您正在从服务器日志中提取消息，请将运行时参数 log_error_verbosity设置为_verbose_，以便记录所有详细信息。
If you are reporting an error message, please obtain the most verbose form of the message. In psql, say \set VERBOSITY verbose beforehand. If you are extracting the message from the server log, set the run-time parameter log_error_verbosity to verbose so that all details are logged.
Note
在发生致命错误的情况下，客户端报告的错误消息可能不包含所有可用信息。请还查看数据库服务器的日志输出。如果您不保留服务器的日志输出，现在是开始这样做的好时机。
In case of fatal errors, the error message reported by the client might not contain all the information available. Please also look at the log output of the database server. If you do not keep your server’s log output, this would be a good time to start doing so.
如果您的错误报告变得很长，那也没什么可担心的。这是生活中的一个事实。将所有内容都在第一次报告中汇报出来，比我们必须从您那里一点点挤出事实要好。另一方面，如果您的输入文件很大，首先询问一下是否有谁有兴趣对此进行查看到是公平的。以下是一篇 article 提供了更多有关报告错误的提示。
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. Here is an article that outlines some more tips on reporting bugs.
不要花所有时间来弄清楚输入中的哪些更改使问题消失。这可能无助于解决问题。如果事实证明该错误无法立即修复，你仍然有时间找到并分享你的解决方法。同样，不要浪费你的时间猜测为什么存在错误。我们很快就会发现。
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.
在编写错误报告时，请避免混淆术语。软件包称为“PostgreSQL”，有时简称“Postgres”。如果你专门讨论后端进程，请提及它，不要只说“PostgreSQL 崩溃”。单个后端进程崩溃与父“postgres”进程崩溃有很大不同；当你指的是单个后端进程崩溃时，请不要说“服务器崩溃”，反之亦然。此外，客户端程序（如交互式前端“psql”）与后端完全分开。请尝试具体说明问题是在客户端还是在服务器端。
When writing a bug report, please avoid confusing terminology. The software package in total is called “PostgreSQL”, sometimes “Postgres” for short. If you are specifically talking about the backend process, mention that, do not just say “PostgreSQL crashes”. A crash of a single backend process is quite different from crash of the parent “postgres” process; please don’t say “the server crashed” when you mean a single backend process went down, nor vice versa. Also, client programs such as the interactive frontend “psql” are completely separate from the backend. Please try to be specific about whether the problem is on the client or server side.
5.3. Where to Report Bugs #
一般来说，将错误报告发送到 < link:mailto:pgsql-bugs@lists.postgresql.org[pgsql-bugs@lists.postgresql.org]> 的错误报告邮件列表。请您为电子邮件信息使用描述性主题，可以是错误消息的一部分。
In general, send bug reports to the bug report mailing list at <link:mailto:pgsql-bugs@lists.postgresql.org[pgsql-bugs@lists.postgresql.org]>. You are requested to use a descriptive subject for your email message, perhaps parts of the error message.
另一种方法是填写项目 web site 中提供的错误报告网络表单。这样输入错误报告会将其发送到 < link:mailto:pgsql-bugs@lists.postgresql.org[pgsql-bugs@lists.postgresql.org]> 邮件列表。
Another method is to fill in the bug report web-form available at the project’s web site. Entering a bug report this way causes it to be mailed to the <link:mailto:pgsql-bugs@lists.postgresql.org[pgsql-bugs@lists.postgresql.org]> mailing list.
如果您的错误报告有安全隐患，您希望它不会立即显示在公共存档中，请不要将其发送到 pgsql-bugs 。可以通过电子邮件将安全问题私下报告给 < link:mailto:security@postgresql.org[security@postgresql.org]> 。
If your bug report has security implications and you’d prefer that it not become immediately visible in public archives, don’t send it to pgsql-bugs. Security issues can be reported privately to <link:mailto:security@postgresql.org[security@postgresql.org]>.
不要将错误报告发送到任何用户邮件列表，如 < link:mailto:pgsql-sql@lists.postgresql.org[pgsql-sql@lists.postgresql.org]> 或 < link:mailto:pgsql-general@lists.postgresql.org[pgsql-general@lists.postgresql.org]> 。这些邮件列表用于回答用户问题，并且其订阅者通常不希望收到错误报告。更重要的是，他们不太可能修复它们。
Do not send bug reports to any of the user mailing lists, such as <link:mailto:pgsql-sql@lists.postgresql.org[pgsql-sql@lists.postgresql.org]> or <link:mailto:pgsql-general@lists.postgresql.org[pgsql-general@lists.postgresql.org]>. 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.
另外，请 not 发送报告到开发人员邮件列表 < link:mailto:pgsql-hackers@lists.postgresql.org[pgsql-hackers@lists.postgresql.org]> 。此列表用于讨论 PostgreSQL 的开发，如果我们能够将错误报告分开，将会很好。如果问题需要更多审查，我们可能会选择在 pgsql-hackers 中讨论您的错误报告。
Also, please do not send reports to the developers' mailing list <link:mailto:pgsql-hackers@lists.postgresql.org[pgsql-hackers@lists.postgresql.org]>. This list is for discussing the development of PostgreSQL, 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 pgsql-hackers, if the problem needs more review.
如果您对文档有任何问题，最好的报告位置是文档邮件列表 < link:mailto:pgsql-docs@lists.postgresql.org[pgsql-docs@lists.postgresql.org]> 。请具体说明您对文档的哪一部分不满意。
If you have a problem with the documentation, the best place to report it is the documentation mailing list <link:mailto:pgsql-docs@lists.postgresql.org[pgsql-docs@lists.postgresql.org]>. Please be specific about what part of the documentation you are unhappy with.
如果您的错误是在非受支持平台上的可移植性问题，请发送邮件到 < link:mailto:pgsql-hackers@lists.postgresql.org[pgsql-hackers@lists.postgresql.org]> ，以便我们（以及您）致力于将 PostgreSQL 移植到您的平台。
If your bug is a portability problem on a non-supported platform, send mail to <link:mailto:pgsql-hackers@lists.postgresql.org[pgsql-hackers@lists.postgresql.org]>, so we (and you) can work on porting PostgreSQL to your platform.
Note
由于大量垃圾邮件的不幸传播，除非您订阅，否则所有上述列表都将受限。这意味着电子邮件将在交递之前延迟一段时间。如果您希望订阅列表，请访问 https://lists.postgresql.org/获取说明。
Due to the unfortunate amount of spam going around, all of the above lists will be moderated unless you are subscribed. That means there will be some delay before the email is delivered. If you wish to subscribe to the lists, please visit https://lists.postgresql.org/ for instructions.