💡 适合人群：有基础 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 git@github.com:YOUR_USERNAME/PROJECT_NAME.git
cd PROJECT_NAME

# 3. 添加上游源（便于同步官方最新代码）
git remote add upstream git@github.com:ORIGINAL_OWNER/PROJECT_NAME.git
git fetch upstream

3️⃣ 必读文档清单

• 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-docs

Step 2：本地开发与测试

# 安装依赖（以 Node 为例）
npm install  # 或 yarn / pnpm

# 运行项目 & 验证修改
npm run dev  # 或对应启动命令
npm run test # 确保测试通过

Step 3：规范提交（Conventional Commits）

git 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 bug"

📌 Commit 类型速查表：

类型	含义	示例
feat	新功能	feat(auth): add JWT refresh logic
fix	修复 Bug	fix(ui): align buttons on mobile
docs	文档更新	docs: add setup guide for Windows
style	代码格式	style: run prettier on src/
refactor	重构	refactor(utils): simplify date parser

Step 4：推送并创建 PR

git 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 会被秒合并？

1. 小而精：改动 <50 行，逻辑清晰，附带测试
2. 守规范：Commit 语义化、代码格式化、遵循项目结构
3. 带文档：更新了相关注释/示例/README，降低后续维护成本
4. 态度好：Review 意见逐一回复，不争论技术路线，接受合理建议
5. 能复用：代码可测试、可回滚、不引入强依赖

🗣️ Maintainer 原话：“我宁愿合并 10 个 20 行的小 PR，也不愿花 3 天 Review 一个 500 行的巨型提交。开源协作的本质是降低沟通成本。”

---

🎁 附录：提效工具链推荐

场景	工具	安装/使用
自动规范 Commit 信息	commitizen + cz-cli	npm i -g commitizen → git cz
本地 CI 预检	act (GitHub Actions 本地运行)	brew install act → act push
PR 模板自动生成	GitHub 仓库根目录 .github/PULL_REQUEST_TEMPLATE.md	仓库已有则自动加载到 PR 描述框
同步上游代码	git pull upstream main && git push origin main	定期执行，避免 PR 冲突

---

🎯 结语：你的第一次 PR，不必完美，但必须完整

开源不是“代码高手”的专属游戏，而是持续贡献、持续学习的社区实践。从改一个错别字、补一行注释开始，跑通 Fork → Branch → Commit → PR → Merge 的完整闭环，你就已经踏入了开源世界的大门。

👇 互动时间

1. 你最近一次给哪个开源项目提了 PR？遇到卡点是什么？
2. 评论区留下你的 PR 链接，点赞最高的 3 位，我将免费帮你做一次 Maintainer 视角的 PR 诊断！