如何开始开源贡献：从第一个 Issue 到成为核心维护者

你在项目中遇到的任何不爽 = 潜在的贡献机会

- 文档有歧义或过时？→ 文档 PR
- 错误提示不清晰？→ 改进错误信息
- 某个 API 不符合直觉？→ 讨论 + 改进
- README 缺少某个使用场景？→ 补充示例

# GitHub Explore：按语言和趋势筛选
open https://github.com/explore

# 搜索带有 good first issue 标签的 issue
github.com/issues?q=is%3Aopen+label%3A%22good+first+issue%22

# 搜索特定语言和标签
github.com/issues?q=is%3Aopen+label%3A%22good+first+issue%22+language%3Atypescript

# 使用 GitHub CLI 搜索
github search issues --label "good-first-issue" --language typescript --state open

项目健康度评估清单：

✅ 积极维护的信号：
  - 最近 1 个月内有过 commit
  - Issue 有维护者回复
  - 有 CONTRIBUTING.md 文件
  - 有清晰的贡献指南和代码规范
  - CI/CD 配置完整且通过
  - Pull Request 在 2 周内有回应（合并或反馈）

⚠️  需要警惕的信号：
  - 最后一次 commit 超过 6 个月
  - Issue 堆积且无人回复
  - 没有 CONTRIBUTING.md
  - PR 长期未处理
  - 维护者态度傲慢或排斥新人
  - 许可证不明确

高效的文档阅读路径：

1. README.md → 理解项目是什么，解决什么问题
2. CONTRIBUTING.md → 了解如何贡献，这是你的「入职指南」
3. CODE_OF_CONDUCT.md → 了解社区行为准则
4. docs/ 目录 → 深入理解架构和用法
5. CHANGELOG.md → 了解项目演进历史
6. ARCHITECTURE.md（如果有）→ 理解代码组织结构

# 标准流程
# 1. Fork 项目仓库
# 在 GitHub 页面点击 Fork 按钮

# 2. Clone 到本地
git clone https://github.com/YOUR_USERNAME/project.git
cd project

# 3. 添加上游仓库
git remote add upstream https://github.com/ORIGINAL_OWNER/project.git

# 4. 查看贡献指南中的环境搭建说明
cat CONTRIBUTING.md

# 5. 安装依赖
pnpm install  # 或 npm/yarn，注意 CONTRIBUTING.md 中的推荐

# 6. 运行测试确保一切正常
pnpm test

# 7. 创建功能分支
git checkout -b fix/improve-error-message

聚焦式探索策略：

1. 从 Issue 描述出发 → 定位相关代码区域
2. 使用 GitHub 的文件搜索功能 → 查找关键词
3. 使用 git blame → 了解代码的作者和历史
4. 阅读相关测试用例 → 测试是最好的使用文档
5. 设置断点（debugger）→ 跟踪执行流程
6. 从入口文件出发 → 理解代码调用链

实用命令：

# 查找包含特定字符串的文件
rg "functionName" --type ts
# 或
git grep "functionName"

# 查看文件的修改历史
git log --follow -p -- src/file.ts

# 查看最后一次修改某行的提交
git blame src/file.ts -L 100,120

# 搜索 commit 信息
git log --all --grep="bug" --oneline

常见的贡献友好标签：

good first issue    → 专门为首次贡献者准备，通常有详细指引
help wanted         → 维护者需要帮助，但可能需要一定经验
bug                 → 修复缺陷，通常优先级较高
documentation       → 文档改进，进入门槛最低
enhancement         → 功能增强，需要更多沟通讨论
hacktoberfest       → Hacktoberfest 活动专属标签
up-for-grabs        → 等待认领

# 在 Issue 下评论，表明意图

@maintainer I'd like to work on this issue. 

I've read through the discussion and understand the problem. 
My plan is to:
1. [简述你的方案]
2. [简述实现步骤]

Does this approach sound reasonable? I'm happy to adjust based on your feedback.

主动发现贡献机会：

1. 改进文档
   - 拼写/语法错误（最安全的第一个 PR）
   - 过时的安装说明
   - 缺少某个平台的使用示例
   - 函数/API 缺少文档注释

2. 改进开发者体验
   - 添加 TypeScript 类型定义
   - 改善错误信息（更具体、更有建设性）
   - 优化构建/测试脚本
   - 增加缺失的测试用例

3. 修复小 Bug
   - 边界情况处理
   - 内存泄漏
   - 竞态条件
   - 可访问性问题

如何表达：

"I noticed that XXX behavior seems unexpected. 
 I'd like to fix it by doing YYY. 
 Would a PR for this be welcome?"

PR 前自检：

□ 阅读了 CONTRIBUTING.md
□ 代码遵循项目的编码风格（lint 通过）
□ 添加了必要的测试用例
□ 所有已有测试继续通过
□ 提交消息符合项目约定（通常是 conventional commits）
□ 分支是最新的（已 rebase upstream/main）
□ Commit 历史干净有意义（squash 实验性提交）
□ 没有引入新的 lint 警告
□ 文档已同步更新（如适用）

## Summary

<!-- 用 1-2 句话描述这个 PR 做了什么 -->
Fix: Improve error message when config file is missing

## Problem

<!-- 描述要解决的问题 -->
When users run `cli init` without a config file, the error message
"Error: ENOENT" gives no actionable guidance.

## Solution

<!-- 描述你的解决方案 -->
- Check if config file exists before attempting to read
- Provide a clear error message with remediation steps
- Add a link to the setup documentation

## Screenshots / Logs

<!-- 如果有 UI 变化，附上前后对比截图 -->
Before:
Error: ENOENT: no such file or directory

After:
Error: Config file not found at ~/.myapp/config.yml
Run `myapp init` to create a default configuration.
See https://docs.myapp.dev/setup for more details.

## Testing

<!-- 描述如何测试你的改动 -->
1. Delete config file: `rm ~/.myapp/config.yml`
2. Run: `myapp start`
3. Verify the new error message appears
4. Unit test added: `tests/cli.test.ts`

## Related Issues

Closes #1234

心态篇：

✅ Review 是对代码的讨论，不是对你个人的评价
✅ 有意见说明维护者认真看了你的代码，这是好事
✅ 即使资深开发者的 PR 也会收到大量修改意见
✅ 不懂就问，坦诚比假装理解更受尊重

操作篇：

# 1. 仔细阅读每一条意见，标记已理解的

# 2. 在本地进行修改
git add -p  # 选择性暂存

# 3. 追加提交（不要 force push 覆盖已有提交，除非项目要求）
git commit -m "Address review feedback: improve error handling"

# 4. 回复 review 意见
"Good catch! Fixed in [commit hash]."
"I chose approach A because [原因]. What do you think?"

# 5. 重新请求 review
# 在 PR 页面点击 re-request review 按钮

✅ 正确的期待：
- 给维护者 2-5 个工作日回应
- 不要催促（"Any update?" 建议改为等待 3 天后再礼貌询问）
- 理解维护者也是人，有工作、家庭和自己的生活

✅ 有效的沟通方式：
- 信息完整：一次说清问题、环境、期望
- 尊重时间：在提问前先做好功课
- 表达感谢：维护者的工作是免费的
- 接受拒绝：维护者有最终决定权

❌ 避免的行为：
- "This is broken, fix it!!!"
- "Why hasn't this been merged yet?"
- "When will you release this?"
- 在多个 Issue 中重复提问
- 没有上下文就直接 @ 维护者

一个好的 Issue 应该包含：

Bug Report：
1. 环境信息（OS、版本、Node 版本等）
2. 复现步骤（最小可复现示例）
3. 期望行为 vs 实际行为
4. 相关日志/截图

Feature Request：
1. 要解决的问题（而非具体方案）
2. 为什么现有功能不够
3. 建议的实现方向（可选）
4. 替代方案（已经考虑过的）

使用模板：
# GitHub Issue 模板
## Description
...

## Environment
- OS: macOS 14.0
- Node.js: v20.10.0
- Package version: v2.1.3

## Steps to Reproduce
1. ...
2. ...
3. ...

## Expected Behavior
...

## Actual Behavior
...

建设性分歧处理框架：

1. 先理解对方的出发点和关切
2. 用技术理由而非主观偏好论证
3. 提供数据或具体案例支持观点
4. 愿意妥协 —— 不完美的 merged PR > 完美的未 merge PR
5. 如无法达成一致，尊重维护者的最终决定

典型表达：
"I see your point about [对方的关切]. 
 My concern is [你的关切]. 
 What if we [折中方案]?"

成长路线图：

阶段一：Reader（第 1-2 周）
→ 阅读文档，理解架构，搭建环境
→ 完成 1-2 个文档/小修小补 PR

阶段二：Contributor（第 1-3 个月）
→ 修复 bug，添加小功能
→ 参与 Issue 讨论，帮助其他用户
→ 了解项目的 release 流程

阶段三：Reviewer（第 3-6 个月）
→ 开始 review 他人的 PR
→ 在 Issue 中给出建议
→ 维护文档和测试

阶段四：Maintainer（6 个月以上）
→ 被邀请加入组织
→ 有 merge 权限
→ 参与项目方向和 Roadmap 讨论

开源影响力 = 贡献质量 × 持续时长 × 社区参与度

具体行动：

1. 打造你的 GitHub 个人主页
   - 完善 bio 和 pinned repositories
   - 使用 GitHub Profile README 展示你的技术栈和贡献

2. 写作和分享
   - 写博客记录贡献经历和学到的技术
   - 在社交媒体分享你的开源工作

3. 在社区中帮助他人
   - 在 Issue 中帮助 triage（分类和复现）
   - 在 Discussion 中回答用户问题
   - 参与代码审查

4. 演讲和活动
   - 在本地 Meetup 分享开源经验
   - 参与 Hacktoberfest 等社区活动

从零开始一个开源项目：

1. 解决一个真实存在的问题（最好是你自己遇到的）
2. 写好 README：快速开始、核心功能、示例代码
3. 配置完整的工程化骨架：
   - LICENSE（必选，推荐 MIT 或 Apache 2.0）
   - CONTRIBUTING.md
   - CODE_OF_CONDUCT.md
   - .github/ISSUE_TEMPLATE/
   - CI/CD（GitHub Actions）
   - CHANGELOG.md
4. 发布到 npm/PyPI/等注册表
5. 在相关社区推广
6. 耐心等待和持续维护

推荐的项目类型：
- CLI 工具（小而精，容易上手）
- 库/框架的插件或中间件
- 开发效率工具（模板、脚手架、脚本）
- 学习资源合集

# 安装 GitHub CLI
brew install gh

# 认证
gh auth login

# 搜索 issue（含标签过滤）
gh search issues \
  --label "good first issue" \
  --language typescript \
  --state open \
  --limit 20

# 查看 issue 详情
gh issue view 123 --repo owner/repo

# 创建 PR
gh pr create \
  --title "fix: improve error message for missing config" \
  --body-file PR_DESCRIPTION.md \
  --base main

# 查看 PR 状态
gh pr status

# 查看 CI 状态
gh pr checks

# Review PR
gh pr review 456 --approve
gh pr review 456 --request-changes --body "Please add tests"

# 列出自己的 PR
gh pr list --author @me --state open

# 交互式 rebase（清理 commit 历史）
git rebase -i HEAD~5
# 将 fixup commit 合并到目标 commit
# pick → squash 或 fixup

# 同步上游分支
git fetch upstream
git rebase upstream/main

# 从正确的 commit 创建分支
git checkout -b feat/my-feature upstream/main

# 只添加部分修改
git add -p

# 暂存当前工作（切换上下文）
git stash push -m "WIP: refactoring parser"
git stash pop

# 查看某个文件在特定 commit 中的状态
git show COMMIT_HASH:path/to/file.ts

# 二分查找引入 bug 的 commit
git bisect start
git bisect bad HEAD
git bisect good v2.0.0
# git 会自动 checkout 中间 commit，测试后标记 good/bad

# .github/workflows/ci.yml（参考）
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        node-version: [18, 20, 22]
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: ${{ matrix.node-version }}
      - run: npm ci
      - run: npm test
      - run: npm run lint

大多数 first PR 的实际情况：
- 修复一个错别字
- 补充一句文档说明
- 添加一个边界测试用例
- 改善一个错误信息

你不需要理解整个代码库才能做出有价值的贡献。
一个小而清晰的改进，胜过一个大而混乱的重构。

就从这个清单开始，按难度递增：

第 1 级（30 分钟）：
☐ 给一个项目的 README 修正一个拼写错误

第 2 级（1-2 小时）：
☐ 为某项目补充一段缺失的文档
☐ 给某个函数添加 JSDoc/TSDoc 注释

第 3 级（半天）：
☐ 修复一个标记为 good first issue 的 bug
☐ 为某 CLI 工具添加更清晰的错误提示

第 4 级（1-2 天）：
☐ 实现一个小功能增强
☐ 为某库添加新的测试用例

第 5 级（持续）：
☐ 成为项目的常驻贡献者
☐ 在社区中 review 他人的 PR