缺陷报告指南

标识缺陷

在你报告一个缺陷之前，请阅读再阅读文档来验证你真地可以做你正在尝试的任何东西。如果从文档中无法清楚地知道你是否能做某事，也请把它报告给我们；这是一个文档中的缺陷。如果发现一个程序做的事情和文档说的不一样，那就是一个缺陷。那可能包括（但不限于）下列情况：

• 一个程序带有一个致命信号或者一个操作系统错误消息终止，它们会指出程序中的一个问题（一个反例是一个"磁盘满"消息，因为你只能自己修复它）。

• 一个程序对任何给定的输入产生错误的输出。

• 一个程序拒绝接受合法的输入（按文档定义）。

• 一个程序接受非法输入，并且没有提示或者错误消息。但是记住你对非法输入的概念可能是我们认为的一个扩展或兼容性。

• PostgreSQL根据在被支持平台上的指导无法编译、建立或者安装。

这里的"程序"指任何可执行文件，不仅仅是后台进程。

很慢或者很占资源不一定是一个缺陷。阅读文档或者在邮件列表中寻求帮助来调优你的应用。无法符合SQL标准也不一定是一个缺陷，除非文档中已经明确地声明指定特性是兼容的。

在你继续之前，检查 TODO 列表和 FAQ 来看你的缺陷是否为已知。如果你不能理解 TODO 列表中的信息，那就报告你的问题。至少我们可以让 TODO 列表更清晰。

报告什么

关于缺陷报告要记住的最重要的事情是说明事实并且只说明事实。不要推断你觉得什么出错了、"它看起来在做"什么或者程序的哪一部分出错了。如果你不熟悉实现，你可能猜错并且不会帮到我们。而且即使你熟悉实现，受过训练的解释是巨大的补充但是也无法替代事实。如果我们想要修复缺陷，我们还是需要首先重现它。报告裸的事实相对直接（你可以直接从屏幕上拷贝和粘贴它们）但是可能有太多重要的细节被略去，因为某些人可能认为它不重要（所以没有包含在报告中）或者报告可能以其他方式被理解。

下列项应该被包含在每一个缺陷报告中：

• 从程序启动开始的准确步骤序列，我们需要它们来重现问题。这应该是自包含的，如果输出是依赖于表中的数据，那么只发送一个裸的SELECT语句而不发送前面的CREATE TABLE和INSERT语句是不够的。我们没有时间来对你的数据库模式做逆向工程，而且即使我们能够通过我们自己的数据来弥补，我们也很可能会错过问题。

  SQL 相关问题的一个测试样例的最佳格式是一个可以通过psql前端运行并展示该问题的文件（注意不要在你的~/.psqlrc启动文件中包含任何东西）。一种简单的创建该文件的方法是使用pg_dump来转储出表声明和设置场景的数据，然后增加问题查询。我们鼓励你最小化你的例子的尺寸，但是这不是绝对必要的。如果缺陷是可重现的，我们以两种方法都可以找到它。

  如果你的应用使用某些其他客户端接口（例如PHP），那么请尝试隔离出错的查询。我们将可能无法设置一个网页服务器来重现你的问题。在任何情况中记住提供准确的输入文件，不要猜测问题是因为"大文件" 或"中等大小的数据库"等而发生，因为这些信息用起来太不准确。

• 你得到的输出。请不要说它"无法工作"或者"崩溃了"。如果有一个错误消息，请展示它，即使你不理解它。如果程序带着一个操作系统错误而终止，请说出它。如果根本没有发生任何事情，也说出来。虽然你的测试样例的结果是一次程序崩溃，但是显然它不一定会在我们的平台上发生。如果可能的话，最简单的事情就是从终端上复制你的输出。

  注意: 如果你正在报告一个错误消息，请获得消息的最冗长的形式。在psql中，预先执行\set VERBOSITY verbose。如果你在从服务器日志抽取消息，设置运行时参数log_error_verbosity为verbose，这样所有的细节将被记录在日志中。

  注意: 在致命错误的情况中，客户端报告的错误消息可能不会包含所有可用的信息。请也看看数据库服务器的日志输出。如果你没有保留你的服务器的日志输出，这将是一个最好的时机开始记录它。

• 你所期望的输出也是需要说明的很重要的内容。如果你只写"这个命令给我那个输出。"或"这不是我所期待的。"，我们可能自己运行它、扫描输出并且认为它看起来 OK 并且正是我们期望的。我们不会花时间来理解你的命令背后的准确语义。特别是避免仅仅说"这不是 SQL 所说的/Oracle 所作的。"从SQL中挖掘出正确的行为不是一个有趣的工作，我们也没法去了解所有的其他关系型数据库的行为（如果你的问题是一个程序崩溃，你显然可以忽略这一项）。

• 任何命令行选项和其他启动选项，包括任何相关的环境变量或者你从默认修改过的配置文件。再次，请提供准确的信息。如果你在使用一个预打包的发布并且它在系统启动时自动开始数据库服务器，你应当尝试找出它是怎样启动的。

• 任何你做的和安装指导上不同的地方。

• PostgreSQL的版本。你可以运行命令SELECT version();来找出你连接到的服务器的版本。大部分可执行程序也支持一个--version选项，至少postgres --version和psql --version可以工作。如果该函数或选项不存在，那么你的版本就已经老得无法保证可以升级了。如果你运行的是一个预打包的版本（如 RPM），请说明并且包括该包的任何子版本。如果你在谈论一个 Git 快照，也请说明并且包括提交哈希值。

  如果你的版本比 9.6.0 更老，我们将几乎肯定会告诉你进行升级。在每一个新的发布中都包含很多缺陷修复和改进，因此很有可能你在旧版本PostgreSQL中碰到的一个缺陷已经被修复了。我们对使用旧版本PostgreSQL的站点只提供有限的支持。如果你需要更多支持，请考虑咨询一个商业支持。

• 平台信息。这包括内核名称和版本、C 库、处理器、内存信息等等。在大部分情况中，提供厂家和版本就足够了，但是不要假定每个人都了解"Debian"中到底包含什么或者每个人都运行在 i386 上。如果你碰到的是安装问题，那么你机器上的工具链（编译器、make等等）的信息也是需要被报告的。

不要担心你的缺陷报告变得太长。这就是生活。最好是第一次就报告所有的东西，而不是让我们去从你那里询问。在另一方面，如果你的输入文件太大，最好先问问是否有人有兴趣去看它。这里有一篇文章勾勒了一些报告缺陷的提示。

不要把你所有的时间花费在指出输入中的哪些改变让问题消失。这可能对解决问题没有什么帮助。如果发现缺陷不能被立马解决，你将还有时间去寻找和分享你的解决方法。同样，不要浪费你的时间去猜测为什么缺陷会存在。我们将尽快找出原因。

在编写一份缺陷报告使，请避免使用含糊的术语。这个软件包从整体上被称为"PostgreSQL"，有时会简称为"Postgres"。如果你要谈论特定的后端进程，不要只说"PostgreSQL 崩溃了"。一个单一后端进程的崩溃和其父"postgres"进程崩溃是完全不同的；当你想说一个单一后端进程垮掉时，请不要说"服务器崩溃了"，反之亦然。还有，如交互式前端"psql"等的客户端程序和后端是完全独立的。请尽量确定问题是发生在客户端还是服务器端。

向哪里报告缺陷

通常，请把缺陷报告发送到缺陷报告邮件列表<pgsql-bugs@postgresql.org>。你会被要求给你的电子邮件消息加上一个描述性的主题，可以用错误消息的一部分。

另一种方法是填写项目网站上的缺陷报告网页表格。以这种方式输入的缺陷报告会被发送到<pgsql-bugs@postgresql.org>邮件列表。

如果你的缺陷报告牵涉到安全并且你不想让它立刻变得公众可见，不要把它发送到pgsql-bugs。安全问题可以被私下报告给<security@postgresql.org>。

不要将缺陷报告发送到任何一个用户邮件列表，例如<pgsql-sql@postgresql.org>或<pgsql-general@postgresql.org>。这些邮件列表是用来回答用户问题的，并且它们的订阅者通常不希望收到缺陷报告。更重要的是，他们不可能去修复缺陷。

另外，请不要把报告发送给开发者邮件列表<pgsql-hackers@postgresql.org>。这个列表是用来讨论PostgreSQL开发的地方，并且把缺陷报告隔离开对我们会比较好。如果问题需要更多的审查，我们可能选择在pgsql-hackers上对你的缺陷报告展开一次讨论。

如果你有一个关于文档的问题，报告它最好的地方是文档邮件列表<pgsql-docs@postgresql.org>。请指出你对文档的哪个部分不爽。

如果你的缺陷是一个在非被支持平台上的移植性问题，请发送邮件到<pgsql-hackers@postgresql.org>，这样我们（和你）就可以做些工作把PostgreSQL移植到你的平台。