如何参与贡献 PolarDB for PostgreSQL开源

本文分享的内容是如何参与贡献PolarDB for PostgreSQL开源。


说起开源,近年来的开源项目越来越多,开源也越来越热,那是什么原因呢?每个人都有自己的想法,我个人认为随着软件行业的发展,无论是软件的消费端还是生产端,都有对软件产品的诉求。


软件的消费端也就是我们的用户,他希望的是产品是一个长久的产品,不会因为某些原因停止服务,没有人维护了,也希望是软件产品的后续功能能得到继续支持。


作为软件的开发人员,也就是我们的生产端,他更希望的是我们能开发出更多、更新、更炫的一些功能,并能快速地分享给大家。


而开源正是给他们提供了一个非常好的温床,一个好的开源项目离不开大家的支持和贡献,更离不开好的开源管理。


而作为开源的参与者,也就很想知道如何能快速高效地参与进来,并开发出符合开源标准的高质量代码。本文将简单讲一下PolarDB for PostgreSQL开源项目开发环境的快速搭建以及一些开发的规范,最后用一个案例来演示一下如何快速参与到我们的贡献中。

 

一、开发环境搭建


作为开发人员,最想有的就是一个比较适合自己的开发环境,就像一个砍树的人需要一个锋利的斧头一样,使得自己能够快速地投入到工作中,而不是为其他繁杂的问题所影响,正所谓欲善其事必先利其器。

 

(一)开发环境搭建—系统环境搭建与依赖安装

如何参与贡献 PolarDB for PostgreSQL开源

开源环境搭建分成两部分,一部分是讲一下系统环境搭建,虽然我们在开源项目里已经提供了Docker版本的快速部署,但是还是需要给大家介绍里边具体做了什么,因为作为开发人员,如果要对这里面的内容进行开发和维护,肯定要知道里边具体都做了什么。


由于我们项目是基于PostgreSQL(后面简称为PG)开发,如果以前参与过PG的开发,基于对PG的了解,大家都知道PG是一个基于C语言开发的。我们这里首先需要安装一些C语言的编译环境以及一些依赖库,同时为了方便我们后期调试使用以及代码编辑,也需要安装一些其他的工具,比如git。这个git实际上是我们的一个代码管理工具,可以快速获取到最新代码,GDB用来调试debug我们的代码,vim可以进行一个快速的编辑,还有SSH服务等。SSH服务在集群部署中会使用到,然后安装一些PolarDB的依赖,这些依赖是后续一些编译工作能够顺利展开的重要保障。


比如说,我们这里提到的bison和flex,如果我们后期开发过程中需要添加新的SQL语法或者是对现有语法进行修改,肯定就需要安装这些依赖,为什么呢?因为我们的语法解析器正是基于两个工具进行开发的。

 

(二)开发环境搭建—源码获取与编译安装


下面介绍一下代码。

如何参与贡献 PolarDB for PostgreSQL开源

我们的代码是托管在GitHub上,可以通过前面安装的git管理工具git clone,快速获取最新的代码,同时也欢迎大家去浏览GitHub项目地址,时刻可以看到开源的最新动态以及最新讨论。


通过git clone拿到最新代码之后,我们首先要考虑的工作就是进行编译。


前面讲到装了很多依赖,这里我们的编译工作会顺利很多。我们提供了一个build.sh的快速编译脚本,通过这个脚本可以快速进行编译安装,然后它的默认安装位置就会安装到HOME目录下的polardb子目录以及polardbhome的子目录下。


这个脚本都做了什么?实际上做了三件事,就是我们的configure,用来检测依赖环境,然后生成make file,然后是我们的一些 make,进行编译,然后就是make install进行安装。


对于我们这种开发人员来讲,更关心的肯定是一些我们的自己手动编译安装的步骤,因为对于这种编译的环境,我们肯定有根据自己的这开发要求进行修改,这里提供了一些简单的手动编译过程,通过configure命令,指定几个参数来进行configure。


Configure里比如“-O0”,可以通过这种“-O0”让编译器不要去优化一些我们的代码,这样在debug过程中可以得到更多有效的信息,enable-debug实际上是在我们编译的命令上加了一些参数,比如加了个-g的参数,这样也可以在debug过程中提供代码详细的文字信息。


enable-tap-tests实际上是一个基于TAP测试框架,因为我们的产品的测试分成两部分,一部分可以认为是内核功能的测试,还有一部分功能可以认为是一些周边的工具,包括一些插件的测试,有一些周边的工具和插件,它就用了基于perl这种tap的测试框架,我们在这里面支持它,方便后期的测试。


对于Python需要支持,因为我们有些代码是基于Python开发,prefix参数指定了默认的安装目录,刚才上面提到,如果通过build.sh去进行编译安装,它指定的一个目录,我们根据自己的需要,根据自己开发的目录管理可以自己指定一个目录,然后编译DMA高可用的一个功能,我们就照着对应的目录进行编译即可。然后回到code主目录进行编译,进行安装。


最后是contrib目录,我们所有的插件都放在这个目录下面进行编译和安装。到此为止,开发环境搭建已经初步完成,可以进行编译代码的debug调试,包括编译等工作都可以在这上面运行了。


有些同学有自己的一些习惯提升开发环境,大家可以根据自己的喜好安装,比如Eclipse、Source Inside、VScode等,在这里就不做具体介绍。

 

(三)开发环境搭建—regression 测试

如何参与贡献 PolarDB for PostgreSQL开源

我们拿到了一个环境编译,安装完之后,想快速验证一下这个产品是否好用,或者怎么快速知道产品的一些特性功能。


我们提供了一个测试框架,这种测试框架实通过make check、make check-world,然后make checkdma、make check-world-dma这几个命令可以快速对产品内核的功能进行一些测试验证,包括一些周边工具的测试验证。比如make check-world,check-world,可以看到它是在5个目录下面进行分别的进行make check,如果看到它的make file是怎么写,在这么一个make check的过程中,实际上不仅它包含了上面提到的make check,make check只是测试我们内核功能。


刚才前面也提到了,测试功能主要分成内核功能还有一些设施周边的工具和插件,这种make check-world就可以测试到所有的这些模块上,它通过这种方式也包含了核心功能的测试,执行一个make check-world,它时间会稍微长一点,但是它可以做一个全量测试。

我们这个开源版本里面提供了make checkdma,这个checkdma是什么?实际上前面提到这是支持DMA高可用的一个版本,这种高可用的是一个集群版,它是三节点集群。前面像make check,make check-world,它是一个单节点模式下的运行的测试,我们想测试一下在集群下的所有测试是否通过,我们提供了一个快速的命令 make checkdma,那也可以通过make checkdma,类似于make check-world功能一样,它区别在于启动每个测试的时候都是启动一个集群的测试,而不是一个单节点测试。

 

 

二、开发规范


下面介绍一下开发规范。


大家都知道开发规范对于平时开发工作有重要的作用,但是开发人员平时对开发规范可能关注得不够,但是作为开源项目,开发规范是显得尤为重要。


大家都知道这些年PG社区发展非常快,每年有大版本的发布,他们实际上就是通过一些标准的开发规范,包括一些制度,然后能联合全世界各个国家无数优秀的开发人员,使其通过协同开发来开发出高质量的代码。


所以开发规范在开源项目中就好比一套标准,只要大家做出来的东西符合这套标准,大家就有了共同沟通的语言,它是一个开源项目能否良好持续发展的关键之一,我们的PolarDB-for-PostgreSQL依然坚持这套标准。


下面将简单介绍一下经常使用的一些规范,希望这些规范能帮助大家在开发过程中更得心应手,提升开发的代码质量,更加符合一些国际规范,为自己以后的发展提供一个好的支撑。

 

(一)编码习惯—C语言格式规定

如何参与贡献 PolarDB for PostgreSQL开源

由于我们的代码大部分都是用C语言开发,因此这里主要介绍一些C语言的开发规范。

首先是缩进,可能大家在过去的开发过程中被告知不要使用这种制表服务,就是我们Tab键。实际上PG要求使用tab键,而且是用4列制表符,大家使用时要遵循这个标准,因为所有的代码都是基于这个标准做的。


布局规则,比如大括号的位置信息怎么放置,它要遵循BSD习惯,特别是一些if、while、switch等受控块的花括号,受控块的花括号要独自占一行。


还有是限制行长度,比如每行的长度建议在80列宽度上,这个是为了代码的可读性,如果代码写得太长,可能不利于代码的阅读。那是否就不能超过80列?也不是,比如说我们的一些 errormsg可能会写得很长,如果为了80列的宽度限制而在任意位置进行切断,就会影响可读性,所以目的还是为了可读性。在保证最大可读性的情况下,我们要尽量保证80列的宽度限制。


除此之外,不要使用C++的一些注释风格,比如说双斜杠,还有C编译器,实际上是不接受这种注释的。出于相同的原因,我们也不推荐使用C++的扩展,比如在一个控制块中的一些变量的声明,比如说for语句,for语句如果在控制块里边,声明一个变量I,在这里边是不允许的,需要把这个声明变量拿到for控制框外面的。然后要follow一下注释的模式,通过这种多行注释块去填注释。

 

(二)编码习惯—如何报错


下面主要讲一下我们的报错信息。

如何参与贡献 PolarDB for PostgreSQL开源

作为开发人员,知道输出日志信息是我们和软件用户之间一个重要的交流手段,输出的正确日志信息尤其重要,为什么呢?


因为它告诉客户我们是否专业,如果写的信息很随意的,客户看到这个软件注册信息的时候,不论你是否写了一个非常优秀的算法或功能,如果你的信息写的不够专业,从用户的角度来看,他会认为这个软件产品不够专业。因此,往往我们忽略的东西可能正是一个非常关键的东西。


产品里报错信息主要通过两个函数来实现的,分别是ereport和elog。


首先讲一下ereport,可以看到ereport这个语句主要分三部分, error就是我们的严重级别,errcode就是一些错误代码,最后是errmsg。


严重级别根据PG里边的一些规范,我们这里规定是用DEBUG5到DEBUG1,包括我们的NOTICED、WARNING、ERROR、FATAL、PANIC,随着级别越来越高,对于客户的信息产生了不同的重要程度,也可以通过我们的配置文件设置给客户输出什么级别的信息。


如果是error或者更高,需要注意的是如果严重级别没有设置,或者说严重级别设置了error或者更高ereport,会终止用户定义函数的执行,并且不会返回到调用者。如果是严重级别低于error,那ereport会正常返回。


errcode指定对于该情况的一些错误标识代码,这里的错误代码是一般是由5个字符组成,这5个字符包含了一些数字和大写字母,它表示多种错误和警告情况的代码,所以它也是分层次的。


前两位一个是错误的总分类,后三个字符表示一个情况的子类,代码5个0,“00000”代表着一个成功的状态,这可以帮助我们快速定位问题的类型,也大概知道debug的方向在哪里。如果没有指定errcode错误严重性,特别是error或者更高的错误标识,会默认使用ERRCODE_INTERNAL_ERROR 。如果错误级别是warning标识符的这种, errcode会默认使用ERRCODE_WARNING 。


如果错误严重级别是在notice以及以下,就会使用ERRCODE_SUCCESSFUL_COMPLETION 这么一个errcode,这是一个默认的情况,如果没有设置errcode的话。


对于我们来讲,有的时候不用errcode是一个很方便的情况,但是如果考虑到不用errcode的时候,要很清楚地知道自己不用的原因是什么,考虑一下它们是否合适。


剩下就是errmsg 。errmsg主要是提供消息主体,就是要报错的信息。然后就是ereport,ereport这里边实际上还有很多辅助函数,就里提到了我们的errcode(),errmsg()这里边都是辅助函数,还有很多其他的辅助函数,这些辅助函数大家可以在PG的官网上进行查看。

下面讲第二种错误代码,就是说我们elog。


elog的作用是什么?它是一个旧有的模式,它可以等效于 ereport这种模式,可以看到它提供了level,错误级别是一样的,但它没有提供errcode,就跟刚才讲到的,根据严重级别提供默认的errcode。然后消息通过一个辅助函数errmsg_internal() 去show出来,过程和刚才讲到的ereport里面的errmsg是不同的,errmsg()根据地域设置设定,比如它可以翻译成对应国家的语言,比如说翻译成汉语,实际上errmsg_internal()这个语言就不会受翻译的限制,它可以自动把原的语言打印出来。


为什么还要保留这种旧有的模式呢?因为它足够简洁,在有一些内部的错误,比如说PG内核一些内部错误的时候,这种错误实际上它并不是给用户show出来的,不是用户感兴趣的这些错误,这些错误可以用这种简洁的模式进行打印,这种方式是非常方便的,因此也得到了保留。

 

(三)编码习惯—错误消息如何撰写

如何参与贡献 PolarDB for PostgreSQL开源

下面讲讲我们消息的怎么输出,这也是很关键的一个步骤。


错误消息通常分成三部分,主要的错误消息是通过简单概要的一个介绍是什么样的一个错误,如果简单概要的这个信息不够完整,或者不能够足够表达出具体的错误,也可以通过添加Detail信息,把具体的一些细节打印出来。


同时,如果你提供了比如对错误的一些修复建议,可以通过这种Hint的方式进行加入,比如可以提供一下这个东西是不是文件不见了,可以去做一些文件添加等提示信息。


然后就是引号,因为在引用时,英文文本应该都使用双引号,我们通常总是用这个引号界定文件名,包括用户提供的一些标识服务,以及其他可能包含词的一些变量,不要用他们标记那些不包含词的那种变量。为什么要这么做?实际上因为我们有一些对象在插入到信息中,它是会产生歧义的,如果不用双引号,那就产生了歧义,把它插到这个消息中,通过双引号可以避免歧义。


还有就是语法和标点,主要错误信息,例如通常第一个字母不要大写,不要用一个句点结束一个消息,甚至不要考虑用一个感叹号结束一个消息。


关于详细和提示信息,尽量要使用完整的句子,并且每一句都要用句点结束,对句子的第一个词进行首字母大写,如果后面跟着另一个句子,在句号后面放两个空格。


为什么有这些具体的建议或规范,比如主要消息为什么不要大写?第一个字母怎么不要大写?因为这些消息对于用户来讲,他会把你的信息很方便插入到各种各样语法的上下文中,如果用完整句子可能就不方便。因为通常来讲,主要消息通常不是一个语法上完整的句子,如果它是一个很长的句子,尽量把它拆分成一个主要部分和一个详细部分。不过详细和提示消息会很长,通常需要包括多个句子,为了一致,即使它们只是一个句子,也应该遵循完整句子的风格,我们要求它的首字母大写,每个句都句点结束。

如何参与贡献 PolarDB for PostgreSQL开源

关于大写和小写方面,对消息使用小写的这种形式,主要错误消息里面第一个字母也要小写,如果是SQL命令,一些关键词出现在消息中,请为它们使用大写,因为这也是为了明确告诉大家这些信息。然后避免要被动态,尽量使用主动语态,在有主语时使用完整的句子,比如说类似于“A could not do B”,如果主语是程序本身,请使用没有主语的电报风格,但不要为程序加上“I”。因为程序并不是人,所以不需要去假装。


现在时和过去时,如果一次尝试做某事失败,但是可能下一次就成功了,就使用过去式,如果失败必定是持久的,那就使用现在时。比如下面这两个句“could not open”和“cannot open”有什么区别?第一个表示打开文件尝试失败,该消息应该给出一个具体的原因,比如说磁盘满了或者是文件不存在,过去时更合适,因为下一次磁盘可能就不满了,或者是文件就存在了。第二种形式表示打开所提及的文件的功能在程序中根本就不存在,或者概念上是不可能的,现在时更合适,因为在该种情况下将无限保持,就是这种错误的无限保持,不可能因为这个文件存在。因为你的功能没有,即使文件存在,也没有这个功能,为什么要这样呈现?普通用户没有能力从消息的时态上得出重要的结论的,但是由于语言给我们提供了语法,就应该正确地使用它。

如何参与贡献 PolarDB for PostgreSQL开源

关于对象类型,在引用一个对象名称时,说明该对象的类型,因为如果不说明它就没有人会了解这个对象是什么类型,比如 “foo.bar.baz”具体是什么东西,我们需要给它一个具体说明。


然后是组装错误消息。比如有一些消息是在别处生成的,这种产生的文本怎么嵌入到我们消息里面。消息总是要说明为什么错误会发生,如果没有已知的原因,最好去修复这个代码。比如一个错误的实例 “could not open file”,这种没有给的原因,没有给原因就不确定错误的信息是怎么产生的。最好的是说比如 “could not open file”,然后改给它一个I/O failure,是因为I/O错误导致的。


不要在消息中使用函数名,可能大家开发过程中经常会在日志里用到这个函数名,但是日志写函数名实际上对用户来讲是没有任何作用的,因为他不清楚你在里边实现什么样的,请大家把函数名保留在debug阶段,最后提交的时候还是要把函数名去掉,写成一个合规的错误消息。


避免缩略语,比如尽量不要使用“can't”,应该使用“cannot”。避免使用“Unable、Bad、Illegal、Unknown”这种单词,为什么?比如说unable,它更接近于被动态,使用“cannot”等会更好。比如bad result这种错误信息,实际上很难从错误信息中知道到底是什么东西,最好是写出一个结果不好原因,比如Invalid format,是一个无效的格式。Illegal表示违反法律,最好是写成Invalid,如果说明为什么无效就更好了。尝试避免Unknown,为什么?比如说Unknown responds,如果你不知道响应是什么,怎么知道它是错误的?应该使用Unrecognized,相当于没有识别或这是一个更好的选择。


Find and Exists,找到还是存在的问题。如果是使用了某个算法去查找,而算法执行失败了,就用无法找到更好,如果是已知的资源位置,但是程序无法去找到它,那不存在会更合适一点。

 

(四)编码习惯—其他编码习惯


下面介绍一下其他的一些编码习惯。

如何参与贡献 PolarDB for PostgreSQL开源

比如我们在C语言里一些宏和内联函数,因为带有参数的宏和内联函数在代码中经常会被使用,当使用宏时有多次计算风险的时候,就推荐使用后者,如果是其他情况,只能尽量去使用宏,因为宏使用起来会更容易一点。


信号处理函数是一个很重要的部分,因为除了一些特殊的代码,信号处理函数处理不好会导致程序混乱,在信号处理器中,只应该调用那些对异步信息安全的函数,比如在处理信号的时候去操作一个锁,这个锁是在外部调用的,已经锁上了,此时信号处理函数中要去加这个锁可能会发生什么,大家清楚。在这里推荐只是提示一下这个信号已经到达,并用一个 latch 去唤醒信号处理器之外的一些代码,比如记录一下这是一个sigh up信号,同时去唤醒一些其他代码去执行。

如何参与贡献 PolarDB for PostgreSQL开源

还有就是调用函数指针,如果函数指针是个简单的变量,调用的时候推荐显式调用,虽然不加也是会有效的。

 

(五)编码习惯—其他语言编码规范

如何参与贡献 PolarDB for PostgreSQL开源

如上所示,还有一些其他的开发规范。因为我们不仅有C语言,还有其他的语言,大家自行参考上方地址的信息,参考对应的代码规范。

 

 

三、开发示例


下面将简单用一个实例验证,告诉大家如何快速加入到我们的开源项目中。


我们通过git clone那个项目代码,这里已经gitclone好了,可以看一眼gitlog,看到已经更新到最新的位置信息了。

如何参与贡献 PolarDB for PostgreSQL开源

下面是我们刚才讲到的提供了一个docker的快速启动方式。

如何参与贡献 PolarDB for PostgreSQL开源

比如build出一个docker版本,我们可以通过这个命令,比如这个命令可以用社区提供的dockerfile去创建。

如何参与贡献 PolarDB for PostgreSQL开源

创建以后我们可以看到这个Images。

如何参与贡献 PolarDB for PostgreSQL开源

可以看到生成好的一个Image,通过Image就可以直接启动集群。

如何参与贡献 PolarDB for PostgreSQL开源

我们需要把它停下来,去启动我们的集群。通过我exec命令登记到集群里边,进来以后可以看到代码已经给它git clone下来了。

如何参与贡献 PolarDB for PostgreSQL开源

我们可以尝试看一下build.sh。

如何参与贡献 PolarDB for PostgreSQL开源

可以看到是下图这样,但是我们看到没有语法高亮,尝试一下用vim去看一下语法高亮。

如何参与贡献 PolarDB for PostgreSQL开源

没有提供我们的vim,就需要去装一个。

如果发现没有去装,我们是否可以让社区版自己提供vim,这样下次使用的时候就可以不用自己安装了,这就是我们修改贡献开源的一个好处。

如何参与贡献 PolarDB for PostgreSQL开源

装好以后,我们就可以看到高亮了。

如何参与贡献 PolarDB for PostgreSQL开源

这个改进是否可以直接把它作为代码提交到开源社区,答案是当然可以,这里边已验证了,通过安装vim就可以了。

我们转到docker目录。

如何参与贡献 PolarDB for PostgreSQL开源

Docker目录里,我们打开了dockerfile,可以在这里进行安装,比如加一个vim

如何参与贡献 PolarDB for PostgreSQL开源

我们去验证一下这个改进是否可以。

如何参与贡献 PolarDB for PostgreSQL开源

如上所示,这样就可以了。

我们重新拉起了一个,登进来以后看一下是否直接就可以进行一个vim。

如何参与贡献 PolarDB for PostgreSQL开源

出现上图则说明我们这个功能是ok的,可以把这个代码进行提交。

进行代码提交的时候,首先给它一个新的branch,比如叫fix_dockerfile,然后给它checkout fix_dockerfile,可以看一下我们是在哪个分支上。

如何参与贡献 PolarDB for PostgreSQL开源

这个时候我们可以看到更改这个文件已经可以了,这里还有更改历史。

如何参与贡献 PolarDB for PostgreSQL开源

如何参与贡献 PolarDB for PostgreSQL开源

如何参与贡献 PolarDB for PostgreSQL开源

可以看到我们的提交已经完成了。

如何参与贡献 PolarDB for PostgreSQL开源

那怎么把我们的提交推到社区呢?提交前需要git check到master。

如何参与贡献 PolarDB for PostgreSQL开源

接着需要更新一下代码,更新了代码以后要checkout fix_dockerfile,我然后再rebase master就可以提交了。

如何参与贡献 PolarDB for PostgreSQL开源

这样我们就把代码提交到社区了,之后可以看一眼我们的代码。

如何参与贡献 PolarDB for PostgreSQL开源

我们可以通过建一个pull request,然后Comepare pull request。

如何参与贡献 PolarDB for PostgreSQL开源

然后可以看到docker file,描述一下这是一个什么提交

如何参与贡献 PolarDB for PostgreSQL开源

然后通过create poll request就可以把我们的代码快速提到master分支里,到这整个代码提交流程包括修改流程就基本完成了。

如何参与贡献 PolarDB for PostgreSQL开源

这里我把命令列出来,大家可以参考一下。

如何参与贡献 PolarDB for PostgreSQL开源

下面是一些git的命令。

如何参与贡献 PolarDB for PostgreSQL开源

最后,欢迎大家一起加入到我们的开源项目中,贡献一份力量,提出一些想法,让我们一起努力,把这个项目做大做强。

上一篇:C#语法——泛型的多种应用


下一篇:XenServer 6.5实战系列之十二:License Management