向Greenplum报ISSUE的正确姿势

开源项目

2019-03-20

作为github上活跃的开源项目，Greenplum每天约有数十次代码提交，平均每月发布一次新版本，每个版本在引进新功能的同时也会修复已知的问题。Greenplum开发人员高度重视包括开源社区用户在内的所有用户的反馈，欢迎大家在Greenplum github上提交issue。根据我们的经验，发现以往有些issue很难被处理，浪费了许多不必要的时间，例如没有足够多的信息或者无法重现等。在这里详细说明什么样的ISSUE报告会比较高效，可以得到较快的修复，并介绍Greenplum的相关资源。大家可以充分利用正确的资源解决遇到的问题。

1. 区分问题和bug

Github上的ISSUE主要是用来描述代码中存在的bug，而不是软件的使用问题。因此第一步要明确想要问的内容，是属于问题还是属于bug。如果是bug，可以github上创建ISSUE并提供详细的信息供开发人员参考；如果不是bug，开发人员通常会忽略这些问题。在后面会介绍如何寻求这些问题的答案。

对于新接触Greenplum的人员来说，bug和问题的界限可能并不是十分明显，但下面几个大的准则可以参考：

询问Greenplum对某些功能的支持情况，不属于bug
询问如何执行某些操作的，不属于bug
询问某些概念的，不属于bug
询问实现细节的，不属于bug
A版本正常但在B版本上出错，通常属于bug
查询执行时出现内存溢出或者进程异常崩溃，属于bug
期望对某个功能做增强，虽然不属于bug但可以在issue里讨论
……

2. 开源版和企业版Greenplum的区别

Pivotal会为其客户提供Greenplum企业版发布，二者最重要的区别之一是，Greenplum的企业版提供了更多产品组件和第三方合作伙伴的产品，如gptext，gpcc，jdbc驱动等。它们不属于Greenplum源码的一部分，因此不在Greenplum的ISSUE覆盖范围内。对付费用户的企业版支持，推荐直接联系Pivotal的官方售后和售前团队，他们也是更专业的团队，可以快速对问题进行诊断和排查。

开源Greenplum的ISSUE里，通常不会对下列问题有及时的回复：

闭源组件，例如GPTEXT，GPCC等
合作伙伴的产品，例如数据迁移产品，驱动程序等
不支持的运行平台，例如Windows，AIX等

3. Greenplum的社区资源

代码库

Greenplum的代码托管在GitHub上，这个代码库对全部用户可见，大家可以在上面提ISSUE或者发pull request（参见如何成为Greenplum的代码贡献者）。

开发者讨论组

Greenplum的开发者邮件地址为gpdb-dev@pivotal.io，任何跟Greenplum开发有关的问题可以直接在开发组提问。需要注意的是加入这个邮件组需要fanqiang。加入以后就不需要再fanqiang了，因为讨论邮件就会直接发往注册邮箱。有很多重磅的消息通常都会在开发组里发布，比如Postgres合并工作的进展（最新消息可参考），以及某些重大新特性的设计等等。

用户组

Greenplum的用户邮件组地址为gpdb-users@pivotal.io，这里主要讨论Greenplum的使用问题，比如对特定功能的支持情况，使用中出现的性能问题，安装时遇到的困难等等。

文档

Greenplum的每个版本都可以在官方网站找到相应的文档，里面对产品的使用做了详细的介绍，大部分问题及解决办法在文档里都有描述，仔细阅读文档可以节省很多后期部署调试的时间。

社区网站

开源版Greenplum的网站为greenplum.org，这里汇集了包括官方资源在内的很多有用资源，包括sandbox下载，用户问答等，对Greenplum新手来说是一个理想的入门起点。

中文资源
CSDN上有Greenplum的中文论坛
知乎上也有Greenplum的主题
Pivotal国内有两个微信公众号会（pivotal, pivotal研发中心）定期推送相关文章，也有微信群和QQ群供大家交流讨论。

4. ISSUE的基本要求

在报ISSUE之前，有一些准备功课需要预先做好，这里列举如下：

充分利用各种搜索功能，避免报告一个已知问题或者已修复问题
尽可能确保在最新版Greenplum上复现bug，因为Greenplum只在最新版本进行bug修复

当你确定发现了Greenplum的一个新的bug时，我们非常希望你可以在ISSUE里将其正确清楚的描述出来，这样我们的开发人员会在第一时间评估其影响并给与适当的反馈。如果问题严重，将会在第一时间的到修复。

报ISSUE的一个原则是，正确清楚的描述问题，并根据实际情况，尽可能附带原始数据和详细复现步骤。报ISSUE时，有一个官方的模板，对应的中文版本如下：

### Greenplum 版本号或commit id
### 操作系统版本和命令 uname -a 的输出
### autoconf的参数 ( config.status --config )
### 安装信息 ( pg_config / gp_state 的输出)
### 期望的行为
### 实际行为
### 复现步骤

这上面的信息中最重要的信息是日志信息。Greenplum 由于分布式原因，每个segment都会有日志，需要 1）Master pg_log下面的相关日志文件或者出错的那一条日志；2）出错的segment上面的日志信息。此外各种工具，譬如gpstart、gpstate、gprecoverseg 等会默认保存日志到 ~/gpAdminLogs/, 这里面的日志对于分析 Greenplum 的各种管理工具非常重要。

ISSUE描述以准确为主，尽可能提供详尽的信息便于复现。可以用中英文描述，有语法错误也没关系。例如下面几个ISSUE的内容可以参考：

gpadmin=# select c1, c2, grouping(c1), grouping(c2) from (select i as c1, i as c2 from generate_series(1, 2) i) as s1 group by rollup(c1, c2) order by c1, c2;
 c1 | c2 | grouping | grouping
----+----+----------+----------
  1 |  1 |        0 |        0
  1 |    |        0 |        1
  2 |  2 |        0 |        0
  2 |    |        0 |        1
    |    |        1 |        1
(5 rows)

另一个例子：

gpadmin=# set optimizer to off;
SET
gpadmin=# select c1, c2, grouping(c1), grouping(c2) from (select i as c1, i as c2 from generate_series(1, 2) i) as s1 group by rollup(c1, c2) order by c1, c2;
 c1 | c2 | grouping | grouping
----+----+----------+----------
  1 |  1 |        0 |        0
  1 |  1 |        0 |        1
  2 |  2 |        0 |        0
  2 |  2 |        0 |        1
    |    |        0 |        1
(5 rows)

### Greenplum version or build
GPDB 5.2

### OS version and uname -a
Centos

### autoconf options used ( config.status --config )
### Installation information ( pg_config )
Testing dblink from Greenplum to access Postgresql 8.3.23 and 9.6

### Expected behavior
gpadmin=# SELECT dblink_connect('host=postgresql port=5432 dbname=postgres');
Connection is successful when we run these commands.

### Actual behavior
ERROR: could not establish connection
DETAIL: FATAL: unsupported frontend protocol 28675.0: server supports 1.0 to 3.0

### Step to reproduce the behavior.
Follow these instructions to setup DBLink on GPDB 5.2
Link: https://gpdb.docs.pivotal.io/520/utility_guide/dblink.html

ISSUE成功报告后，会在第一时间分配给相应的开发team。同时整个Greenplum社区也会感激你高质量的ISSUE报告。