如何完成 FISCO BCOS 的第一个 PR —— 实战教程

原创已于 2026-05-22 10:58:36 修改 · 563 阅读

11 ·

本内容遵循CC 4.0 BY-SA版权协议

标签

#区块链

于 2026-05-21 22:28:43 首次发布

区块链专栏收录该内容

4 篇文章

订阅专栏

本教程以一个真实的 Bug 修复为例，带你走完 Fork → Clone → 修复 → 提交 PR 的完整流程。
适合第一次参与开源项目的新手。

一、前言：什么样的改动适合作为第一个 PR？

对于开源项目的第一次贡献，最佳切入点是小型但有意义的改动，例如：

命令行参数校验缺失或错误
文档拼写错误
变量命名不当
缺少边界检查

我们这次修复的就是一个经典的命令行参数个数判断错误问题。

二、Fork 仓库（第一步）

由于我们没有 FISCO BCOS 主仓库的直接写入权限，第一步需要先 Fork。

打开 FISCO BCOS 的 GitHub 仓库：https://github.com/FISCO-BCOS/FISCO-BCOS
点击页面右上角的 Fork 按钮
在弹出的页面中选择你的 GitHub 账号作为 Fork 目标
等待 Fork 完成，完成后你会拥有一个 https://github.com/<你的用户名>/FISCO-BCOS 仓库

Fork 是什么？ 简单说就是在你自己的 GitHub 账号下创建一份仓库的副本，你可以随意修改，不会影响原仓库。

三、Clone 到本地

Fork 完成后，将你自己的仓库克隆到本地：

git clone https://github.com/<你的用户名>/FISCO-BCOS.git
cd FISCO-BCOS

添加上游仓库（即 FISCO BCOS 官方仓库）作为 remote，方便后续同步最新代码：

git remote add upstream https://github.com/FISCO-BCOS/FISCO-BCOS.git

验证 remote 配置：

git remote -v

预期输出：

origin    https://github.com/<你的用户名>/FISCO-BCOS.git (fetch)
origin    https://github.com/<你的用户名>/FISCO-BCOS.git (push)
upstream  https://github.com/FISCO-BCOS/FISCO-BCOS.git (fetch)
upstream  https://github.com/FISCO-BCOS/FISCO-BCOS.git (push)

origin 指向你自己的 Fork 仓库（你有写入权限）
upstream 指向官方仓库（你只有读取权限）

四、发现问题

4.1 阅读源码

在 bcos-sdk/sample/tx/tx_sign_perf.cpp 中，usage() 函数明确描述了程序的用法：

void usage()
{
    printf("Usage: tx_sign_perf isSM txCount\n");
    // ...
}

程序需要 2 个参数：isSM（是否使用国密）和 txCount（交易数量）。

4.2 定位 Bug

查看 main 函数的参数校验：

int main(int argc, char** argv)
{
    if (argc < 2)        // ← 只检查了 argv[1] 是否存在
    {
        usage();
    }

    bool smCrypto = (std::string(argv[1]) == "true");
    uint32_t txCount = std::stoul(argv[2]);  // ← 但这里访问了 argv[2]！
    // ...
}

问题：

参数位置	内容	`argc < 2` 是否保证安全
`argv[0]`	程序名	✅ 始终存在
`argv[1]`	isSM	✅ `argc >= 2` 时存在
`argv[2]`	txCount	❌ `argc >= 2` 不保证存在！需要 `argc >= 3`

当用户只传入一个参数（如 ./tx_sign_perf true）时，argc == 2，通过了检查，但访问 argv[2] 是越界的，会导致未定义行为或段错误。

4.3 修复方案

将参数校验改为 argc < 3：

if (argc < 3)    // ← argv[0]=程序名, argv[1]=isSM, argv[2]=txCount，至少需要 3 个
{
    usage();
}

五、创建特性分支并修复

5.1 创建分支

不要直接在 master 上修改，创建一个有意义的分支名：

git checkout -b fix/tx-sign-perf-argc-check

分支命名建议：

fix/ 前缀 → 修复 Bug
feat/ 前缀 → 新功能
docs/ 前缀 → 文档改动

5.2 进行修改

编辑 bcos-sdk/sample/tx/tx_sign_perf.cpp，将第 137 行：

if (argc < 2)

改为：

if (argc < 3)

仅此一行，改动最小化，专注于修复目标问题。

5.3 查看改动

git diff

预期输出：

-     if (argc < 2)
+     if (argc < 3)

5.4 验证修复（可选）

如果你有本地构建环境，编译后可以这样测试：

# 传入 0 个参数 → 应打印 usage 并退出 ✅
./tx_sign_perf

# 传入 1 个参数 → 应打印 usage 并退出（修复前会崩溃！）✅
./tx_sign_perf true

# 传入 2 个参数 → 正常运行 ✅
./tx_sign_perf true 30000

六、提交代码

6.1 暂存并提交

git add bcos-sdk/sample/tx/tx_sign_perf.cpp
git commit -m "fix: correct argc check in tx_sign_perf to prevent argv[2] out-of-bounds access

The program requires 2 arguments (isSM and txCount) but only checked
argc < 2, which allows argv[2] to be accessed out-of-bounds when only
one argument is provided. Changed to argc < 3."

Commit Message 规范：

第一行以类型前缀开头：fix:、feat:、docs:、refactor: 等
第一行简短总结（50 字符以内）
空一行后写详细说明（解释为什么改，而不是改了什么）

6.2 推送到你的 Fork

git push origin fix/tx-sign-perf-argc-check

七、创建 Pull Request

打开你 Fork 的仓库页面 https://github.com/<你的用户名>/FISCO-BCOS
GitHub 会自动检测到你推送了新分支，页面顶部会出现一个 “Compare & pull request” 按钮，点击它

填写 PR 信息：

Title（标题）：

fix(sample, gitignore): 修正tx签名性能示例参数检查

Description（描述）：

## 问题
`tx_sign_perf.cpp` 的 `main` 函数中，命令行参数个数检查为 `argc < 2`，
但程序实际访问了 `argv[1]` 和 `argv[2]`，需要至少 3 个参数。
当用户只传入 1 个参数时，访问 `argv[2]` 会导致未定义行为或段错误。

## 修复
将 `argc < 2` 改为 `argc < 3`。

## 影响范围
仅影响 `bcos-sdk/sample/tx/tx_sign_perf.cpp`。

## 测试
- `./tx_sign_perf` → 打印 usage 并退出 ✅
- `./tx_sign_perf true` → 打印 usage 并退出 ✅（修复前会崩溃）
- `./tx_sign_perf true 30000` → 正常运行 ✅

确认 base 分支指向 FISCO-BCOS/FISCO-BCOS 的 master，head 分支指向你的 fix/tx-sign-perf-argc-check
点击 “Create pull request”

八、提交后的注意事项

事项	说明
签署 CLA	首次提交 PR 可能需要签署贡献者许可协议（Contributor License Agreement），按照机器人提示操作即可
响应 Code Review	维护者可能会提出修改意见，及时在 PR 中回复并更新代码
保持分支同步	如果上游有更新，用以下命令同步并 rebase：
	`git fetch upstream`
	`git rebase upstream/master`
	`git push origin fix/tx-sign-perf-argc-check --force`
一个 PR 只做一件事	不要混合多个不相关的修改，方便 Review

九、完整流程回顾

GitHub Fork
    │
    ▼
git clone（你的 Fork）
    │
    ▼
git remote add upstream（添加上游）
    │
    ▼
git checkout -b fix/xxx（创建分支）
    │
    ▼
编辑代码 → 测试
    │
    ▼
git add → git commit（提交）
    │
    ▼
git push origin fix/xxx（推送到你的 Fork）
    │
    ▼
GitHub 上创建 Pull Request → 等待 Review → 合并 🎉

十、常见问题

Q1：Fork 后主仓库更新了怎么办？

git fetch upstream
git checkout master
git merge upstream/master
git push origin master

Q2：PR 被要求修改怎么办？

直接在本地修改，然后：

git add .
git commit -m "fix: address review comments"
git push origin fix/tx-sign-perf-argc-check

新的 commit 会自动出现在 PR 中。

Q3：如何让 commit 历史更干净？

如果不想增加新的 commit，可以用 --amend：

git add .
git commit --amend
git push origin fix/tx-sign-perf-argc-check --force

Q4：PR 被拒绝了怎么办？

不要气馁！维护者通常会说明原因，根据反馈修改后重新提交即可。开源社区欢迎一切有意义的贡献。

总结

这次修复的核心改动只有一行，但它解决了一个真实的内存安全问题。对于第一个 PR 来说：

改动小 → Review 周期短，通过率高
问题明确 → Reviewer 一眼就能看懂
有价值 → 修复了可能导致段错误的 Bug
有测试方法 → 可以构造用例验证修复效果

希望这个实战示例能帮助你迈出为 FISCO BCOS 贡献代码的第一步！🚀