第一次开源贡献与PR提交流程

记录我的第一次开源贡献经历，特别感谢项目 Code Owner 的耐心指导。我将从项目选择、Issue 筛选、修复策略、PR 提交与跟进四个方面，记录这次贡献过程，最后附上总结的完整 PR 提交流程。

PR过程的思考

1、选择的项目

选择开源项目时，建议优先考虑自己日常使用的工具、框架，或领域内知名度较高、维护相对活跃的项目。这样不仅上手更快，也更容易发现真实且有价值的问题。

额外建议：

• 查看项目 Star 数、最近提交频率、Issue 响应速度、是否有活跃的 Contributor。
• 优先选择社区氛围友好、有 good first issue 标签较多的项目。

这次我选择了 Terragrunt，它是 Gruntwork 团队维护的 Terraform / OpenTofu 辅助工具，主要用于大规模、多环境下的基础设施配置管理、模块复用、依赖处理、配置文件生成以及远程状态管理等。它在 GitHub 上拥有 9.6k+ Stars，是一个质量很高、维护活跃的项目。

• 项目：gruntwork-io/terragrunt
• 仓库链接：https://github.com/gruntwork-io/terragrunt

2. 如何筛选 Issue

在项目开发过程中发现 Bug 或可优化点时，可以自己提交 Issue 并尝试修复。也可以从已有的 Open Issue 中挑选。

推荐优先筛选带有 good first issue 或 help wanted 标签的 Issue，这类问题通常难度适中，且维护者更愿意帮助新人。

筛选技巧：

• 阅读 Issue 的历史评论，确认目前还没有人认领或正在处理。
• 优先选择描述清晰、有复现步骤、可验证的 Issue。
• 评估问题范围：最好是小而明确的问题，避免跨多个模块的大改动。

本次 PR 我选择了已有的 Open Issue，筛选时主要考虑以下几点：

• Issue 是否真实存在且有实际用户价值
• 问题范围是否清晰适中
• 是否容易验证修复效果

3、修复策略

选定 Issue 后，将项目 Fork 到本地进行修改。对于 Bugfix 类型的 PR，建议在修复过程中思考并能够回答以下问题：

• 原来为什么会出现这个问题？
• 现在为什么是正确的？
• 测试覆盖了哪条失败路径？
• 是否会影响已有的正常行为？
• 是否需要更新文档或 Changelog？

核心原则：保持改动最小化，只解决当前问题，不做无关的重构或大范围改动。

4、PR的提交与后续跟进

提交 PR 后，通常会有机器人自动检查（Lint、Test、DCO 等）和 Code Owner 进行 Review。此时需要积极、耐心跟进：

• 认真阅读每一条评论，判断是否合理。
• 只修改真正有必要的地方，保持改动最小。
• 每次修改后重新 push，并确认 CI 全部通过。
• 对于不理解的点，可以礼貌地提问，与维护者共同讨论。

小建议：

• PR 描述要写清楚：做了什么改动、为什么这么改、如何验证。
• 回复 Review 评论时，态度谦虚、表达清晰，可以使用 “Done.”、“Addressed.” 等简洁回复。
• 这是一个很好的学习机会，能直接和项目核心贡献者交流代码设计思路。

完整的PR流程

1. 先选一个小而真实的问题

作为第一次贡献，新手最好挑边界清晰、容易验证的问题下手。比如：

• 小 Bug 修复
• 补缺失的测试
• CLI 参数组合问题
• 文档和实际行为不一致的地方

千万别 一上来就挑大重构、核心架构修改或者特别复杂的功能。目标是让 Reviewer 能快速看懂：这个问题确实存在，你的修复是合理的，而且有测试覆盖。

2. 阅读项目贡献指南

在动手前一定要先看这些文件：

• CONTRIBUTING.md
• README.md
• .github/PULL_REQUEST_TEMPLATE.md（如果有）
• 其他贡献相关文档

重点关注：

• PR 标题格式要求
• 是否需要关联 Issue
• 是否要求 DCO（Signed-off-by）
• 测试和 Lint 如何运行
• 有没有明确禁止低价值 PR 的规则

按规矩来，能少走很多弯路。

3. Fork 仓库

在 GitHub 项目页面点击右上角的 Fork。

Fork 后本地会有两个远程仓库：

• upstream：原项目（gruntwork-io/terragrunt）
• origin：你自己的 Fork

4. Clone 到本地

1
2
3
4
5
6

git clone https://github.com/你的用户名/terragrunt.git
cd terragrunt

# 添加 upstream
git remote add upstream https://github.com/gruntwork-io/terragrunt.git
git remote -v

5. 同步最新主分支

1
2
3

git fetch upstream
git switch main
git pull upstream main

如果项目主分支叫 master，把 main 换成 master。

6. 创建工作分支

分支名写清楚目的,例如：

1

git switch - c fix/benchmark- result- filename

分支命名建议带前缀：fix/、feat/、docs/、test/ 等，清晰描述目的。

7. 复现问题

先别急着改代码，一定要先确认问题真实存在。可以用最小复现命令、运行相关测试、查看日志等方式验证。

8. 写失败测试

bugfix PR 最好先写 regression test。

流程：

写测试 → 看它失败 → 修代码 → 看它通过

测试要覆盖用户行为或关键边界，不要只测实现细节。

9. 做最小代码改动

改动原则：

• 只解决当前这个问题
• 不要顺手重构
• 不要大范围格式化
• 不要引入自己也解释不清的新东西
• 如果用户可见行为变了，就记得更新文档

改完后问自己：原来为什么错？现在为什么对？会不会影响其他功能？

10. 本地验证

按项目要求跑测试。常见命令：

Python 项目：

1
2
3

pytest tests/ -q
ruff check .
ruff format --check .

Node/Go/Rust项目换成对应命令：

1

npm test npm run lint

1

go test ./... gofmt - w path/to/file.go

1

cargo test  cargo fmt --check  cargo clippy

没跑的测试不要写进PRbody。

11.自查diff

提交前一定要执行：

1
2

git status --short 
git diff

重点检查：- 有没有无关文件。- 有没有临时文件、缓存、日志。- 有没有 debug print。- 有没有本地路径、token、密钥。- 有没有无意义格式化。- 新测试是否真的覆盖问题。

12.Commit

普通提交：

1
2

git add 文件路径
git commit -m "fix: 简短清晰的描述"

项目要求DCO时加- s：

1

git commit - s - m "fix: handle dataset stats plot filename"

项目要求标题前缀时：

1

git commit - s - m "[Bugfix] [Benchmark] Fix dataset stats plot filename"

若项目要求GPG签名，可以参考：
https://docs.github.com/zh/authentication/managing-commit-signature-verification/signing-commits

13.Push到自己的fork

1

git push -u origin fix/你的分支名

GitHub会给出创建PR的链接。

14.创建PullRequest

PR 描述要写清楚三件事：

• 改了什么
• 为什么改
• 如何验证

标题和描述尽量遵循项目规范。

15.等CI和review

PR创建后看Checks。

CI失败时按这个顺序处理：

读日志 → 定位失败点 → 本地复现 → 修复 → push新commit

不要猜原因，也不要一次改很多地方。

收到 Reviewer 意见后，能改的尽快改，不懂的就礼貌提问。改完后回复 “Done” 或 “Addressed” 并说明修改点。

16.更新PR

修改后正常 push 即可，PR 会自动更新。

如果reviewer要求squash：

1
2
3

git fetch upstream
git rebase -i upstream/main
git push --force-with-lease

注意：用 –force-with-lease，不要用裸 –force。

同步主分支：

1
2

git fetch upstream git switch main 
git pull upstream main

最后清理分支：

1
2

git branch -d fix/你的分支名
git push origin --delete fix/你的分支名