为 octokit.js 贡献力量：从 Issue 提交到 Pull Request 的完整贡献指南

本文基于 octokit.js 仓库的 CONTRIBUTING.md 编写，面向希望参与这个"为 Browsers、Node.js 和 Deno 提供一体化 GitHub SDK"项目开发的开发者。文章将带你走完贡献的完整链路：如何提交高质量的 Issue（Bug 报告与功能需求）、如何 fork 并在本地搭建可运行可测试的开发环境、如何规范地发起 Pull Request 并利用 Closes #123 自动关闭关联 Issue，以及如何直接从 GitHub 的 Pull Request 安装 @octokit/* 包进行本地验证，最后补充仓库源码与维护文档中可验证的提交规范与测试门槛，帮助你的贡献一次通过。

参与项目前的约定：行为准则与新人视角

octokit.js 项目随仓库发布了 CODE_OF_CONDUCT.md（贡献者行为准则）。根据 CONTRIBUTING.md 的说明，参与该项目即表示你同意遵守其条款，这是所有贡献的前提约定。

文档特别强调了一点：新贡献者的视角是项目最宝贵的资产。由于长期维护者已经熟悉一切，很多令人困惑的地方和真实存在的问题对他们而言反而"熟视无睹"；作为新人，你遇到的困惑、踩到的坑、发现的别扭之处，恰恰是维护者最需要你反馈的内容。因此不必担心自己"不够资深"，任何真实的体验反馈都有价值。

创建 Issue：高质量问题报告的四条准则

在向目标仓库的 Issues 区提交新 Issue 之前，CONTRIBUTING.md 要求你依次完成四项准备工作：

1. 先检索是否已有同类 Issue：确保目标仓库的 Issues 区中尚无未关闭的同类问题，避免重复提交。
2. Bug 报告必须附带可复现步骤：请包含一步步的复现方法，并在 runkit.com 上创建一个可复现的测试用例（文档给出的示例为 https://runkit.com/gr2m/octokit-rest-js-1808）。可复现用例是维护者定位问题的最快路径。
3. 功能请求必须说明动机与备选方案：请分享你提出新功能背后的动机、你已经尝试过的替代方案，以及你设想的实现方式。
4. 附上对应的 GitHub 官方文档链接：为维护者核对 API 行为提供权威依据。

这四条准则本质上是把"问题最小可复现 + 背景信息充分"作为提交门槛，既能减少维护者来回追问的沟通成本，也能显著提升 Issue 被快速响应的概率。

本地搭建开发环境：fork、clone 与依赖安装

fork 并克隆仓库

参与开发的第一步是 fork 仓库，然后克隆到本地。CONTRIBUTING.md 给出了标准流程，其中 <your account name> 是你的 GitHub 账号名，<repository name> 是你 fork 的仓库名（对本文场景即 octokit.js）：

git clone https://github.com/<your account name>/<repository name>.git
cd <repository name>
npm install

从当前仓库的 package.json 可以看出该项目的运行环境要求："engines": { "node": ">= 20" }，且 "type": "module" 表明项目采用 ESM 模块体系，因此请确保本机 Node.js 版本不低于 20。

运行测试验证本地环境

依赖安装完成后，应在改动代码之前先跑一遍测试，确认本地环境工作正常：

npm test

结合仓库配置，这一步实际会做两件事（详见 package.json 的 scripts）：

• npm run -s lint：使用 prettier 对 {src,test,scripts}/**/*.{js,json,ts} 与 *.{md,json} 做格式检查；
• vitest run --coverage：运行全部测试并统计覆盖率。

值得留意的是仓库对测试质量的硬性要求：根目录 vite.config.js 中配置了覆盖率阈值 thresholds: { 100: true }，即测试覆盖率必须达到 100% 才算通过；覆盖率范围限定在 src/**/*.ts。这意味着你新增或修改的源码路径，都需要配套测试用例覆盖到。这与仓库 README 中"所有库都有 100% 测试覆盖"的定位一致，也与 CONTRIBUTING.md 强调"改动前先跑测试"的目的相吻合——确保你的开发环境基线是绿的。

当前仓库的测试用例可以参考：

• test/smoke.test.ts：冒烟测试，验证 Octokit、App、OAuthApp 是可实例化的函数且可作为 TypeScript 类型使用，RequestError 继承自 Error；
• test/app.test.ts：集成测试，通过 nock 拦截对 https://api.github.com 的 HTTP 请求，逐一验证 README 中的 app.eachRepository.iterator、app.getInstallationOctokit、createNodeMiddleware(app) 三个示例（测试内还保留了与文档一致的 JWT 载荷与签名，注释指向 https://runkit.com/gr2m/reproducable-jwt）。

其他可用的开发命令

除 npm test 外，package.json 还提供了以下脚本，供你在开发与提交前自检：

• npm run build：先执行 node scripts/build.mjs，再运行 tsc -p tsconfig.json 生成类型声明。构建脚本 scripts/build.mjs 会先用 esbuild 把 src/*.ts 编译为 ESM 输出到 pkg/dist-src，再打包为 pkg/dist-bundle/index.js，拷贝 LICENSE 与 README.md 到 pkg/，最后基于 package.json 生成带 exports 条件导出字段的 pkg/package.json；tsc 则依据 tsconfig.json 将类型声明输出到 pkg/dist-types（emitDeclarationOnly: true）。
• npm run lint / npm run lint:fix：前者只检查格式，后者自动修复格式问题（prettier --write）。建议提交前先执行 lint:fix 统一代码风格。
• npm run test:typescript：通过 tsc 以严格模式对 test/typescript-validate.ts 做纯类型检查（该文件顶部注释明确说明"这段代码不会被执行，仅用于类型检查"），确保公开 API 的类型签名符合预期。

提交 Pull Request：分支、推送与关联 Issue

当你完成代码修改后，CONTRIBUTING.md 要求的 PR 提交流程如下：

1. 在本地新建分支：不要直接在 main 上改动，为主题改动单独建一个 topic 分支；
2. 在分支上完成修改并推送到你的 fork；
3. 从 topic 分支向 octokit/<repository name> 仓库的 main 分支发起 Pull Request；
4. 在 PR 描述中标注其处理或关联的 Issue 编号：在描述中写入 Closes #123（#123 替换为实际 Issue 编号），PR 合并后该 Issue 会被自动关闭。

提交信息规范：决定版本号的语义化提交

虽然 CONTRIBUTING.md 未展开提交信息格式，但仓库的 MAINTAINING.md 明确说明：发布流程由 semantic-release 自动化驱动，提交信息的前缀直接决定版本号如何递增（该规范同样约束你作为贡献者提交的 commit message）：

1. fix: ... 或 fix(scope name): ... 开头：递增补丁版本，如 1.2.3 → 1.2.4；
2. feat: ... 或 feat(scope name): ... 开头：递增功能版本，如 1.2.3 → 1.3.0；
3. 正文中包含 BREAKING CHANGE:：递增主版本，如 1.2.3 → 2.0.0。

一次只升一个版本号，以最高的变更级别为准。semantic-release 除发布 npm 包外，还会自动创建 git tag、生成 GitHub Release，并从提交信息生成 changelog。实际触发这些行为的发布分支配置见 package.json 的 release.branches（main、next、beta、debug 以及 *.x 维护分支）。所以，即便作为外部贡献者，也请让 PR 的最终合并提交信息符合上述语义化提交约定，否则维护者将不得不改用 Squash & merge 重写提交信息（见 MAINTAINING.md 中的说明）。

在本地测试他人提交的 Pull Request

社区协作中你常常需要验证"某个未合并 PR 是否解决了你的问题"。对此 CONTRIBUTING.md 提供了一条捷径：直接从 GitHub 的 Pull Request 安装对应包，无需等待合并发布。将 [PULL REQUEST NUMBER] 替换为实际的 PR 编号：

npm install https://github.pika.dev/octokit/<repository name>/pr/[PULL REQUEST NUMBER]

测试结束后，可以随时恢复为 npm 上默认的正式版本：

npm install @octokit/<repository name>

这条命令对 Octokit 生态中任意子仓库（如 @octokit/request、@octokit/core、@octokit/app 等）同样适用——只需把 <repository name> 换成对应仓库名即可。在当前仓库（octokit.js）中，这些子包正是其依赖基础：octokit 包聚合了 @octokit/app、@octokit/core、@octokit/oauth-app、@octokit/plugin-* 系列插件与 @octokit/webhooks 等（见 package.json），因此"先装 PR 版本、验证通过再等正式发布"是验证上游修复的实用工作流。

维护者视角：PR 合并、breaking change 与维护版本

Squash & merge 与语义化提交

如果某个 PR 本身没有问题、但提交信息不符合 semantic-release 约定，维护者会使用 GitHub 的 Squash & merge 按钮，在确认对话框中把提交信息改写为符合规范的格式后合并（MAINTAINING.md 中对此有专门提醒）。对贡献者而言，这同样说明：PR 主题分支上的提交历史并不强制逐条符合规范，但最终合并进 main 的提交信息必须语义化。

Breaking change 的合并顺序

MAINTAINING.md 还描述了涉及破坏性变更时的特殊流程：breaking change 应先合并到 beta 分支（基于 main 创建、短期存在），在 beta 上继续测试并汇集更多破坏性变更，再通过从 beta 到 main 的草稿 PR 合并发布。由于 Octokit 生态存在依赖层级，破坏性变更需按依赖树自底向上合并（顺序大致为 octokit/types → endpoint → request → 各插件 → auth 策略 → core → 各 *-methods → oauth-app → webhooks → app → octokit/octokit.js → octokit/rest.js），先合并叶子节点、再合并上层节点。

维护版本（maintenance release）

对于已发布的老版本线（如 2.x），维护者可从对应 tag 创建维护分支（如 git checkout -b 2.x v2.10.9），在其上继续发布仅含 fix: / feat: 的维护版本（维护版本不支持破坏性变更），npm 发布会使用 @release-*.x tag 以免被当作 @latest。完整流程见 MAINTAINING.md。

源码速览：你将要贡献的模块边界

为了让你的贡献更精准，这里结合当前仓库源码给出各模块的职责边界（均可在仓库中直接查看）：

• src/octokit.ts：Octokit 客户端本体，由 @octokit/core 通过 .plugin() 组合 restEndpointMethods、paginateRest、paginateGraphQL、retry、throttling 五个插件生成，并通过 .defaults() 预设了 userAgent: octokit.js/<VERSION> 与默认限流回调（onRateLimit / onSecondaryRateLimit，仅在 retryCount === 0 时重试一次）；同时从 @octokit/request-error 重新导出 RequestError。它是 README 中 octokit.rest.*、octokit.request()、分页与限流重试能力的来源。
• src/app.ts：通过 .defaults({ Octokit }) 将上述 Octokit 注入 @octokit/app 与 @octokit/oauth-app，导出 App、OAuthApp 与 createNodeMiddleware，让 GitHub App、Webhooks、OAuth 能力共用同一套客户端配置。
• src/index.ts：统一出口，对外暴露 Octokit、RequestError、PageInfoForward、PageInfoBackward、App、OAuthApp、createNodeMiddleware。
• src/version.ts：导出 VERSION（开发版为 0.0.0-development，发布时由 semantic-release 插件在 pkg/*/version.* 中更新，见 package.json）。

如果你准备提交的是 Bug 修复，建议同时查看 test/app.test.ts 中 nock 拦截请求的写法——它展示了在不触碰真实 GitHub API 的前提下验证客户端行为的标准模式，也是新测试用例的最佳模板。

总结：一次贡献的完整清单

对照 CONTRIBUTING.md 与仓库实际配置，一次合格的贡献可以按以下清单自查：

1. 提交 Issue 前先检索是否重复；Bug 报告附 runkit 可复现用例，功能请求说明动机与备选方案，并附官方文档链接；
2. 本地 npm install 后先跑 npm test（含 lint + vitest 全覆盖检查）确认基线通过；
3. 在新分支上改动，改动涉及 src/**/*.ts 时务必补测试用例，保持 100% 覆盖率；
4. 提交前用 npm run lint:fix 统一格式、用 npm run build 验证可构建；
5. 推送 fork 后向 octokit/<repository name> 的 main 发起 PR，并在描述中写入 Closes #123 关联 Issue；
6. 保证最终合并进 main 的提交信息符合 fix: / feat: / BREAKING CHANGE: 语义化约定，以便 semantic-release 自动决定版本号。

遵循以上流程，你的贡献将顺畅地进入 Octokit 生态的自动化发布管道，被数以万计的使用者直接受益。