尧图网页设计 
Apache bRPC 贡献指南从 Issue 到 PR 的完整参与路径与代码规范【免费下载链接】brpcbrpc is an Industrial-grade RPC framework using C Language, which is often used in high performance system such as Search, Storage, Machine learning, Advertisement, Recommendation etc. brpc means better RPC.项目地址: https://gitcode.com/GitHub_Trending/brpc/brpcbRPC 是一个用 C 编写的工业级 RPC 框架常用于搜索、存储、机器学习、广告、推荐等高性能系统。本文基于仓库根目录的 CONTRIBUTING.md 展开系统梳理向 bRPC 提交贡献的完整流程如何报告问题、提出新功能需求、编写并提交 PR以及 PR 前后必须满足的代码风格、代码组织与单元测试要求。读完本文你将掌握 bRPC 社区认可的开发规范、测试组织方式与 CI 检查机制能够高质量地参与这个开源项目的共建。一、贡献流程总览两条主要路径根据 CONTRIBUTING.md 的说明向 bRPC 贡献有两种典型路径报告问题或请求新功能遇到任何问题bug、使用障碍、文档疑问等或者需要新功能欢迎创建 issue。仓库提供了标准化的 issue 模板见 .github/ISSUE_TEMPLATE/bug_report.mdbug 报告模板和 .github/ISSUE_TEMPLATE/feature_request.md功能请求模板提交时选择合适的模板填写能让维护者更快定位与响应。解决已有 issue 并提交 PR如果你能解决 issue 列表中任何一个问题欢迎将代码以 Pull RequestPR的形式提交给社区评审。整个参与流程可以概括为发现问题 → 创建 issue → 认领/解决 issue → 本地编码与测试 → 提交 PR → 通过 CI 检查 → 合并。其中 PR 前后各有关键要求下面逐一展开。二、提交 PR 前的三项硬性要求CONTRIBUTING.md 明确列出了提交 PR 之前必须确认的三件事这是每个贡献者绕不开的关卡1. 代码风格必须符合 Google C Style规范基准代码风格需符合 Google C 编码规范Google C Style Guide这是 bRPC 全仓库代码的基础风格。缩进要求文档明确要求缩进最好为 4 个空格Indentation is preferred to be 4 spaces。在 bRPC 的源码中这一约定贯穿始终例如 src/brpc/policy/redis_protocol.cpp 等核心文件的函数体、嵌套代码块均使用 4 空格缩进。从仓库结构看src/brpc 下的所有核心模块channel、server、controller、socket 等都严格遵循该风格新增代码应当与既有代码保持视觉上的一致这能显著降低评审成本。2. 代码必须出现在它应该在的位置这是 bRPC 贡献规范中最具项目特色的要求原文强调特定协议的扩展代码不应放在通用类中例如为某个特定协议protocol新增的支持代码不应该塞进 src/brpc/server.cpp、src/brpc/channel.cpp 这类通用类中。非常通用的改动也不该深藏在某个特定协议内部如果一个改动影响面大、属于通用能力就不应把它隐藏在某个具体协议的 cpp 文件里。这一原则在仓库的物理布局中有清晰印证bRPC 将所有协议的实现集中放在 src/brpc/policy 目录下每种协议一个独立文件。例如Redis 协议src/brpc/policy/redis_protocol.cppHTTP 协议src/brpc/policy/http_rpc_protocol.cppThrift 协议src/brpc/policy/thrift_protocol.cppgRPC/H2 协议src/brpc/policy/http2_rpc_protocol.cpp负载均衡策略src/brpc/policy/round_robin_load_balancer.cpp 等而真正通用的能力如 src/brpc/server.h、src/brpc/channel.h则保留在通用层。从源码结构可以推断这是 bRPC 长期演进形成的一种约定新增协议时遵循协议代码进 policy 目录、扩展点用注册/适配机制接入的模式避免通用类无限膨胀也方便按协议独立测试与维护。如果你要扩展某个协议先在 src/brpc/policy 中找到对应实现参考其写法如果你要做通用改动优先考虑是否会影响所有协议使用者并评估是否需要补充通用层的测试。3. 必须包含单元测试文档要求每个 PR必须有对应的单测代码Has unittests。这一点在仓库中有大量实证全部测试位于 test 目录每个核心模块都有对应的*_unittest.cpp文件例如服务器核心test/brpc_server_unittest.cpp通道核心test/brpc_channel_unittest.cppRedis 协议test/brpc_redis_unittest.cpp负载均衡test/brpc_load_balancer_unittest.cpp测试基于 GoogleTestgtest框架编写测试构建配置见 test/CMakeLists.txt使用 Bazel 构建时测试目标定义在 test/BUILD.bazel 中。测试运行脚本 test/run_tests.sh 会批量执行test_butil、test_bvar、bthread*unittest、brpc*unittest等测试二进制并开启 ASandetect_leaks1:detect_stack_use_after_return1、开启 coredump 以便失败时用 gdb 抓取调用栈。从该脚本可以看出bRPC 对内存安全和崩溃现场还原非常重视贡献者的单测也应当尽可能覆盖边界条件与内存路径。以 test/brpc_redis_unittest.cpp 为例它是单测应该如何写的样板该测试会在本机 fork 一个真实的redis-server监听 6479 端口作为被测对象再通过 brpc 的 Redis 客户端发起请求并断言结果覆盖了协议编解码、命令路由、认证等多个层面。可以推断为协议类改动编写单测时参考这类拉起真实服务 端到端断言的集成测试模式是最贴合 bRPC 现状的做法。三、提交 PR 后的检查GitHub Actions CICONTRIBUTING.md 要求提交 PR 之后必须确保 GitHub Actions 流水线通过Make sure the GitHub Actions passed。CI 配置集中在 .github/workflows 目录其中核心的是 .github/workflows/ci-linux.yml 与 .github/workflows/ci-macos.yml。以 Linux 流水线为例从源码结构看它覆盖了非常完整的验证矩阵任何 PR 都要经过这些检查检查维度具体内容说明构建系统make / cmake / bazel 三套保证三种主流构建方式都可用编译器gcc / clang双编译器矩阵发现平台相关隐患编译选项--werror警告即错误、--with-thrift、--with-glog、--with-rdma、--with-asan、--with-debug-lock、--with-bthread-tracer等全功能开关下的编译验证详见 .github/workflows/ci-linux.yml 中的 matrix 定义单元测试bazel test --configrdma --configubring //test/...以及 make 下的cd test make sh ./run_tests.sh全量单测必须在 CI 中通过Protobuf 兼容分别编译 protobuf 3.5.1 / 3.12.4 / 21.12 等版本保证对多个 protobuf 版本向后兼容从 CI 配置可以推断两点重要信息一是贡献者新增代码应避免引入编译器警告--werror下任何警告都会让构建失败二是如果你改动了协议或通道逻辑CI 会以 ASan 模式运行全量单测内存问题泄漏、越界会在 CI 阶段暴露因此本地最好先用 ASan 构建跑一遍相关测试。四、让 PR 更顺畅的配套约定除了 CONTRIBUTING.md 正文的硬性要求仓库还提供了几项配套设施建议贡献者一并遵循1. 使用 PR 模板填写描述.github/pull_request_template.md 要求 PR 描述回答以下问题What problem does this PR solve?解决什么问题填写关联的 Issue Number模板中预留了resolve字段用于自动关联关闭 issue、问题摘要What is changed and the side effects?改了什么、副作用是什么明确列出 Changed并评估 Performance effects性能影响与 Breaking backward compatibility是否破坏向后兼容——这两项对 RPC 框架尤为重要Check List确认改动可编译提供新功能时最好补充相关测试遵循 CODE_OF_CONDUCT.md 中的行为准则。2. 提前在本地验证结合第二节内容提交 PR 前建议在本地完成以下自检清单git diff检查代码风格是否符合 Google C Style、缩进是否为 4 空格确认改动落位正确协议类改动进 src/brpc/policy通用改动不藏在具体协议中新增或修改对应的*_unittest.cpp并在 test/CMakeLists.txt / test/BUILD.bazel 中正确登记测试目标本地用 gcc 与 clang 各编译一次开启--werror再用 ASan 构建运行相关单测若改动涉及跨版本兼容如 protobuf 版本参考 CI 的版本矩阵在本地抽查。五、结语CONTRIBUTING.md 虽然篇幅精炼但浓缩了 bRPC 社区对贡献者的全部核心期望规范的代码Google C Style、4 空格缩进、恰当的落位协议进 policy、通用进通用层、完备的测试每个 PR 必须有单测、以及必须通过的 CI。对照仓库中的实际实现src/brpc/policy 的协议组织、test 目录的测试体系、.github/workflows/ci-linux.yml 的 CI 矩阵可以清晰看到这些要求并非空泛口号而是贯穿代码库的真实工程实践。遵循这套规范提交 PR既能提高通过评审的概率也是在为这个服务于搜索、存储、机器学习、广告、推荐等高性能场景的工业级 RPC 框架持续注入高质量代码。【免费下载链接】brpcbrpc is an Industrial-grade RPC framework using C Language, which is often used in high performance system such as Search, Storage, Machine learning, Advertisement, Recommendation etc. brpc means better RPC.项目地址: https://gitcode.com/GitHub_Trending/brpc/brpc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Apache bRPC 贡献指南：从 Issue 到 PR 的完整参与路径与代码规范
Apache bRPC 贡献指南从 Issue 到 PR 的完整参与路径与代码规范【免费下载链接】brpcbrpc is an Industrial-grade RPC framework using C Language, which is often used in high performance system such as Search, Storage, Machine learning, Advertisement, Recommendation etc. brpc means better RPC.项目地址: https://gitcode.com/GitHub_Trending/brpc/brpcbRPC 是一个用 C 编写的工业级 RPC 框架常用于搜索、存储、机器学习、广告、推荐等高性能系统。本文基于仓库根目录的 CONTRIBUTING.md 展开系统梳理向 bRPC 提交贡献的完整流程如何报告问题、提出新功能需求、编写并提交 PR以及 PR 前后必须满足的代码风格、代码组织与单元测试要求。读完本文你将掌握 bRPC 社区认可的开发规范、测试组织方式与 CI 检查机制能够高质量地参与这个开源项目的共建。一、贡献流程总览两条主要路径根据 CONTRIBUTING.md 的说明向 bRPC 贡献有两种典型路径报告问题或请求新功能遇到任何问题bug、使用障碍、文档疑问等或者需要新功能欢迎创建 issue。仓库提供了标准化的 issue 模板见 .github/ISSUE_TEMPLATE/bug_report.mdbug 报告模板和 .github/ISSUE_TEMPLATE/feature_request.md功能请求模板提交时选择合适的模板填写能让维护者更快定位与响应。解决已有 issue 并提交 PR如果你能解决 issue 列表中任何一个问题欢迎将代码以 Pull RequestPR的形式提交给社区评审。整个参与流程可以概括为发现问题 → 创建 issue → 认领/解决 issue → 本地编码与测试 → 提交 PR → 通过 CI 检查 → 合并。其中 PR 前后各有关键要求下面逐一展开。二、提交 PR 前的三项硬性要求CONTRIBUTING.md 明确列出了提交 PR 之前必须确认的三件事这是每个贡献者绕不开的关卡1. 代码风格必须符合 Google C Style规范基准代码风格需符合 Google C 编码规范Google C Style Guide这是 bRPC 全仓库代码的基础风格。缩进要求文档明确要求缩进最好为 4 个空格Indentation is preferred to be 4 spaces。在 bRPC 的源码中这一约定贯穿始终例如 src/brpc/policy/redis_protocol.cpp 等核心文件的函数体、嵌套代码块均使用 4 空格缩进。从仓库结构看src/brpc 下的所有核心模块channel、server、controller、socket 等都严格遵循该风格新增代码应当与既有代码保持视觉上的一致这能显著降低评审成本。2. 代码必须出现在它应该在的位置这是 bRPC 贡献规范中最具项目特色的要求原文强调特定协议的扩展代码不应放在通用类中例如为某个特定协议protocol新增的支持代码不应该塞进 src/brpc/server.cpp、src/brpc/channel.cpp 这类通用类中。非常通用的改动也不该深藏在某个特定协议内部如果一个改动影响面大、属于通用能力就不应把它隐藏在某个具体协议的 cpp 文件里。这一原则在仓库的物理布局中有清晰印证bRPC 将所有协议的实现集中放在 src/brpc/policy 目录下每种协议一个独立文件。例如Redis 协议src/brpc/policy/redis_protocol.cppHTTP 协议src/brpc/policy/http_rpc_protocol.cppThrift 协议src/brpc/policy/thrift_protocol.cppgRPC/H2 协议src/brpc/policy/http2_rpc_protocol.cpp负载均衡策略src/brpc/policy/round_robin_load_balancer.cpp 等而真正通用的能力如 src/brpc/server.h、src/brpc/channel.h则保留在通用层。从源码结构可以推断这是 bRPC 长期演进形成的一种约定新增协议时遵循协议代码进 policy 目录、扩展点用注册/适配机制接入的模式避免通用类无限膨胀也方便按协议独立测试与维护。如果你要扩展某个协议先在 src/brpc/policy 中找到对应实现参考其写法如果你要做通用改动优先考虑是否会影响所有协议使用者并评估是否需要补充通用层的测试。3. 必须包含单元测试文档要求每个 PR必须有对应的单测代码Has unittests。这一点在仓库中有大量实证全部测试位于 test 目录每个核心模块都有对应的*_unittest.cpp文件例如服务器核心test/brpc_server_unittest.cpp通道核心test/brpc_channel_unittest.cppRedis 协议test/brpc_redis_unittest.cpp负载均衡test/brpc_load_balancer_unittest.cpp测试基于 GoogleTestgtest框架编写测试构建配置见 test/CMakeLists.txt使用 Bazel 构建时测试目标定义在 test/BUILD.bazel 中。测试运行脚本 test/run_tests.sh 会批量执行test_butil、test_bvar、bthread*unittest、brpc*unittest等测试二进制并开启 ASandetect_leaks1:detect_stack_use_after_return1、开启 coredump 以便失败时用 gdb 抓取调用栈。从该脚本可以看出bRPC 对内存安全和崩溃现场还原非常重视贡献者的单测也应当尽可能覆盖边界条件与内存路径。以 test/brpc_redis_unittest.cpp 为例它是单测应该如何写的样板该测试会在本机 fork 一个真实的redis-server监听 6479 端口作为被测对象再通过 brpc 的 Redis 客户端发起请求并断言结果覆盖了协议编解码、命令路由、认证等多个层面。可以推断为协议类改动编写单测时参考这类拉起真实服务 端到端断言的集成测试模式是最贴合 bRPC 现状的做法。三、提交 PR 后的检查GitHub Actions CICONTRIBUTING.md 要求提交 PR 之后必须确保 GitHub Actions 流水线通过Make sure the GitHub Actions passed。CI 配置集中在 .github/workflows 目录其中核心的是 .github/workflows/ci-linux.yml 与 .github/workflows/ci-macos.yml。以 Linux 流水线为例从源码结构看它覆盖了非常完整的验证矩阵任何 PR 都要经过这些检查检查维度具体内容说明构建系统make / cmake / bazel 三套保证三种主流构建方式都可用编译器gcc / clang双编译器矩阵发现平台相关隐患编译选项--werror警告即错误、--with-thrift、--with-glog、--with-rdma、--with-asan、--with-debug-lock、--with-bthread-tracer等全功能开关下的编译验证详见 .github/workflows/ci-linux.yml 中的 matrix 定义单元测试bazel test --configrdma --configubring //test/...以及 make 下的cd test make sh ./run_tests.sh全量单测必须在 CI 中通过Protobuf 兼容分别编译 protobuf 3.5.1 / 3.12.4 / 21.12 等版本保证对多个 protobuf 版本向后兼容从 CI 配置可以推断两点重要信息一是贡献者新增代码应避免引入编译器警告--werror下任何警告都会让构建失败二是如果你改动了协议或通道逻辑CI 会以 ASan 模式运行全量单测内存问题泄漏、越界会在 CI 阶段暴露因此本地最好先用 ASan 构建跑一遍相关测试。四、让 PR 更顺畅的配套约定除了 CONTRIBUTING.md 正文的硬性要求仓库还提供了几项配套设施建议贡献者一并遵循1. 使用 PR 模板填写描述.github/pull_request_template.md 要求 PR 描述回答以下问题What problem does this PR solve?解决什么问题填写关联的 Issue Number模板中预留了resolve字段用于自动关联关闭 issue、问题摘要What is changed and the side effects?改了什么、副作用是什么明确列出 Changed并评估 Performance effects性能影响与 Breaking backward compatibility是否破坏向后兼容——这两项对 RPC 框架尤为重要Check List确认改动可编译提供新功能时最好补充相关测试遵循 CODE_OF_CONDUCT.md 中的行为准则。2. 提前在本地验证结合第二节内容提交 PR 前建议在本地完成以下自检清单git diff检查代码风格是否符合 Google C Style、缩进是否为 4 空格确认改动落位正确协议类改动进 src/brpc/policy通用改动不藏在具体协议中新增或修改对应的*_unittest.cpp并在 test/CMakeLists.txt / test/BUILD.bazel 中正确登记测试目标本地用 gcc 与 clang 各编译一次开启--werror再用 ASan 构建运行相关单测若改动涉及跨版本兼容如 protobuf 版本参考 CI 的版本矩阵在本地抽查。五、结语CONTRIBUTING.md 虽然篇幅精炼但浓缩了 bRPC 社区对贡献者的全部核心期望规范的代码Google C Style、4 空格缩进、恰当的落位协议进 policy、通用进通用层、完备的测试每个 PR 必须有单测、以及必须通过的 CI。对照仓库中的实际实现src/brpc/policy 的协议组织、test 目录的测试体系、.github/workflows/ci-linux.yml 的 CI 矩阵可以清晰看到这些要求并非空泛口号而是贯穿代码库的真实工程实践。遵循这套规范提交 PR既能提高通过评审的概率也是在为这个服务于搜索、存储、机器学习、广告、推荐等高性能场景的工业级 RPC 框架持续注入高质量代码。【免费下载链接】brpcbrpc is an Industrial-grade RPC framework using C Language, which is often used in high performance system such as Search, Storage, Machine learning, Advertisement, Recommendation etc. brpc means better RPC.项目地址: https://gitcode.com/GitHub_Trending/brpc/brpc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考