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 与 scopeEgg 的 Issue 标签分为两类类别含义示例typeIssue 的类型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 仓库的开发者权限并希望贡献代码可以创建分支修改代码后提交 PRegg 开发团队会 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: 2017package.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 MessageEgg 采用 [Angular 规范]风格的 Commit Message这样 history 看起来更加清晰还可以自动生成 changelog。标准格式如下type(scope): subject BLANK LINE body BLANK LINE footer1type提交类型type含义feat新功能fix修复问题docs修改文档style修改代码格式不影响代码逻辑refactor重构代码理论上不影响现有功能perf提升性能test增加或修改测试用例chore修改工具相关包括但不限于文档、代码生成等deps升级依赖2scope修改范围scope 表示修改文件的范围包括但不限于doc、middleware、core、config、plugin。3subject一句话描述用一句话清楚地描述这次提交做了什么。4body补充说明补充 subject适当增加原因、目的等相关因素也可不写。5footer收尾信息当有非兼容修改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上层框架可以通过eggnext引用开发中的版本进行测试持续维护的版本以 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}.xv 为当前版本例如release-1.x将next分支推送到master成为新的稳定版本分支并去除nexttag修改 README 中与分支相关的内容发布新的稳定版本到 npm并通知上层框架进行更新。npm tag 的设置方式上述描述中所有设置 tag都指在package.json中设置 npm 的 tagpublishConfig: { 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-builddoctools 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），仅供参考