Botkit 代码贡献指南：从 CLA 签署到 PR 合入的完整规范

Botkit 是一个用于构建聊天机器人、应用及多平台自定义集成的开源开发者工具，本仓库（gh_mirrors/bo/botkit）以 lerna monorepo 形式同时托管了 Botkit 核心库与各主流消息平台的适配器（Slack、Facebook、Webex、Twilio SMS、Web 等）。本文以 CONTRIBUTING.md 为骨架，结合仓库内的源码、测试与构建脚本，完整梳理参与 Botkit 贡献的规范流程：从 CLA 签署、提交 Issue、发起 Pull Request，到代码风格、JSDoc 文档与 Git Commit Message 的具体要求。读完本文，你将能够按照官方验收标准提交一份可被合入的 Botkit 补丁。

理解仓库结构：贡献前需要认识的 monorepo 布局

Botkit 仓库采用 lerna 管理的多包（monorepo）结构，lerna.json 中声明 "packages": <a href="https://link.gitcode.com/i/8107a951304df782ad601c3313786f1a" target="_blank">"packages/*"]，即所有子包位于 packages/ 目录下。核心包为 [botkit（Botkit Core library），其余为平台适配器与扩展，例如：

• botbuilder-adapter-slack
• botbuilder-adapter-facebook
• botbuilder-adapter-webex
• botbuilder-adapter-hangouts
• botbuilder-adapter-twilio-sms
• botbuilder-adapter-web
• generator-botkit（Yeoman 脚手架生成器）
• botkit-plugin-cms（Botkit CMS 插件）

根目录 package.json 暴露了与贡献者密切相关的顶层脚本，这些脚本正是 PR 提交前的自检入口：

脚本	作用
postinstall	安装依赖后自动执行 lerna bootstrap --hoist，完成本地包之间的链接
build	lerna run build，逐个包执行 TypeScript 编译
test	lerna run build ; lerna run test，先构建再跑全部测试
build-docs	lerna run build-docs，重新生成 packages/docs 下的类参考文档
eslint / eslint-fix	对 packages/*/src 下的 TypeScript 源码执行 ESLint 检查/自动修复

每个子包都带有独立的 tsconfig.json、package.json 与 tests/ 目录。例如 botkit/package.json 中 test 脚本为 tsc ; nyc mocha tests/*.tests.js——先编译 TypeScript，再用 nyc 收集覆盖率的 mocha 运行 tests/ 下以 .tests.js 结尾的测试文件。

签署 CLA：贡献前的第一步

CONTRIBUTING.md 明确指出：本项目欢迎任何贡献与建议，但绝大多数贡献需要你同意一份贡献者许可协议（Contributor License Agreement，CLA），声明你拥有所贡献代码的权利，并实际授权项目使用该贡献。

当你提交 Pull Request 时，一个 CLA bot 会自动判断你是否需要签署 CLA，并在 PR 上以标签（label）、评论（comment）等方式提示。你只需按 bot 的指引完成操作即可。该 CLA 是一次性的——在你使用本项目 CLA 覆盖的所有仓库中，只需签署一次，后续提交无需重复操作。

行为准则（Code of Conduct）

项目采用 Microsoft Open Source Code of Conduct（微软开源行为准则）。所有参与讨论、提交 Issue、Review PR 的贡献者都应遵守该准则，以营造开放、包容的协作环境。任何关于准则本身的疑问或举报，可通过官方维护渠道提出。

提交 Issue：如何写一份高质量的问题报告

在创建 Issue 之前，请先阅读以下要点，并尽可能在报告中包含更多细节：

• Botkit 版本：你正在使用的 Botkit 版本号（可在对应包的 package.json 中查看，例如 packages/botkit/package.json 中的 version 字段）。
• 操作系统：你使用的操作系统及版本。
• 复现上下文：如适用，说明问题发生时你在做什么，以及你期望发生什么。

此外，以下信息将显著加速问题的定位与解决：

• 截图与动画 GIF：直观呈现界面表现。
• 错误输出：终端、DevTools 或 alert 中出现的报错日志。
• 先行搜索：在提交前对已有 Issue 做一次粗略检索（cursory search），确认是否已有相似问题被提交，避免重复报告。

提交 Pull Request：合入前的完整要求

CONTRIBUTING.md 对 PR 提出了明确的质量门槛，每一项都直接影响能否被 Review 与合入：

1. 主题简洁、描述详实：PR 应包含简洁的主题（topic）与详细的说明文字，清晰标明变更目的（purpose）以及应被接受的依据（justification）。
2. 关联 Issue：创建或链接一个已有 Issue，用于说明驱动该 PR 的需求。Issue 可以承载更多背景细节，并承载关于"采取哪种方案更符合公共价值"的讨论。
3. 尽量附带截图与 GIF：尤其是涉及 UI、消息交互或 Web 客户端（如 botbuilder-adapter-web 的 client/）的改动。
4. 提交前运行 npm test 并修复问题：确保构建与全部测试通过。
5. 为新增功能补充测试：任何新功能都应有测试覆盖；对已有代码的更新也应新增或同步更新测试。仓库中测试的典型组织方式是每个包下的 tests/*.tests.js，使用 mocha 的 describe / it 结构，例如 packages/botkit/tests/Core.tests.js 验证 Botkit controller 的构造与多适配器场景下的 bot worker 派生，packages/botbuilder-adapter-facebook/tests/FacebookAdapter.tests.js 验证 FacebookAdapter 的构造与请求处理。
6. 用 Markdown 编写文档：涉及使用方式、配置项或行为变更时，应同步更新文档。本仓库的文档集中在 docs/ 目录（如 docs/core.md、docs/conversations.md、docs/platforms/index.md、docs/reference/index.md）。
7. 遵循 JSDoc 规范书写注释：公共 API 与核心逻辑应使用 JSDoc 风格注释。仓库源码中已有大量范例，例如 packages/botkit/src/botworker.ts 与 packages/botkit/src/core.ts 中通过 @param、@returns 标注参数的名称、类型与含义。
8. 遵循 Git Commit Message 风格：使用简短、现在时的提交信息，具体规范见下文"Git Commit Message 规范"小节。

代码风格指南：通用代码要求

CONTRIBUTING.md 的 Styleguides 章节定义了通用代码风格，这些规则在合入 Review 时会被逐一检查：

• 文件以换行符结尾（End files with a newline）。
• require 语句按顺序放置：
  • 先是内置 Node 模块（如 path）；
  • 再是本地模块（使用相对路径）。
• 避免平台相关代码：拼接文件名一律使用 path.join()，而不是依赖操作系统分隔符的字符串拼接。这一要求在源码中得到贯彻，例如 packages/botkit/src/core.ts 中通过 path.join(__dirname,'views') 构造视图目录路径，并在比较路径时使用 path.relative(path.join(this.webserver.get('views')), path_to_view)；同一文件的 loadModule 也使用 path.join(p, file)（见 core.ts）。
• 显式返回时使用裸 return：当函数在末尾需要显式返回时，直接写 return，而不要写 return null、return undefined，也不要只写 null 或 undefined。

Git Commit Message 规范

提交信息是代码历史的公共语言，CONTRIBUTING.md 给出了三条硬性规则：

• 使用现在时：写 "Add feature" 而不是 "Added feature"。
• 使用祈使语气：写 "Move cursor to..." 而不是 "Moves cursor to..."。
• 首行限制在 72 个字符以内：保证在窄屏终端与各类 Git 工具中可读。
• 尽量引用 Issue 与 PR：在提交信息中引用相关 Issue/PR 编号，便于追溯变更动机。

本地构建与测试：提交前的自检流程

CONTRIBUTING.md 要求提交 PR 前运行 npm test。要执行这一自检，需要先在本地搭好开发环境。根据 readme.md 的 "Build Botkit locally" 章节，步骤如下：

全局安装 lerna 与 TypeScript：

npm install -g typescript
npm install -g lerna

克隆仓库并安装依赖（根目录 npm install 会通过 postinstall 自动执行 lerna bootstrap --hoist，将各子包相互链接）：

git clone https://gitcode.com/gh_mirrors/bo/botkit.git
cd botkit
npm install

显式执行 lerna bootstrap（如未由 postinstall 触发）：

lerna bootstrap --hoist

构建全部库：

lerna run build

如修改了类定义并需要更新类参考文档（packages/docs 下的 reference 文档）：

lerna run build-docs

运行完整测试：

npm test

该命令等价于 lerna run build ; lerna run test，即先确保所有 TypeScript 包编译通过，再逐个包执行测试。每个包的测试脚本各自负责编译与运行，例如核心包的 tsc ; nyc mocha tests/*.tests.js 会在编译后以 nyc 覆盖率模式运行 mocha 测试套件。提交前确保构建与测试全部绿灯，是 PR 被合入的基本前提。

小结

一份合格的 Botkit 贡献，从签署 CLA 开始，经过高质量的 Issue 描述、带测试与文档的 PR 提交，最终通过代码风格与 Commit Message 规范的 Review。对照本文梳理的检查清单——npm test 全绿、新增功能有测试覆盖、公共 API 带 JSDoc 注释、文档同步更新、提交信息采用现在时祈使语气且首行不超过 72 字符——你的补丁将具备被顺利合入的全部要素。更详细的构建命令与包清单可继续查阅 readme.md 与 packages 目录下各包的说明文档。