# Contributing Upstream

> 维护者时间极稀缺：bug 报告、最小可复现、issue、PR、CONTRIBUTING.md、许可证与安全披露都要信噪比高。 Use when the user wants to report a bug, submit a pull request, contribute to an open-source project, write a minimal repro, or asks whether to fork upstream. 触发于「我要报个 bug/提个 PR/贡献开源/写个复现」。

- Skill: `anthealaffy/contributing-upstream` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add anthealaffy/contributing-upstream`
- Raw SKILL.md: https://api.skillmd.com/api/skills/anthealaffy/contributing-upstream/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: AntheaLaffy (https://skillmd.com/u/anthealaffy)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/anthealaffy/contributing-upstream

---


# 向上游贡献

主线事实：用户数 ≫ 贡献者数 ≫ 维护者数，**维护者的时间极稀缺**。让贡献信噪比高、值得投入时间；接受 PR 意味着维护者承接长期责任——那几千行代码从此由他永久维护，而你作为贡献者可以转身离开。由你论证这份贡献为何值得这个负担。讲清「为什么」的契约见 `writing-for-readers`。

## 操作契约

- **先问，不猜。** 报 bug 或写 PR 前，环境、版本、复现步骤、动机等缺失就逐项向用户补齐；拿不到的明确标注缺失，不编造。
- **先搜索已有 issue。** 已有讨论就补充信息，不创建重复条目——减少维护者噪音。
- **安全漏洞不公开发布。** 私下联系维护者，按 SECURITY.md 流程走，给合理修复时间。
- **许可证与雇主政策。** 你的贡献受项目许可证约束；GPL 等 copyleft 要求派生作品开源，可能影响雇主（choosealicense.com 有更多实用信息）。在职期间给开源项目贡献前，先弄清公司对贡献的政策。
- **复杂改动升级盘问。** 背景复杂时用 `/grilling` 逐轮挖清动机与取舍，再落笔。
- **没回复别催。** 维护者多是志愿者；一两周后礼貌跟进一次可以，每天催不行。

## bug 报告：一次给全理解与复现所需的一切

- 环境：操作系统、版本号、相关配置
- 期望结果 vs 实际发生：**两者都写**——有时你观察到的其实是「设计如此」，这个落差恰恰说明问题可能在文档而非代码
- 复现步骤：编号的有序列表，越具体越好：「点击按钮」不如「以管理员身份登录 /settings 页，点击 Submit 按钮」
- 已尝试过什么：避免重复建议，表明做过初步调查
- 模板只是格式：GitHub 的 issue 模板填得差照样是差报告——好坏取决于你是否理解 bug 报告的目的：**为维护者省下修复它的时间**
- 噪声评论是三重伤害：重复 issue 让搜索更难、让维护者更痛苦、让订阅该 issue 的人收到海量无关邮件。想表达「我也是」？点 issue 顶部的 👍（维护者会按它排序），别评论 "+1"。真正有用的评论是补一条新的复现路径或最小复现。

**最小可复现示例（minimal repro）是黄金**：可靠复现往往是修复最难的一步。要么你花时间做复现，要么维护者花时间做复现——用户比维护者多得多，应该由你来做。贴个 10 万行项目的链接说「编译不过」等于没报告。

## 提交代码贡献

- 读并遵守 CONTRIBUTING.md：bug 报告流程、PR 流程、测试方式、代码约定都在里面。
- 从小处开始：修错别字或改进文档是好的首次贡献——熟悉流程，不必在内容本身来回拉锯。
- 持续的可靠贡献是成为维护者的正路：维护者通常从贡献最多、最可信的人里找接班人。

## Pull Request

- **隔离真正想被接受的改动。** 无关内容混改，审核人很可能退回整理。多个看似无关、但都为同一特性铺路的改动可开大 PR，此时 commit hygiene 尤其重要——**明确告诉审核者「请按提交逐个审阅」**，而不是看整体 diff；你比审核者更清楚该怎么审。拆分标准见 `writing-for-readers`。
- **讲清两层「为什么」。** 不要只描述改了什么：① 为什么这样改、为什么这是好的解法；② 为什么这个项目**应该收下**这个改动（新特性/修 bug 值得吗？）。PR 描述就像一封带 diff 附件的邮件。主动指出需特别关注的部分；按 CONTRIBUTING.md 与改动性质补充取舍说明、测试方法等。
- **AI 生成代码你要当过滤器、能答辩。** AI 能快速产出看似靠谱的 PR，但维护者追问「为什么选 A 不选 B」时，作者答不上来就露馅了。如果流程只是「描述 bug → 回车 → 粘贴」，那维护者自己就能让 LLM 生成——他没那么做的原因往往值得思考。提交你解释不了的 AI 代码，等于把审查乃至维护负担甩给已过载的维护者。可用 AI 定位问题、产出修复，但理解与打磨责任在你。
- **被拒是常事。** 维护者可能因不符合项目方向、增加不愿承担的复杂度、需求论证不足而拒绝——由你论证接受的价值。
- **fork 是最后手段。** 维护者明确拒收后才有 fork 的选项。fork 代价高昂：两个高度重叠的项目分摊维护精力，一方的改进不会自动惠及另一方，而且从此你是这个副本的唯一维护者。「我的特性没被收」不是 fork 的好理由；「我要做范围上根本不同的项目」才是。真 fork 了记得感谢原项目。

## 练习

学习材料在 `exercises.md`。

> 改编自 MIT The Missing Semester 课程 Lecture 8: Beyond the Code（讲义 + 口播稿，CC BY-NC-SA 4.0）：https://creativecommons.org/licenses/by-nc-sa/4.0/ · 课程站点：https://missing.csail.mit.edu/ · 讲座视频：https://www.youtube.com/watch?v=2DOEATfXT8k