Egg 开源框架代码贡献指南：从 Issue 到 PR 再到版本发布的完整协作规范-二趣网

Egg 开源框架代码贡献指南：从 Issue 到 PR 再到版本发布的完整协作规范

【免费下载链接】egg🥚 Born to build better enterprise frameworks and apps with Node.js & Koa项目地址: https://gitcode.com/gh_mirrors/egg11/egg

本指南以 Egg 框架官方仓库的 CONTRIBUTING.zh-CN.md 为骨架，系统梳理参与 Egg 开源协作的完整流程：如何提交高质量的 Issue、如何编写配套文档、如何通过 Pull Request 提交代码、如何遵循 Angular 风格的 Commit 规范，以及 Egg 团队的语义化版本发布与分支管理策略。读完本文，你将掌握一套可直接复用的开源项目协作方法论，并能对照仓库中的工程化设施（lint、测试、changelog 生成脚本）验证每一步规范的实际落地方式。

提交 Issue：让问题被高效定位与处理

在 CONTRIBUTING.zh-CN.md 中，Egg 团队对 Issue 提交提出了三条核心要求：

确定 Issue 的类型：在提交前想清楚这是功能诉求（feature）、缺陷（bug）、文档问题（documentation）、性能问题（performance），还是日常技术支持（support）。
避免重复 Issue：提交之前先搜索现有 Issue，确认没有相同或相似的问题被提出过。
明确表达意图：在标签、标题或者内容中体现出明确的意图。

提交之后，Egg 负责人会确认 Issue 的意图，为其更新合适的标签、关联 milestone（里程碑），并指派开发者处理。

标签体系：type 与 scope

Egg 的 Issue 标签分为两类：

类别	含义	示例
`type`	Issue 的类型	`feature`、`bug`、`documentation`、`performance`、`support`等
`scope`	修改文件的范围	`core: xx`、`plugin: xx`、`deps: xx`等

常用标签说明

标签	含义与处理优先级
`support`	需要开发者协作排查、咨询、调试等日常技术支持的问题
`bug`	疑似缺陷。打上`bug`后等待确认，一旦确认会再打上`confirmed`，并以非常高的优先级处理
`critical`	在`bug`已确认且正在影响线上应用正常运行时追加，代表最高优先级，需要立即处理
`core: xx`	与 core 内核相关，如`core: antx`表示与 antx 配置相关
`plugin: xx`	与插件相关，如`plugin: session`表示与 session 插件相关
`deps: xx`	与 dependencies 模块相关，如`deps: egg-cors`表示与 egg-cors 模块相关
`chore: documentation`	发现文档相关问题，需要修复文档
`cbd`	与服务器部署相关（中英文档不一致，中文版特有标签）

值得注意的细节：bug 的修复版本也会反映在标签上。例如某个 bug 需要在0.9.x修复，而当前最新版本是1.1.x，那么该 Issue 还会被打上0.9、0.10、1.0、1.1，明确指示出需要修复到的所有版本。这种"版本矩阵"标签让维护者在发版时能一眼看到每个版本还需要合入哪些修复。

编写文档：所有功能点必须配套文档

Egg 团队对文档有硬性要求：所有功能点必须提交配套文档。文档需要满足：

说清楚问题的几个方面：what（是什么）、why（为什么）、how（怎么做），可根据问题特性有所侧重。
how 部分必须包含详尽完整的操作步骤，必要时附上足够简单、可运行的范例代码。
提供必要的链接，如申请流程、术语解释和参考文档。
同步修改中英文文档，或者在 PR 里面说明。

这一要求与仓库的文档体系高度一致。仓库的文档源文件位于 docs/source，同时维护了en与zh-cn两套语言目录（docs/source/en 与 docs/source/zh-cn），覆盖 basics（基础）、core（核心）、advanced（进阶）、tutorials（教程）等主题。新增功能时，开发者需要保证两套文档同步更新，这正是"同步修改中英文文档"规范的具体落地。

提交代码：从分支到 Pull Request

如果你拥有 egg 仓库的开发者权限并希望贡献代码，可以创建分支修改代码后提交 PR，egg 开发团队会 review 代码并合并到主干。官方推荐的完整流程如下：

# 先创建开发分支开发，分支名应该有含义，避免使用 update、tmp 之类的 $ git checkout -b branch-name # 开发完成后跑下测试是否通过，必要时需要新增或修改测试用例 $ npm test # 测试通过后，提交代码，message 见下面的规范 $ git add . # git add -u 删除文件 $ git commit -m "fix(role): role.use must xxx" $ git push origin branch-name

提交后即可创建 Pull Request。

PR 信息四要素

由于谁也无法保证过了多久之后还记得多少，为了后期回溯历史方便，提交 PR 时必须提供以下四类信息：

需求点：一般关联 Issue 或者注释都算；
升级原因：不同于 Issue，可以简要描述为什么要处理；
框架测试点：可以关联到测试文件，不用详细描述，关键点即可；
关注点：针对用户而言，可以没有，一般是不兼容更新等需要额外提示的内容。

代码风格：必须通过 eslint

你的代码风格必须通过 eslint，可以运行npm run lint在本地测试。仓库中这一规范的落地情况可以直接查看：

.eslintrc 继承eslint-config-egg规则集，并指定ecmaVersion: 2017；
package.json 的 scripts 中定义了"lint": "eslint app config lib test *.js"，即对app、config、lib、test目录及根目录下所有 JS 文件执行检查；
完整的测试脚本链路为"test": "npm run lint -- --fix && egg-bin pkgfiles && npm run test-local"，其中test-local调用egg-bin test运行测试。

也就是说，npm test会自动先执行 lint（并尝试--fix自动修复），再检查发布文件清单，最后跑测试，一条命令即可完成贡献前检查。

Commit 提交规范：基于 Angular 规范的 Commit Message

Egg 采用 [Angular 规范]风格的 Commit Message，这样 history 看起来更加清晰，还可以自动生成 changelog。标准格式如下：

<type>(<scope>): <subject> <BLANK LINE> <body> <BLANK LINE> <footer>

（1）type：提交类型

type	含义
`feat`	新功能
`fix`	修复问题
`docs`	修改文档
`style`	修改代码格式，不影响代码逻辑
`refactor`	重构代码，理论上不影响现有功能
`perf`	提升性能
`test`	增加或修改测试用例
`chore`	修改工具相关（包括但不限于文档、代码生成等）
`deps`	升级依赖

（2）scope：修改范围

scope 表示修改文件的范围，包括但不限于doc、middleware、core、config、plugin。

（3）subject：一句话描述

用一句话清楚地描述这次提交做了什么。

（4）body：补充说明

补充 subject，适当增加原因、目的等相关因素，也可不写。

（5）footer：收尾信息

当有非兼容修改（Breaking Change）时必须在 footer 中描述清楚；
关联相关 issue，如Closes #1, Closes #2, #3；
如果功能点有新增或修改，还需要关联doc和egg-init的 PR，如eggjs/egg-bin#123。

完整示例

fix($compile): [BREAKING_CHANGE] couple of unit tests for IE9 Older IEs serialize html uppercased, but IE9 does not... Would be better to expect case insensitive, unfortunately jasmine does not allow to user regexps for throw expectations. Document change on eggjs/egg#123 Closes #392 BREAKING CHANGE: Breaks foo.bar api, foo.baz should be used instead

该示例展示了规范的完整形态：type(scope): subject作为首行，空行后是 body（说明问题的来龙去脉），再空行后是 footer（包含关联 IssueCloses #392与BREAKING CHANGE声明）。其中[BREAKING_CHANGE]在 subject 中的出现也提醒我们：破坏性变更需要在标题层尽早暴露。

发布管理：语义化版本与分支策略

egg 基于 [semver]（语义化版本号）进行发布。

分支策略

master分支为当前稳定发布的版本，next分支为下一个开发中的大版本。核心约定：

只维护两个版本：除非有安全问题，否则修复只会 patch 到master和next分支，其他更新推动上层框架升级到稳定大版本的最新版本；
API 废弃需提前 deprecate：所有 API 的废弃都需要在当前稳定版本上给出deprecate提示，并保证在稳定版本上一直兼容到新版本发布；
master 不设置 publish tag：上层框架基于 semver 依赖稳定版本；
next 设置 tag 为next：上层框架可以通过egg@next引用开发中的版本进行测试；
持续维护的版本以 Milestone 为准：只要是开着的版本都会进行修复。

发布策略

每个大版本都有一个发布经理（PM）管理，PM 在不同阶段承担如下职责。

准备工作

建立 milestone，确认需求关联 milestone，指派和更新 issues；
从master分支新建next分支，并设置 tag 为next。

发布前

确认当前 Milestone 所有的 issue 都已关闭或可延期，并完成性能测试；
发起一个新的 Release Proposal MR，按照 node CHANGELOG 的风格编写History，修正文档中与版本相关的内容，commits 可以自动生成：

$ npm run commits

指定下一个大版本的 PM。

发布时

将老的稳定版本（master）备份到以当前大版本为名字的分支上（例如1.x），并设置 tag 为release-{v}.x（v 为当前版本，例如release-1.x）；
将next分支推送到master，成为新的稳定版本分支，并去除nexttag，修改 README 中与分支相关的内容；
发布新的稳定版本到 npm，并通知上层框架进行更新。

npm tag 的设置方式

上述描述中所有"设置 tag"都指在package.json中设置 npm 的 tag：

"publishConfig": { "tag": "next" }

当前仓库的 package.json 中实际配置为"publishConfig": { "tag": "latest-1" }，即 1.x 稳定线以latest-1作为默认发布 tag，与文档所述"master 分支不设置额外 next tag、稳定版本走 semver"的策略一致。

仓库中的配套工程化设施

贡献规范并非停留在纸面，仓库中有完整的工程化设施与之对应：

Changelog 生成：scripts/commits.sh 实现了npm run commits。它读取git config中的 remote origin 地址、通过git describe --tags找到最近一个 tag、用git show -s获取该 tag 的日期，然后以[commit-hash] - subject (author <email>)的格式输出该日期以来的所有非 merge 提交——这正是"commits 可以自动生成"的实现原理。
History 维护：History.md 记录了每个版本的 Notable changes 与对应 commits 列表，例如1.21.0版本记录了 "feat: egg 1.x support cookies config init"，版本标题形如2019-10-28, Version 1.20.0 @dead-horse（日期、版本、发布经理），与"按照 node CHANGELOG 编写 History"的规范吻合。
测试基础设施：仓库测试统一使用egg-mock启动 fixture 应用，见 test/utils.js，其中exports.app/exports.cluster分别用于单进程与 cluster 模式的测试启动，customEgg指向仓库根目录。新增功能时，建议参照 test 目录下按模块组织的测试用例（如 test/lib/core、test/app）编写对应测试，这与 PR 信息四要素中"框架测试点"的要求相互呼应。
文档站点构建：仓库的 docs/source 维护中英文双语文档源，结合 docs/_config.yml 与 docs/source/_data/menu.yml 等导航配置，通过npm run doc-build（doctools build）生成站点，是"功能点必须配套文档"规范在仓库中的实物体现。

小结

Egg 的贡献规范可以浓缩为一条完整链路：用规范的 Issue + 标签把问题讲清楚 → 用 what/why/how 的文档把功能讲明白 → 用带含义的分支 + 通过 eslint 与测试的代码把功能做出来 → 用 Angular 风格的 Commit 与四要素 PR 把改动说清楚 → 由 PM 按 semver 与 master/next 分支策略完成发布。这套规范不仅适用于 Egg 框架本身，也是一份值得任何 Node.js 开源项目借鉴的团队协作模板。

如果你正准备为 Egg 提交第一个 Issue 或 PR，不妨按本文的清单逐项自检：Issue 是否重复、标签是否准确、文档是否中英文同步、代码是否通过npm run lint、Commit 是否符合<type>(<scope>): <subject>格式、PR 是否包含需求点/升级原因/测试点/关注点四项信息。规范的流程，是开源协作效率与代码质量的共同保障。

【免费下载链接】egg🥚 Born to build better enterprise frameworks and apps with Node.js & Koa项目地址: https://gitcode.com/gh_mirrors/egg11/egg

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析