本教程以一个真实的 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 完成后将你自己的仓库克隆到本地gitclone https://github.com/你的用户名/FISCO-BCOS.gitcdFISCO-BCOS添加上游仓库即 FISCO BCOS 官方仓库作为 remote方便后续同步最新代码gitremoteaddupstream https://github.com/FISCO-BCOS/FISCO-BCOS.git验证 remote 配置gitremote-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()函数明确描述了程序的用法voidusage(){printf(Usage: tx_sign_perf isSM txCount\n);// ...}程序需要2 个参数isSM是否使用国密和txCount交易数量。4.2 定位 Bug查看main函数的参数校验intmain(intargc,char**argv){if(argc2)// ← 只检查了 argv[1] 是否存在{usage();}boolsmCrypto(std::string(argv[1])true);uint32_ttxCountstd::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 3if(argc3)// ← argv[0]程序名, argv[1]isSM, argv[2]txCount至少需要 3 个{usage();}五、创建特性分支并修复5.1 创建分支不要直接在 master 上修改创建一个有意义的分支名gitcheckout-bfix/tx-sign-perf-argc-check分支命名建议fix/前缀 → 修复 Bugfeat/前缀 → 新功能docs/前缀 → 文档改动5.2 进行修改编辑bcos-sdk/sample/tx/tx_sign_perf.cpp将第 137 行if(argc2)改为if(argc3)仅此一行改动最小化专注于修复目标问题。5.3 查看改动gitdiff预期输出- if (argc 2) if (argc 3)5.4 验证修复可选如果你有本地构建环境编译后可以这样测试# 传入 0 个参数 → 应打印 usage 并退出 ✅./tx_sign_perf# 传入 1 个参数 → 应打印 usage 并退出修复前会崩溃✅./tx_sign_perftrue# 传入 2 个参数 → 正常运行 ✅./tx_sign_perftrue30000六、提交代码6.1 暂存并提交gitaddbcos-sdk/sample/tx/tx_sign_perf.cppgitcommit-mfix: 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 推送到你的 Forkgitpush origin fix/tx-sign-perf-argc-check七、创建 Pull Request打开你 Fork 的仓库页面https://github.com/你的用户名/FISCO-BCOSGitHub 会自动检测到你推送了新分支页面顶部会出现一个“Compare pull request”按钮点击它这里已经提交PR了填写 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的masterhead 分支指向你的fix/tx-sign-perf-argc-check点击“Create pull request”八、提交后的注意事项事项说明签署 CLA首次提交 PR 可能需要签署贡献者许可协议Contributor License Agreement按照机器人提示操作即可响应 Code Review维护者可能会提出修改意见及时在 PR 中回复并更新代码保持分支同步如果上游有更新用以下命令同步并 rebasegit fetch upstreamgit rebase upstream/mastergit 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 → 合并 十、常见问题Q1Fork 后主仓库更新了怎么办gitfetch upstreamgitcheckout mastergitmerge upstream/mastergitpush origin masterQ2PR 被要求修改怎么办直接在本地修改然后gitadd.gitcommit-mfix: address review commentsgitpush origin fix/tx-sign-perf-argc-check新的 commit 会自动出现在 PR 中。Q3如何让 commit 历史更干净如果不想增加新的 commit可以用--amendgitadd.gitcommit--amendgitpush origin fix/tx-sign-perf-argc-check--forceQ4PR 被拒绝了怎么办不要气馁维护者通常会说明原因根据反馈修改后重新提交即可。开源社区欢迎一切有意义的贡献。总结这次修复的核心改动只有一行但它解决了一个真实的内存安全问题。对于第一个 PR 来说改动小→ Review 周期短通过率高问题明确→ Reviewer 一眼就能看懂有价值→ 修复了可能导致段错误的 Bug有测试方法→ 可以构造用例验证修复效果希望这个实战示例能帮助你迈出为 FISCO BCOS 贡献代码的第一步