OceanBase 开源贡献指南从 Fork 到 PR 合并的完整协作流程【免费下载链接】oceanbaseOceanBase is the unified distributed database for the AI era — open-source, multi-model, one engine for your most demanding workloads.项目地址: https://gitcode.com/GitHub_Trending/oc/oceanbaseOceanBase 是一个开源分布式数据库其社区欢迎开发者以多种方式参与共建。本文以仓库根目录的 CONTRIBUTING.md 为骨架结合 docs/docs/zh/contributing.md英文版见 docs/docs/en/contributing.md与仓库中的 编程惯例文档系统梳理 OceanBase 的代码贡献全流程从如何找到合适的 Issue、Fork 与 Clone、本地分支开发到提交 PR、签署 CLA、通过 CI 检查直至合并的每一步操作与注意事项。读完本文你将掌握一条可完整走通的开源贡献路径并了解 OceanBase 特有的代码风格与编程惯例为提交高质量的 Pull Request 做好准备。一、贡献方式概览不止写代码参与 OceanBase 社区的方式多种多样代码提交只是其中一种。根据仓库中的贡献文档社区欢迎以下类型的贡献代码贡献修复 Bug、增加新功能这是最主要的贡献形式社区帮助在 DingTalk 群、Slack 群或 StackOverflow 上帮助新用户解答问题测试贡献参与各版本的测试工作帮助发现并反馈问题文档贡献改进和完善项目文档包括格式调整、文字修正等。无论贡献形式如何正式参与代码贡献前都应先阅读仓库根目录的 CODE_OF_CONDUCT.md确保了解并遵守社区行为准则。二、从合适的 Issue 开始新贡献者不应盲目开始写代码而是先找到合适的 Issue。官方建议的路径如下查看 Good First Issue通过good first issue标签可以筛选出适合新手入门的问题。这类问题通常范围明确、改动量适中是熟悉项目的最佳起点发现新问题如果没有合适的问题也可以自己创建 Issue。通过bug/new feature标签可以了解当前版本的已知缺陷和建议新增的功能认领 Issue找到合适的 Issue 后在 Issue 下回复/assign即可将 Issue 分配给自己同时建议在 Issue 标题中添加_developing_标签向社区表明该 Issue 正在被开发中。三、代码贡献完整流程以下流程以 Linux 环境为例综合了根目录 CONTRIBUTING.md 与 docs/docs/zh/contributing.md 中的完整操作步骤。1. Fork 项目仓库访问 OceanBase 的 GitHub 仓库点击右上角的Fork按钮在个人账号下创建一份仓库副本。后续的修改都将在这份 Fork 副本上进行通过 Pull Request 再合并回上游。2. 配置本地环境变量定义工作目录与 GitHub 账户名注意用户名需与 GitHub 账号保持一致working_dir$HOME/workspace # 定义工作目录 user{GitHub账户名} # 和 github 上的用户名保持一致3. 克隆代码并配置 upstreammkdir -p $working_dir cd $working_dir git clone gitgithub.com:$user/oceanbase.git # 也可以使用: git clone https://github.com/$user/oceanbase # 添加上游分支 cd $working_dir/oceanbase git remote add upstream gitgithub.com:oceanbase/oceanbase.git # 或: git remote add upstream https://github.com/oceanbase/oceanbase # 为上游分支设置 no_push防止误推送到官方仓库 git remote set-url --push upstream no_push # 确认远程分支配置正确 git remote -v这里的关键点是显式添加上游upstream仓库并将 upstream 的 push 地址设置为no_push从机制上杜绝误推送到官方仓库的可能。4. 创建开发分支基于最新的上游 master 创建独立分支分支名建议使用issueid的命名方式便于后续 PR 与 Issue 的关联追溯new_branch_name{issue_xxx} # 设定分支名建议直接使用 issueid 的命名 cd $working_dir/oceanbase git fetch upstream git checkout master git rebase upstream/master git checkout -b $new_branch_name5. 开发与测试在新建的分支上完成开发任务包括相应的测试任务。OceanBase 作为一个包含数百万行 C 代码的巨型工程对测试有完整的配套体系仓库中unittest/、mittest/等目录下均有大量可直接参考的测试用例。6. 提交代码# 检查本地文件状态 git status # 添加希望提交的文件 # 如果希望提交所有更改直接使用 git add . git add file ... # 为了让 github 自动将 pull request 关联上 github issue # 建议 commit message 中带上 fixed #{issueid}其中 {issueid} 为 issue 的 id git commit -m fixed #xxxx: update the xx # 推送前先同步上游最新代码 git fetch upstream git rebase upstream/master git push -u origin $new_branch_name这里有一个值得注意的细节commit message 中携带fixed #{issue_id}可以让 GitHub 在 PR 合并后自动关闭对应 Issue实现全流程自动化关联。7. 创建 Pull Request访问你 Fork 的仓库单击{new_branch_name}分支旁的Compare pull request按钮创建 Pull Request。8. 签署 CLA 协议提交 Pull Request 后需要签署 Contributor License Agreement (CLA) 才能进入下一步流程。如果未签署提交流程会被阻断并给出相应报错提示。签署完成后工作流才能继续。9. 代码审查与合并PR 创建后拥有 review、合并权限的维护者会帮助开发者进行代码 review。从源码结构看OceanBase 的代码质量把关体系贯穿于 docs/docs/zh/coding-convention.md、docs/docs/zh/coding_standard.md 等文档规范之中。review 意见通过后后续操作包括运行各项测试由维护者完成最终代码合入主干。四、PR 合并前的 CI 检查根据根目录 CONTRIBUTING.md 的说明PR 合并前必须通过两类 CI 检查检查类型检查内容Compile在 CentOS 和 Ubuntu 上编译代码确保跨发行版可编译通过Farm运行单元测试和部分 mysql 测试用例验证功能正确性其中Farm检查与仓库中的测试体系直接对应unittest/目录下存放了大量单元测试mittest/、tools/deploy等目录则包含 MySQL 兼容性测试相关的内容测试类型覆盖单元测试unit test与 MySQL 测试用例mysql test。注意如果 Farm 检查失败且你认为与自己的改动无关可以请 reviewer 重新运行 Farmreviewer 也可以主动重跑。五、PR 合并后的流程默认情况下PR 会被合并到develop分支该分支是 OceanBase 仓库的默认分支。社区会定期将 develop 分支合并到 master 分支。因此如果你想获取最新代码可以拉取 master 分支你的贡献最终会通过 develop → master 的定期合入流程进入正式主干。六、Feature 开发流程如果你希望开发一个新功能不能直接开始写代码而是需要先走社区讨论流程。官方给出的完整流程如下创建 discussion 发起讨论创建新的 Issue在官方仓库上为你的 Feature 创建新的 feature 分支在分支上完成修改并提交将修改推送到你的 Fork创建 Pull Request将代码合入 feature 分支Feature 分支合并后社区会将 feature 分支合入 master。与普通 Bug 修复相比Feature 开发多了一个先讨论、再立项的前置环节这保证了重大功能在投入开发前已经过社区层面的设计评审。七、代码风格指南与编程惯例根目录 CONTRIBUTING.md 给出的代码风格总原则是遵循现有代码风格和格式化约定编写清晰、描述性强的 commit message为复杂逻辑或算法添加注释确保代码编译无警告如果改动影响用户可见功能同步更新相关文档。在此基础上docs/docs/zh/coding-convention.md 对 OceanBase 特有的编程惯例做了更深入的说明这些是提交高质量代码前必须了解的潜规则。命名习惯文件命名代码文件名均以ob_开头存在少量陈旧例外类命名类均以Ob开头并使用 PascalCase存在少量陈旧例外成员变量命名成员变量以_作为后缀函数与变量命名使用下划线分隔的小写命名。功能编程习惯禁止使用 STL 容器。由于 OceanBase 支持多租户资源隔离为方便控制内存项目禁止使用 STL、boost 等容器而是提供自研容器如ObSEArray等。单入口单出口。强制要求所有函数在末尾返回禁止中途调用return、goto、exit等全局跳转指令。这是初次接触 OceanBase 代码最容易困惑的地方。为满足该要求代码中大量出现if/else if链并通过FALSE_IT宏减少嵌套例如int ObMPStmtReset::process() { int ret OB_SUCCESS; ... if (OB_ISNULL(req_)) { ret OB_INVALID_ARGUMENT; LOG_WARN(invalid packet, K(ret), KP(req_)); } else if (OB_INVALID_STMT_ID stmt_id_) { ret OB_INVALID_ARGUMENT; LOG_WARN(stmt_id is invalid, K(ret)); } else if (OB_FAIL(get_session(session))) { LOG_WARN(get session failed); } else if (OB_ISNULL(session)) { ret OB_ERR_UNEXPECTED; LOG_WARN(session is NULL or invalid, K(ret), K(session)); } else if (OB_FAIL(process_kill_client_session(*session))) { LOG_WARN(client session has been killed, K(ret)); } else if (FALSE_IT(session-set_txn_free_route(pkt.txn_free_route()))) { } else if (OB_FAIL(process_extra_info(*session, pkt, need_response_error))) { LOG_WARN(fail get process extra info, K(ret)); } else if (FALSE_IT(session-post_sync_session_info())) { } else if (FALSE_IT(need_disconnect false)) { } else if (OB_FAIL(update_transmission_checksum_flag(*session))) { LOG_WARN(update transmisson checksum flag failed, K(ret)); } else { // ... } return ret; }注意这类函数都以int ret OB_SUCCESS;开头ret作为统一返回值许多宏默认依赖ret的存在。函数返回错误码。绝大多数函数要求具备int返回值返回值可用 ob_errno.h 中的错误码解释。即使是取值函数如ObSEArray::at也要求返回错误码int at(int64_t idx, T obj);仅当函数是简单返回类属性如int64_t get_capacity();或简单判断时才允许不返回int错误码。所有返回值与参数必须校验。只要函数有返回值就必须检测能检就检函数参数尤其是指针使用前必须检查有效性。典型模式如下int ObDDLServerClient::abort_redef_table(const obrpc::ObAbortRedefTableArg arg, sql::ObSQLSessionInfo *session) { int ret OB_SUCCESS; ... obrpc::ObCommonRpcProxy *common_rpc_proxy GCTX.rs_rpc_proxy_; if (OB_UNLIKELY(!arg.is_valid())) { // 对传入的参数做有效性检查 ret OB_INVALID_ARGUMENT; LOG_WARN(invalid arg, K(ret), K(arg)); } else if (OB_ISNULL(common_rpc_proxy)) { // 使用指针前先检查 ret OB_ERR_UNEXPECTED; LOG_WARN(common rpc proxy is null, K(ret)); } else { ... } return ret; }约定函数接口init/destroy构造函数中仅做轻量级初始化变量置 0、指针置 nullptr复杂的初始化统一放在带int错误码返回值的init函数中对应的资源销毁由destroy函数完成reuse/reset为支持对象复用许多类提供reuse轻量清理与reset更彻底清理接口具体语义需参考具体实现类操作符重载尽量避免因其可能引发隐式类型转换或难以察觉的性能开销避免使用operator对象复制尽量采用deep_copy/shallow_copy。常用宏速查以下宏在 OceanBase 源码中高频出现理解它们是阅读代码和编写符合规范的代码的基础宏等价语义用法示例OB_SUCC(func())OB_SUCCESS (ret func())判断成功if (OB_SUCC(func())) { ... }OB_FAIL(func())判断失败同时赋值 retif (OB_FAIL(func())) { ... }OB_ISNULL(ptr)nullptr ptr判断指针为空if (OB_ISNULL(ptr)) { ... }OB_NOT_NULL(ptr)nullptr ! ptr判断指针非空if (OB_NOT_NULL(ptr)) { ... }K(obj)展开为obj, obj用于日志输出键值对LOG_WARN(fail to exec func, , K(ret));DISALLOW_COPY_AND_ASSIGN(ClassName)声明禁止复制赋值用于类私有区见下例class LogReconfirm { ... private: DISALLOW_COPY_AND_ASSIGN(LogReconfirm); };八、更深一步开发者手册如果你的贡献涉及较大改动建议系统阅读 OceanBase 开发者手册其目录索引位于 docs/docs/zh/README.md英文版见 docs/docs/en/README.md。手册按新手旅程组织主要包括开始阶段安装工具链、获取代码并编译运行、配置 IDE、编程惯例、编写并运行单元测试、运行 MySQL 测试、调试、提交代码与 PR设计与实现日志系统、内存管理、基础数据结构、架构、编程规范。在动手开发较大功能之前阅读上述内容能帮助你更好地理解 OceanBase 的底层设计。仓库根目录还有 docs/coding_standard.md、docs/logging.md、docs/memory.md 等独立文档可供深入参考。结语从找到合适的 Issue、Fork 与配置 upstream到创建分支、规范提交、发起 PR、签署 CLA、通过 CI 审查直至合并OceanBase 提供了一条完整且自动化程度较高的贡献路径。而单入口单出口、错误码返回、参数全量校验等编程惯例则是融入这一庞大代码库的入场券。当你遵循上述流程完成第一个 PR 并成功合并后你就正式成为 OceanBase 贡献者社区的一员了。【免费下载链接】oceanbaseOceanBase is the unified distributed database for the AI era — open-source, multi-model, one engine for your most demanding workloads.项目地址: https://gitcode.com/GitHub_Trending/oc/oceanbase创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考