contributing-upstreamlisted

# 向上游贡献 主线事实：用户数 ≫ 贡献者数 ≫ 维护者数，**维护者的时间极稀缺**。让贡献信噪比高、值得投入时间；接受 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 附件的邮件。主动指出需特别