Request 是一个主打"简化 HTTP 请求客户端"的 Node.js 库（index.js 是它的主入口，仓库根目录还包含 README.md 与 CHANGELOG.md），其开源协作规范集中在 CONTRIBUTING.md 中。本文以该文档为主线，结合仓库内的 package.json 测试脚本、tests 目录的测试用例以及 release.sh 发布脚本，系统讲解如何向本仓库提交高质量 Issue、如何编写携带测试的 Pull Request、贡献者应遵守的基本规则，以及本地如何运行npm test定位失败用例。读完本文，你将掌握一套可直接落地的开源协作实操方法。

背景须知：本仓库 README.md 已明确标注项目自 2020 年 2 月 11 日起进入Deprecated（停止维护）状态，不再预期有新的功能变更合入。因此，本文介绍的贡献流程在"问题复现、测试保障、合入规范"等工程层面依然具有完整的参考价值，但实际贡献前请先确认项目维护状态与维护者的合入意愿。

一、提交 Issue 前的准备：先学会"最小可复现"

CONTRIBUTING.md 的第一条贡献准则就是：提交 Issue 时，必须提供一个足够小的、自包含（self-sufficient）的代码示例来复现问题。这不仅是礼貌，更是效率——只有基于可复现代码，维护者才能快速定位问题所在。

配合这一要求的配套工具是request-debug：提交 Issue 前，请先用它运行你的测试代码，并把调试输出一并粘贴进 Issue 中。它会在请求生命周期的各个阶段输出请求头、响应头、重定向、代理等关键信息，让维护者无需本地复现即可看到请求的实际行为。

具体提交格式要求如下：

• 代码与格式化输出必须使用围栏代码块（fenced code blocks），JavaScript 代码示例与request-debug等命令的输出分别独立成块，例如：

  // 你的 javascript 代码放在这里 var request = require('request') request('http://example.com', function (error, response, body) { console.log(error, response && response.statusCode, body) })

  // 其他格式化输出放在这里，例如 request-debug 返回的结果 { uri: 'http://example.com', method: 'GET', headers: { ... } }

• 如果问题无法被可靠复现，Issue 会被标记为Not enough info (see CONTRIBUTING.md)；

• 如果问题与 request 无关（例如属于业务层代码或使用方式问题），Issue 会被标记为Help (please use Stackoverflow)。

仓库的 tests/test-errors.js 本身就是一个"最小可复现示例"的范本：每个用例都用tape包裹一段最小代码，并断言抛出的错误信息，例如缺少options.uri时抛出options.uri is a required argument、非法 URI 时抛出Invalid URI、HEAD请求携带 body 时抛出HTTP HEAD requests MUST NOT include a request body等。当你怀疑某个参数用法有误时，先看一眼这类用例，往往比直接开 Issue 更快。

二、提交 Pull Request：测试是硬性要求

CONTRIBUTING.md 对 Pull Request 给出了三条明确要求：

1. 几乎所有的 PR 都必须附带测试（needs tests）。本仓库是一个高度依赖测试保障的库，任何新增功能或行为修改，都应先在 tests 目录中补齐对应的test-*.js用例；
2. 推送前必须在本地运行npm test，确保没有破坏已有功能；
3. 提交 PR 后会触发 TravisCI 构建，请等待构建结束并确认所有 job 全部通过后再请求合入。

对照 package.json 中的 scripts 配置，npm test实际执行的是三件事的串联：

{ "scripts": { "test": "npm run lint && npm run test-ci && npm run test-browser", "test-ci": "taper tests/test-*.js", "test-cov": "nyc --reporter=lcov tape tests/test-*.js", "test-browser": "node tests/browser/start.js", "lint": "standard" } }

• lint：使用standard代码风格检查器，保证代码风格统一（对应规则中"contributors should attempt to adhere to the prevailing code-style"）；
• test-ci：通过taper运行 tests 目录下所有test-*.js用例，覆盖 API、重定向、代理、Cookie、OAuth、流式请求、HTTPS、HAR、multipart 等数十个测试模块；
• test-browser：启动 tests/browser/start.js，起一个带自签名证书的 HTTPS 服务器，再调用 tests/browser/karma.conf.js 配置的 Karma（配合 Browserify 与 PhantomJS）在浏览器环境跑同一套测试，验证请求库在浏览器端的兼容行为。

因此，本地开发流程建议是：写完功能 → 在tests/下新增用例 → 先跑单个用例 → 最后执行完整npm test全量验证。

三、成为 Contributor：开源 Wiki 式协作模型

CONTRIBUTING.md 明确写道：为项目做出显著且有价值贡献的个人，将获得项目的 commit 访问权，可以按自己的判断直接提交代码。这个项目"更像一个开放的 wiki，而不是一个标准意义的受保护的开源项目"——这意味着：

• 获得 commit 权限的门槛是"significant and valuable contributions"，即持续的高质量贡献（带测试的 PR、准确的问题诊断、清晰的文档改进等）；
• 权限开放后仍需遵守下文的基本规则，尤其是"任何变更都应通过 Pull Request 合入"这一条，保证所有改动可追溯、可审查。

从仓库结构看，一个"显著贡献"的典型路径是：为 lib 下的某个模块（如 lib/redirect.js 重定向、lib/cookies.js Cookie、lib/oauth.js OAuth 签名）修复缺陷或补充能力，并在 tests 中同步新增对应用例——例如test-redirect.js、test-cookies.js、test-oauth.js这些测试文件本身就是各功能模块的"行为契约"。

四、贡献者基本规则（Ground Rules）

CONTRIBUTING.md 列出 8 条硬性规则，是参与本项目的底线：

1. 禁止--force强制推送，禁止以任何方式改写 Git 历史；
2. 进行中的工作应当使用非 master 分支；
3. 任何变更都必须通过 Pull Request 提交；
4. 对外 API 的变更和重大修改，应当先通过内部 Pull Request 征求其他贡献者意见；
5. 对于其他非平凡的贡献，也鼓励发起内部 Pull Request 征求意见（是否采用由贡献者自行判断）；
6. 对于重要变更，合并前等待满 24 小时，让分布在世界各地的活跃贡献者有机会发表意见；
7. 贡献者应尽量遵循项目现有的代码风格（对应standardlint）；
8. 提交 PR 前本地运行npm test，尽早发现容易被忽略的风格与测试问题。

第 1 条尤其值得注意：历史不可变是协作信用的基础，强制推送会破坏其他贡献者的工作分支，属于一票否决级别的违规行为。

五、本地测试诊断：两种运行单个用例的方式

当全量npm test失败时，CONTRIBUTING.md 给出了两种定位单个测试文件的方案：

• node_modules/.bin/taper tests/test-file.js—— 使用默认的taper测试报告器，输出带格式的 TAP 汇总，适合快速浏览失败项；
• node tests/test-file.js—— 直接以 Node 运行用例文件，查看tap（Test Anything Protocol）原始输出，适合查看完整断言细节。

以 tests/test-errors.js 为例，直接运行node tests/test-errors.js会得到类似not ok 1 - without uri的 TAP 流，以及具体的断言错误信息。这种"单文件直跑"的方式比全量跑更快，能帮助你在修改代码后反复回归验证单个行为。

仓库还提供了便捷的本地测试基础设施：tests/server.js 导出了createServer（HTTP 服务器，按请求路径分发事件）、createEchoServer（回显服务器，把 url/method/headers/body 以 JSON 返回）、createSSLServer（HTTPS 服务器，证书位于 tests/ssl），以及createPostValidator（校验 POST body 与 content-type）等工具函数。编写新测试用例时直接复用这些 helper，能让你的用例与现有测试体系保持一致。

六、版本发布流程：维护者专属的自动化脚本

CONTRIBUTING.md 声明：正式版本的发布权由项目维护者保留（"Declaring formal releases remains the prerogative of the project maintainer"），普通贡献者无需关心发布环节。但如果你想了解发布的具体工程实现，可以阅读仓库根目录的 release.sh，它给出了完整的发布链路：

1. 检查github-changes工具（指定版本0.0.14），缺失则提示安装；
2. 根据远端是否存在upstream决定 push 目标远端（upstream或origin）；
3. 执行npm version minor递增小版本号（v2.x.y → v2.x+1.0）；
4. 调用github-changes从 Pull Request 自动生成 CHANGELOG.md，并把### upcoming占位替换为当前版本号；
5. 提交 changelog 后执行npm publish发布到 npm；
6. 再执行npm version patch递增补丁版本号（为下一个 minor 版本预留空间，原因注释指向oauth-sign的一个历史问题）；
7. 最后把master分支和 tags 推回主仓库。

这个脚本与 package.json 中的version: 2.88.1相互印证：当前仓库正是走这套 minor/patch 交替递增的发布策略。贡献者了解了这条链路，就能理解为什么 PR 需要严格的测试保障——每一次合入最终都会进入 changelog 并对外发布。

七、关于贡献机制本身：这是一场持续进行的实验

CONTRIBUTING.md 在结尾强调：这套协作安排本身"是一场实验（experiment）"，随时欢迎反馈；如果你认为有值得补充或修改的内容，同样可以通过 Pull Request 来改动这份 CONTRIBUTING.md 本身。这体现了项目开放、可迭代的治理姿态——贡献规范不是一成不变的教条，而是与代码一起进化的工程资产。

结语

从最小可复现的 Issue，到必带测试的 Pull Request，再到 24 小时合入窗口与维护者专属的发布脚本，CONTRIBUTING.md 勾勒了一条完整且可执行的开源协作链路。对希望向 Request 贡献代码的开发者而言，核心要点可以浓缩为四句话：复现先行、测试必带、本地全量跑、合入守规则。这套流程同样适用于你参与其他 Node.js 开源项目——规范是通用的，落地细节则藏在每个仓库的CONTRIBUTING.md与package.json里。