pgBackRest代码贡献指南：如何为开源项目添砖加瓦

【免费下载链接】pgbackrest Reliable PostgreSQL Backup & Restore 项目地址: https://gitcode.com/gh_mirrors/pg/pgbackrest

pgBackRest是一款可靠的PostgreSQL备份与恢复工具，作为开源项目，它的发展离不开社区贡献者的支持。本文将为你提供一份详尽的代码贡献指南，帮助你顺利参与到pgBackRest的开发中，为这个强大的PostgreSQL备份工具添砖加瓦。

一、开发环境搭建：从零开始的准备工作 🚀

要为pgBackRest贡献代码，首先需要搭建一个合适的开发环境。以Ubuntu 22.04为例，你需要安装一系列开发工具和依赖库。打开终端，输入以下命令：

sudo apt-get install rsync git devscripts build-essential valgrind autoconf \
       autoconf-archive libssl-dev zlib1g-dev libxml2-dev libpq-dev pkg-config \
       libxml-checker-perl libyaml-perl libdbd-pg-perl liblz4-dev liblz4-tool \
       zstd libzstd-dev bzip2 libbz2-dev libyaml-dev ccache python3-distutils meson

部分单元测试和所有集成测试需要Docker。安装Docker的命令如下：

curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker `whoami`

环境准备好后，克隆pgBackRest仓库：

git clone https://gitcode.com/gh_mirrors/pg/pgbackrest

二、编码规范：写出优雅的代码 ✨

在开始编码之前，务必阅读项目的CODING.md文件，了解详细的编码标准。这里简要介绍几个重要的概念：

内存上下文（Memory Contexts）

内存分配在上下文中进行，可以是长期的（用于对象）或临时的（用于函数）。通常，使用OBJ_NEW_BEGIN(MyObj)创建对象，使用MEM_CONTEXT_TEMP_BEGIN()处理函数中的临时内存。更多细节请参考src/common/memContext.h。

日志记录（Logging）

使用内置宏FUNCTION_LOG_*()和FUNCTION_TEST_*()进行调试日志记录。FUNCTION_LOG_*()用于生产环境日志，FUNCTION_TEST_*()在生产代码中会被编译掉。用户信息通过LOG_*()宏提供，错误通过THROW_*()宏抛出。详细信息见src/common/log.h和src/common/error/error.h。

三、测试：确保代码质量的关键步骤 🧪

pgBackRest有完善的测试体系，提交代码前必须进行充分的测试。

查看测试组合

运行以下命令查看所有可能的测试组合：

pgbackrest/test/test.pl --dry-run

生成测试文件

部分文件在make过程中自动生成，其他则通过测试工具生成：

pgbackrest/test/test.pl --gen-only

运行测试

根据是否使用Docker，测试运行方式有所不同。

不使用Docker

列出不需要容器的测试：

pgbackrest/test/test.pl --dry-run

运行单个测试：

pgbackrest/test/test.pl --vm-out --module=common --test=wait

运行整个模块：

pgbackrest/test/test.pl --module=postgres

使用Docker

构建测试容器：

pgbackrest/test/test.pl --vm-build --vm=u22

运行特定测试：

pgbackrest/test/test.pl --vm=u22 --module=postgres --test=interface --run=2

编写单元测试

目标是实现100%的代码覆盖率。主要涉及两个文件：

1. define.yaml：定义每个模块和测试文件的测试数量。
2. src/module/somefileTest.c：单元测试代码，与被测试代码目录结构对应。

测试结果通过harnessTest.h中定义的宏进行验证，如TEST_RESULT_STR、TEST_RESULT_UINT、TEST_ERROR等。

四、添加新选项：扩展功能的正确方式 ⚙️

要为命令添加新选项，需要修改两个文件：

src/build/config/config.yaml

定义选项的类型、适用命令、默认值等。例如：

repo-test-type:
    section: global
    type: string
    group: repo
    default: full
    allow-list:
      - full
      - diff
      - incr
    command:
      backup: {}
      restore: {}
    command-role:
      main: {}

src/build/help/help.xml

为新选项添加文档：

<option id="force" name="Force">
    <summary>Force a restore.</summary>
    <text>By itself this option forces the <postgres/> data and tablespace paths to be completely overwritten.</text>
    <example>y</example>
</option>

添加选项后，运行帮助命令测试：

pgbackrest/test/test.pl --module=command --test=help --vm-out

五、提交Pull Request：成为贡献者的最后一步 🎉

在提交Pull Request之前，请确保：

• 代码符合编码标准
• 单元测试覆盖率达到100%
• 帮助和文档测试已运行
• 通过持续集成测试

提交Pull Request时：

• 提供简洁的标题
• 详细描述提交目的和解决的问题
• 选择integration分支作为基础

提交后，及时响应审核意见，与审核者积极沟通。

最后，感谢你为pgBackRest的贡献！你的每一行代码都在让这个PostgreSQL备份工具变得更加强大和可靠。

【免费下载链接】pgbackrest Reliable PostgreSQL Backup & Restore 项目地址: https://gitcode.com/gh_mirrors/pg/pgbackrest