适合人群有基础 Git 操作经验、想参与开源但不知如何下手的开发者⏱️阅读时长约 8 分钟️动手成本30 分钟即可完成第一次 PR 本文提供可直接套用的PR 描述模板标准工作流命令 一、提交前的 3 步准备决定 PR 质量的关键1️⃣ 找对项目新手友好型开源库特征特征推荐渠道避坑提示带有good-first-issue/help-wanted标签GitHub Explore / Gitee 探索避免选archived或 2 年未更新的项目有完善的CONTRIBUTING.md项目根目录无此文件说明社区规范弱PR 易被拒CI/CD 状态清晰Actions/Travis仓库 Actions 页全红 CI 说明维护成本高新手慎入2️⃣ 本地环境准备# 1. Fork 目标仓库到你的账号 # 2. Clone 到本地替换你的用户名和项目名 git clone gitgithub.com:YOUR_USERNAME/PROJECT_NAME.git cd PROJECT_NAME # 3. 添加上游源便于同步官方最新代码 git remote add upstream gitgithub.com:ORIGINAL_OWNER/PROJECT_NAME.git git fetch upstream3️⃣ 必读文档清单README.md→ 了解项目定位与安装方式CONTRIBUTING.md→ 代码规范、Commit 格式、PR 模板package.json/go.mod/requirements.txt→ 依赖版本与运行命令现有PR列表 → 观察 Maintainer 的 Review 风格️ 二、标准 PR 提交流程附完整命令Step 1创建独立分支永远不要直接在 main 开发# 同步最新官方代码 git checkout main git pull upstream main # 创建特性分支命名规范type/description git switch -c fix/typo-in-docs # 或 git checkout -b fix/typo-in-docsStep 2本地开发与测试# 安装依赖以 Node 为例 npm install # 或 yarn / pnpm # 运行项目 验证修改 npm run dev # 或对应启动命令 npm run test # 确保测试通过Step 3规范提交Conventional Commitsgit add . # ✅ 正确示例 git commit -m docs: fix typo in README.md git commit -m fix(parser): handle null input gracefully # ❌ 错误示例会被 Maintainer 要求重写 git commit -m update code git commit -m fix bugCommit 类型速查表类型含义示例feat新功能feat(auth): add JWT refresh logicfix修复 Bugfix(ui): align buttons on mobiledocs文档更新docs: add setup guide for Windowsstyle代码格式style: run prettier on src/refactor重构refactor(utils): simplify date parserStep 4推送并创建 PRgit push origin fix/typo-in-docs # 使用 GitHub CLI 一键创建推荐 gh pr create \ --title fix: resolve typo in installation guide \ --body-file ./PR_TEMPLATE.md \ --base main \ --head YOUR_USERNAME:fix/typo-in-docs若无gh命令直接在 GitHub/Gitee 网页端点击Compare pull request即可。 三、高质量 PR 描述模板直接复制使用在 PR 描述框中粘贴以下 Markdown 内容替换{{}}占位符## 变更类型 - [x] Bug 修复 - [ ] ✨ 新功能 - [ ] 文档更新 - [ ] 代码优化/重构 ## 问题描述 修复了 {{简短描述问题如Windows 环境下路径分隔符导致模块加载失败}}。 原代码在 {{操作系统/浏览器/版本}} 下会触发 {{错误现象}}影响 {{功能模块}} 正常使用。 ## ️ 解决方案 1. 将 path.join() 替换为 path.posix.join() 确保跨平台兼容 2. 新增 2 个边界测试用例覆盖空路径场景 3. 更新 README.md 安装指引补充环境变量说明 ## 关联 Issue Fixes #{{Issue 编号}} !-- 若未创建 Issue可写Closes #{{编号}} 或 说明已同步在 Issue 中讨论 -- ## ✅ 自查清单 - [x] 遵循项目 CONTRIBUTING.md 规范 - [x] 本地 npm run test / npm run lint 全部通过 - [x] 未破坏现有公共 API如有破坏已标注 Breaking Change - [x] 代码已格式化Prettier / ESLint / gofmt 等 ## ️ 效果对比可选 | 修改前 | 修改后 | |--------|--------| | !-- 截图/GIF 链接 -- | !-- 截图/GIF 链接 -- | ## 备注 - 该方案参考了 {{相关 Issue/PR/外部文档}} 的讨论 - 如需调整实现方式可随时在评论区沟通我将配合修改 四、新手常踩的 5 个坑附避坑指南坑点后果正确做法直接在main分支提交分支污染无法同步官方更新PR 被拒始终基于main创建独立分支一次性提交 500 行代码Review 成本极高易被要求拆分原子化 PR一个 PR 只做一件事忽略 CI/CD 失败红叉Maintainer 不会 Review 未通过 CI 的 PR本地跑通测试再 Push查看 Logs 定位失败原因提交后不回复评论PR 被标记stale最终关闭24-48 小时内回复 Review 意见用maintainer礼貌询问未关联 Issue变更动机不明合并优先级低PR 描述首行写Fixes #123或Closes #123 五、维护者视角什么样的 PR 会被秒合并小而精改动50行逻辑清晰附带测试守规范Commit 语义化、代码格式化、遵循项目结构带文档更新了相关注释/示例/README降低后续维护成本态度好Review 意见逐一回复不争论技术路线接受合理建议能复用代码可测试、可回滚、不引入强依赖️ Maintainer 原话“我宁愿合并 10 个 20 行的小 PR也不愿花 3 天 Review 一个 500 行的巨型提交。开源协作的本质是降低沟通成本。” 附录提效工具链推荐场景工具安装/使用自动规范 Commit 信息commitizencz-clinpm i -g commitizen→git cz本地 CI 预检act(GitHub Actions 本地运行)brew install act→act pushPR 模板自动生成GitHub 仓库根目录.github/PULL_REQUEST_TEMPLATE.md仓库已有则自动加载到 PR 描述框同步上游代码git pull upstream main git push origin main定期执行避免 PR 冲突 结语你的第一次 PR不必完美但必须完整开源不是“代码高手”的专属游戏而是持续贡献、持续学习的社区实践。从改一个错别字、补一行注释开始跑通Fork → Branch → Commit → PR → Merge的完整闭环你就已经踏入了开源世界的大门。互动时间你最近一次给哪个开源项目提了 PR遇到卡点是什么评论区留下你的PR 链接点赞最高的 3 位我将免费帮你做一次Maintainer 视角的 PR 诊断