企业官网建设流程全解析

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/brpc

bRPC 是一个用 C++ 编写的工业级 RPC 框架，常用于搜索、存储、机器学习、广告、推荐等高性能系统。本文基于仓库根目录的 CONTRIBUTING.md 展开，系统梳理向 bRPC 提交贡献的完整流程：如何报告问题、提出新功能需求、编写并提交 PR，以及 PR 前后必须满足的代码风格、代码组织与单元测试要求。读完本文，你将掌握 bRPC 社区认可的开发规范、测试组织方式与 CI 检查机制，能够高质量地参与这个开源项目的共建。

一、贡献流程总览：两条主要路径

根据 CONTRIBUTING.md 的说明，向 bRPC 贡献有两种典型路径：

1. 报告问题或请求新功能：遇到任何问题（bug、使用障碍、文档疑问等），或者需要新功能，欢迎创建 issue。仓库提供了标准化的 issue 模板，见 .github/ISSUE_TEMPLATE/bug_report.md（bug 报告模板）和 .github/ISSUE_TEMPLATE/feature_request.md（功能请求模板），提交时选择合适的模板填写，能让维护者更快定位与响应。
2. 解决已有 issue 并提交 PR：如果你能解决 issue 列表中任何一个问题，欢迎将代码以 Pull Request（PR）的形式提交给社区评审。

整个参与流程可以概括为：发现问题 → 创建 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.cpp
• HTTP 协议：src/brpc/policy/http_rpc_protocol.cpp
• Thrift 协议：src/brpc/policy/thrift_protocol.cpp
• gRPC/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.cpp
  • Redis 协议：test/brpc_redis_unittest.cpp
  • 负载均衡：test/brpc_load_balancer_unittest.cpp
• 测试基于 GoogleTest（gtest）框架编写，测试构建配置见 test/CMakeLists.txt；使用 Bazel 构建时，测试目标定义在 test/BUILD.bazel 中。
• 测试运行脚本 test/run_tests.sh 会批量执行test_butil、test_bvar、bthread*unittest、brpc*unittest等测试二进制，并开启 ASan（detect_leaks=1:detect_stack_use_after_return=1）、开启 coredump 以便失败时用 gdb 抓取调用栈。从该脚本可以看出，bRPC 对内存安全和崩溃现场还原非常重视，贡献者的单测也应当尽可能覆盖边界条件与内存路径。

以 test/brpc_redis_unittest.cpp 为例，它是"单测应该如何写"的样板：该测试会在本机 fork 一个真实的redis-server（监听 6479 端口）作为被测对象，再通过 brpc 的 Redis 客户端发起请求并断言结果，覆盖了协议编解码、命令路由、认证等多个层面。可以推断，为协议类改动编写单测时，参考这类"拉起真实服务 + 端到端断言"的集成测试模式是最贴合 bRPC 现状的做法。

三、提交 PR 后的检查：GitHub Actions CI

CONTRIBUTING.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 都要经过这些检查：

从 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 前建议在本地完成以下自检清单：

1. git diff检查代码风格是否符合 Google C++ Style、缩进是否为 4 空格；
2. 确认改动落位正确：协议类改动进 src/brpc/policy，通用改动不藏在具体协议中；
3. 新增或修改对应的*_unittest.cpp，并在 test/CMakeLists.txt / test/BUILD.bazel 中正确登记测试目标；
4. 本地用 gcc 与 clang 各编译一次（开启--werror），再用 ASan 构建运行相关单测；
5. 若改动涉及跨版本兼容（如 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