Mocha 维护者手册:从贡献者到维护者的完整协作与发布流程指南

原创2026-09-19 12:19:431,831 阅读

Mocha 维护者手册:从贡献者到维护者的完整协作与发布流程指南

Mocha 是运行于 Node.js 与浏览器端的经典测试框架,本篇文章以其官方《Maintainer's Handbook》(见仓库根目录 MAINTAINERS.md)为骨架,系统讲解 Mocha 社区中「用户 — 贡献者 — 维护者」的角色划分、Issue 与 Pull Request 的分流标签体系、基于语义化版本的合并与里程碑策略,以及由 Release Please 驱动的自动发布流程。读者读完本文,将掌握 Mocha 项目实际运转的协作规范、标签规则与发布操作,并能将其中的工程实践迁移到自己的开源项目中。

这份手册写给谁

Mocha 的维护者手册明确面向三类读者:Mocha 的现任维护者、潜在的未来维护者,以及任何好奇「Mocha 维护者究竟如何维护 Mocha」的人。手册的核心动机很朴素——把流程写下来:项目的维护者们希望避免围绕「不成文的规则」产生冲突与误解,因为把规则写出来,既是最直接的沟通方式,也是最直接的修改方式。

为此,手册首先给出了一套贯穿全文的术语体系,把任何参与 Mocha 的人划分到三个桶里:user(用户)、contributor(贡献者) 和 maintainer(维护者)。

User:使用者

「用户」指任何消费 Mocha 来编写或执行测试的个体开发者。用户与贡献者互动,使用贡献者提供的软件、网站与文档。用户在 Mocha 的官方社交空间(如 mochajs Discord 的所有频道、mochajs GitHub 组织下的所有项目,以及未来 Mocha 组织的线上或线下活动)互动时,需要遵守 行为准则。

Contributor:贡献者——不写代码也可以

手册强调的第一条最重要原则是:

你不必写代码也能成为贡献者!

「贡献者」指以某种方式回馈项目与社区的人,贡献形式包括但不限于:

  1. 遵循报告规范地提交 bug 报告;
  2. 提出具有广泛适用性的增强建议并进行讨论;
  3. 在 Discord、StackOverflow 等渠道帮助他人解答 Mocha 相关问题;
  4. 提交修复 bug、改进文档、改善开发者体验、提升代码质量或实现请求增强的 Pull Request;
  5. 在 Pull Request 上评审代码;
  6. 提供设计素材;
  7. 在个人博客发布教程;
  8. 为项目资金的使用提出建议;
  9. 组织「Mocha 品牌」的活动或工作坊;
  10. 招募更多贡献者(但不要骚扰式推广);
  11. 开展用户调研、收集反馈(同样不要骚扰式推广)。

简而言之:只要你在为 Mocha 增值,你就是贡献者。 由于 GitHub 平台的特性,很难识别那些在站外或「非代码」形式的贡献;如果你知道有未被注意的优秀贡献,可以提请维护者关注。此外,向 Mocha 的 Open Collective 捐款也是一种支持方式——适合想为开源事业出力、但暂时找不到时间以其他方式贡献、或只想表达感谢的人。

Maintainer:维护者

维护者对 Mocha 项目以及 mochajs 组织下的其他项目拥有特定的「权利」(权限),而随之而来的是更高的责任。但手册同样强调了两点:成为维护者不设技术能力的门槛——不意味着缺乏技术监督,每个 PR 最终都会被评审;以及不写代码也可以成为维护者。如果你觉得自己经验不足,那这种想法是错误的,唯一的硬性要求是履行下述责任并怀有服务项目的意愿。(注:在 GitHub 语境中,maintainer 与 Collaborator / Owner 同义。)

维护者的责任

  • 践行而非仅仅遵守行为准则:维护者在线上线下的一言一行都反映着项目与其他维护者;如果对行为准则不理解,教育自己是维护者自己的责任(这不意味着准则不可修改)。
  • 规律贡献:维护者必须是一个「规律贡献」的贡献者——每天、每周甚至每月几次都可以,只要是规律的。毕竟大家都是真实生活的人,对许多人而言开源只是偶尔的爱好。
  • 帮助定义「什么是 Mocha」:维护者至少要理解当前的定义,这些核心问题包括:Mocha 的范围是什么?精力应聚焦何处?什么紧急、什么可以等待?什么可以破坏、什么不可触碰?哪些用户反馈有价值、哪些没有?
  • 开启双因素认证(2FA):维护者的 GitHub 账号必须启用 2FA。

维护者的权利

维护者可以自行斟酌行使以下零项或多项权利:

  • 合并 Pull Request;
  • 修改 Issue(关闭、加标签、指派给其他维护者等);
  • 修改 GitHub Projects;
  • 取消构建、重启任务或与 CI 服务器交互;
  • 对 GitHub 集成做增删改查;
  • 参与决策过程;
  • 向团队添加新维护者;
  • 打标签并发布 Mocha 到 npm。

需要特别注意的是:维护者虽然有能力直接提交到 main 分支,但应尽量避免——除非该改动不会引起其他维护者合理异议,且不影响 Mocha 的 API 或输出。例如修正 CHANGELOG.md 的拼写可能不需要 PR,但改动某个 reporter 的输出则几乎必然需要 PR。维护者被信任使用最佳判断,不确定时宁可保守。

期望的活跃度

维护团队一般期望维护者平均做到:每周多种形式的多次贡献;每月一次有意义的、非平凡(non-trivial)的贡献。这些都是粗略平均值而非硬性下限,偶尔跳过一两周完全没问题。「有意义的非平凡贡献」可以是一个深思熟虑的评论、一个非直截了当的 PR,或任何真正为项目增值的事情。

如果需要离开较长时间,提前告知其他维护者即可:

  • 离开一两个月:无需担心;
  • 未提前通知地失联一个月:团队会联系你确认是否还想继续担任维护者;
  • 三个月不活跃,或两个月未提前通知:大概率会被移除维护者身份。

即使主动卸任或被移除,只要回来并能规律活跃,团队会乐意重新恢复你的身份。

关于「Owners」

部分维护者拥有 mochajs GitHub 组织的完全管理员权限,或拥有 npm 发布权限。拥有发布权限者必须使用 npm 的 2FA;这一层级的权限由现任 owners 授予那些已赢得项目信任的维护者。

决策流程:寻求共识

Mocha 采用共识寻求型决策(consensus-seeking decision-making):所有维护者先尝试达成一致,若失败则通过简单投票决定。

在做重要或可能有争议的决定之前,活跃维护者会努力征求他人反馈。鉴于维护团队的地理分布与可用性差异,团队承诺尽最大努力征求反馈;在大多数情况下,共识投票会等待至少两周,特别重要的决策则等待一个月。换句话说:想让自己的意见被听到,就要规律参与——团队不会一直等待未必会来的反馈。

沟通方面,维护者主要聚集在 Mocha 的公开 Discord 服务器中,任何人都可以加入;视频或语音会议会视日程安排定期或不定期举行(毕竟大家都有真实生活,时区也各不相同)。

处理 Issue 与 Pull Request:先懂语义化版本

所有新 Issue 都需要被分流(triage),所有 PR 都必须被检查。为此,维护者必须理解语义化版本(SemVer),因为 Mocha 严格遵循它。SemVer 的 TL;DR 是:

  • MAJOR:不兼容的 API 变更;
  • MINOR:向后兼容的新功能;
  • PATCH:向后兼容的 bug 修复。

每一个 PR 都必须带有且仅带有以下三个标签之一:

标签 适用场景
semver-patch 向后兼容的 bug 修复、文档,或任何不影响生产安装(npm install mocha)的改动
semver-minor 向后兼容的新功能或可用性/接口增强
semver-major 对 API 的不兼容(破坏性)变更

引入破坏性变更的 PR 一律视为 semver-major,无论它是 bug 修复、新功能还是其他什么。就上述定义而言,Mocha 对「API」有独特的界定,包含以下内容:

  1. Mocha 的文档化编程接口中未被显式标记为 @private 的部分;
  2. Mocha 的机器可读的 reporter 输出;
  3. Mocha 的默认设置;
  4. Mocha 的命令行选项;
  5. Mocha 支持的运行环境,包括浏览器版本、Node.js 版本,以及与流行模块加载器(如 AMD)的兼容性。

规则是「宁可偏向用户」:对私有 API 的破坏性变更,仅当已知被活跃开发的项目消费时才视为 semver-major。典型的破坏性变更示例包括:在原本不抛错的地方抛出 Error;移除某个命令行选项或别名;从 CI 配置中移除某个运行环境;更改默认 reporter;更改默认值导致原本通过的测试开始失败(或反之)——唯一的例外是修复疑似误报(如修改默认 timeout 值这种场景)。

当前仓库的 package.json 版本为 12.0.1,Node 版本要求为 ^20.19.0 || >=22.12.0,CHANGELOG.md 中按 SemVer 组织的历史条目(如 12.0.0 的破坏性变更、12.0.1 的修复与依赖升级)正是这套标签体系的落地产物。

Issue 分流:标签体系与处理路径

Issue 应按 Mocha 的 GitHub Issue 表单 提交(仓库中按 01-bug.yml、02-documentation.yml、03-feature-request.yml、05-repository-tooling.yml 等组织)。如果缺少任何必需信息,添加 status: waiting for author 标签并礼貌地索要缺失信息。

Issue 元标签

对所有 Issue,根据其涉及领域打上 area: 标签:

标签 含义
area: async Mocha 异步使用相关问题
area: browser 浏览器环境特有问题的 Issue
area: parallel Mocha 并行模式相关 Issue
area: documentation 文档相关问题(由表单自动添加)
area: repository tooling 围绕 Mocha 的 CI、自身测试套件或内部工具链的 Issue
area: security 涉及漏洞(实际的或潜在的)
area: windows Windows 特有 Issue,尤其是路径差异

此外还有状态类标签:

  • good first issue:实现工作很可能适合从未为 Mocha(甚至任何开源项目)贡献过的新手;
  • status: duplicate:已有等价 Issue 时添加,按 not planned 关闭,并评论形如 duplicate of #<issue-number>;
  • status: in discussion:Issue 被社区输入和/或更深入讨论阻塞时添加;
  • status: in triage:新 Issue 自动添加;Issue 等待维护者关注时重新添加;
  • status: waiting for author:Issue 被作者侧信息阻塞时添加。

仓库中的自动化也参与了这个流程:.github/workflows/auto-label.yml 会在 Issue 首次打开时自动打上 status: in triage 标签,而 .github/ISSUE_TEMPLATE/01-bug.yml 会为新 bug 自动附加 type: bug 与 status: in triage 两个标签。

各类 Issue 的分流细则

🐛 Bugs:bug 报告应包含一个不熟悉 Mocha 的人也能在本地复现的方式。分流时移除 status: in triage 并追加标签:

  • bug 有效且可复现:加 status: accepting prs;
  • 可能有效但复现不可行:加 status: waiting for author,并礼貌解释复现为何不可行;
  • 可能有效但价值不明确:加 status: in discussion,说明「或许值得修,需要更多社区输入」;
  • 明确不值得修或无效:解释原因并按 not planned 关闭;完全不是 bug 的加 invalid,大致是 bug 但无法/不应修复的加 status: wontfix。

📝 Documentation:文档类报告应明确指出文档中的缺口或问题,按与 bug/feature 类似的方式分流——文档本身就是一个产品领域。移除 status: in triage,保留自动添加的 area: documentation 标签。

🚀 Features:功能请求应给出「为什么值得花维护时间」的有力理由。鉴于 Mocha 将稳定性置于增长之上,这个门槛可能很高。分流路径与 bug 类似:理由充分且值得维护成本则加 status: accepting prs;理由不清则加 status: waiting for author 并说明缺失之处;价值不明确则加 status: in discussion;无效则解释后按 not planned 关闭并加 invalid 或 status: wontfix。

🛠 Tooling:针对 Mocha 内部开发流程改进的 Issue,可由维护者更非正式地讨论,移除 status: in triage 并保留自动添加的 area: repository tooling。

❓ Questions:Issue 跟踪器不是提问的地方。若 Issue 更像提问,移除 status: in triage、加 type: question 标签、礼貌地将用户引导至 .github/CONTRIBUTING.md 中的「Got a Question?」章节,并按 not planned 关闭。如果问题其实与 Mocha 无关(人们通常不愿相信这一点),可以展示反例,并在可能的情况下将作者引导到负责的项目。若该问题被反复提出,添加 faq 标签(获得大量 👍 的问题也适用)。

关闭 Issue 的规则

  • 在 commit 或 PR 中写 closes #000(000 为 Issue 编号)或 resolves #000,可在 PR 合并后自动关闭原 Issue;
  • 重复 Issue:新评论中写 duplicate of #000 然后关闭;
  • 支持类问题若已被解答,则关闭;
  • 与 Mocha 无关或 bug 无法确认的,标记 invalid 并关闭。

评论与评审:善待每一个人

所有维护者都应礼貌友善。 即使 PR 未被合并,也要感谢外部贡献者;如果 PR 在没有对应 Issue 讨论的情况下被打开(并关闭),要让他们知道「先建 Issue」本可以避免白费功夫;拒绝任何 PR 时都要清晰、客观地说明理由。若需要更多信息,礼貌地请用户提供,并提醒他们使用 Issue/PR 模板。

评审代码时使用 GitHub 的 code review 功能。请求另一位维护者 review「可能或未必」真的会得到 review——不要干等;如果 PR 必须等待某位维护者的输入才能推进,就把对方指派(assign)到该 PR。

关于「混蛋」的部分

总会遇到混蛋,手册给了具体的应对建议。

粗鲁或自以为有权的人:这类用户觉得 Mocha 项目及维护者「欠」他们时间或支持——事实并非如此。但这种行为往往说明对方是开源新手,很多人只是不懂。教育他们不是你的责任。建议包括:

  1. 生气了就先等 20 分钟再写评论;
  2. 用善意「杀死」他们——解释他们的表现方式,或许附上一两篇相关好文;
  3. 不要把问题变成「用户 vs 维护者」,把他们当成潜在的未来维护者;
  4. 不要给戏剧加戏——可以尝试私下联系(邮箱可能在 GitHub 个人资料里),对方多半不会再出现;
  5. 如果 Issue 失控,锁定它;
  6. 如果有人屡次粗鲁且不知悔改,可以禁止其参与 mochajs 组织;没有权限就联系有权限的 owner。

行为准则违规:手册坦承「本节是理论性的,因为尚未发生过」,流程为:告知当事人违规并附上行为准则链接;向 OpenJS Foundation 寻求进一步指导;屡次违规者在技术可行的范围内将被封禁;维护者与贡献者都不豁免于行为准则。

分支管理

main 是 mochajs/mocha 及其他仓库中唯一受维护的分支,也是唯一禁止 force-push 的分支。维护者可以向仓库推送新分支,但完成后必须删除(合并 PR 时 GitHub 会提示删除)。手册三令五申:请务必删除旧的或不用的分支。 仓库中的 .github/workflows/stale-branches.yml 正是这套纪律的自动化体现。

合并 PR 与里程碑

Mocha 倾向于对 PR 做 squash merge——要求贡献者为 rebase 保持整洁历史是过高的要求,团队认为不值得。PR 被接受后,必须为它指派一个里程碑(milestone)。

里程碑的使用规则:

  • 破坏性 PR:指派到与下一个 major 版本对应的新/现有里程碑。例如当前版本是 v6.5.2,则里程碑命名为 v7.0.0;
  • semver-minor PR:创建或使用与下一个 minor 版本对应的里程碑,如 v6.6.0;
  • 无法确定下一个里程碑:使用或创建名为 next 的里程碑,发布时再重命名为正式版本号。

通过里程碑机制,团队可以把非破坏性变更 cherry-pick 进 minor 或 patch 版本,同时保持 main 始终是最新版本。

发布流程:Release Please 自动化

Mocha 的发布由 Release Please 管理,测试通过后需要人工批准。合并变更后,要创建新版本,只需合并其自动化创建的 chore(main): release... PR 即可,这会:

  1. 创建新的 GitHub Release;
  2. 触发 main 上的 CI 任务,将包发布到 npm。

随后需要进入该 release commit 的 Publish to npm 任务运行日志,点击 Review pending deployments 链接完成发布审批。

仓库中的实际配置印证了这一点:

  • .github/release-please/config.json 声明 release-type: node,并定义了 CHANGELOG 的分区映射(feat → Features、fix → Fixes、docs → Documentation、chore/perf/refactor/test → Chores、build/ci → Automation),同时将 README 列为发布时同步更新的额外文件;
  • .github/release-please/manifest.json 记录当前版本 12.0.1;
  • .github/workflows/release-please.yml 在 main 分支的 push 上触发 Release Please 动作,并在版本发布后运行 npm 发布任务:根据版本号自动确定 dist-tag(含 -alpha 用 alpha,其他预发布用 next,正式版用 latest),以 npm publish --provenance --access public 带来源证明发布。

Major 版本的奇偶模式

对于 major 版本,Mocha 采用奇偶(even-odd)模式:

  • 偶数版本只更新依赖,避免破坏性功能变更;
  • 奇数版本可以更新依赖并引入破坏性功能变更。

这使得偶数版本通常很小、易于迁移,而奇数版本可以专注于功能变化。当前仓库的版本历史正是这一模式的体现:偶数版本 12.0.1 的变更集中在依赖升级、bug 修复与文档,CHANGELOG.md 中可见其明细。

Beta 与 RC 的推进

对于大型发布,建议按 beta → release candidate (RC) → 正式版 的顺序推进:Beta 阶段大多数功能已可用,但正式发布前还可能增加;RC 几乎可以发布,但正式发布前值得用户测试。

  • 启动新 major 的 beta:在 PR 的 commit message 最后一行(而非 PR 描述)的附加细节中加入 Release-As: 12.0.0-beta.1,Release Please 会尊重该属性并相应更新;也可以把 Release Please 设为预发布模式来自动递增 beta 号;
  • 过渡到 RC:在 commit message 末尾加入 Release-As: 12.0.0-rc.1;
  • 从 beta/RC 过渡到正式版:将 Release Please 的 prerelease 改回 false 即可。

重要提示:预发布标签与编号之间始终使用点号(.) 分隔,例如 beta.1 而不是 beta-1。npm 使用的 semver 库会把点号分隔的数字标识符按数值比较,因此 beta.10 > beta.9;而使用连字符时 beta-10 是单个字符串标识符,会按字母序排在 beta-9 之前。

OpenJS 基金会与 Open Collective

OpenJS Foundation 保有 mochajs 组织下所有项目的版权。基金会不干预技术决策或项目路线图,其职责是确保旗下项目的持续活力与可持续性。作为维护者,你可以使用基金会提供的各项资源。项目的治理与宪章细节可进一步查看 PROJECT_CHARTER.md。

Open Collective 方面,Mocha 通过 Open Collective 接收捐赠;作为维护者,你可以参与决定资金如何使用——这类决策同样遵循共识寻求流程。Open Collective 内置了支出透明度机制。

小结:这套流程能给你的项目带来什么

Mocha 的维护者手册本质上是一套把隐式协作规则显式化的工程实践:

  • 角色清晰化:用 User / Contributor / Maintainer 三档划分责任与权利,大幅降低新人的参与门槛(不写代码也能贡献);
  • 标签即协议:area:、status:、type:、semver-* 标签构成了 Issue 分流与 PR 定级的可执行协议,配以 GitHub Actions 自动化(见 .github/workflows);
  • 发布即自动化:Release Please + npm 发布工作流把「打标签 → 发 Release → 发 npm」变成一次 PR 合并,奇偶版本策略与 beta/RC 推进规范让破坏性变更可控可预期;
  • 人文底线:无论分流、评审还是处理冲突,礼貌、透明与「偏向用户」贯穿始终。

对于正在维护任何规模开源项目的读者,这些规范——尤其是 SemVer 标签三件套、status: 状态机与基于里程碑的版本规划——都是可以直接照搬的成熟模板。

有疑问?去 Mocha Discord 问吧——那是一个公开的、任何人都可以加入的社区。

登录后查看全文
mocha