Midway 开源仓库协作指南：Issue 规范、Commit 约束与版本发布全流程解析-创锋一号

后端
微服务
云原生

【免费下载链接】midway

🍔 A Node.js Serverless Framework for front-end/full-stack developers. Build the application for next decade. Works on AWS, Alibaba Cloud, Tencent Cloud and traditional VM/Container. Super easy integrate with React and Vue. 🌈

项目地址：https://gitcode.com/gh_mirrors/mi/midway

点击查看免费下载

导读

本文围绕 CONTRIBUTING.md 展开，系统讲解 Midway（一个面向全栈开发者、基于 IoC 容器的 Node.js 服务端框架）开源仓库的协作规范，覆盖 Issue 报告与标签体系、PR 提交流程、Commit Message 格式、分支策略与语义化版本发布机制。读完本文，你将掌握一套可直接复用的开源协作实操流程，并能对照仓库中的 package.json、lerna.json、scripts/publish.sh 等真实文件理解其底层执行逻辑。

一、协作入口：Issue 报告规范

Midway 仓库要求所有问题（Bug、功能建议、疑问等）通过 Issue 提交，并在提交前遵循以下三条基本原则：

明确问题类型：在标题、标签或正文中说明这是哪一种 Issue；
先搜索再提问：提交前先在已有 Issue 中检索，避免创建重复问题；
善用标签表达意图：使用下文介绍的「有用标签（Useful Tags）」来标清问题目的。

Issue 被提交后，MidwayJs 核心组成员会确认其目的、替换更准确的标签、关联对应的 Milestone（里程碑），并指派开发者处理。标签体系分为两组：

type（类型）：描述 Issue 属于哪一类问题，例如feature、bug、documentation、performance、support；
scope（范围）：描述改动涉及哪个模块或哪些文件，例如core: xx、plugin: xx、deps: xx。

常用标签速查表

标签	含义与使用场景
`support`	需要框架开发者协助定位问题，或希望改进框架本身，均可打此标签
`bug`	疑似缺陷。组成员复核确认为 Bug 后，会补充`confirmed`标签
`confirmed`	已被核心组确认的真实 Bug，会优先排期修复
`critical`	对线上运行的应用程序有负面影响的高优先级 Bug，将立即修复
`core: xx`	与框架核心相关的 Issue，例如`core: loader`表示与 loader 配置有关
`plugin: xx`	与插件相关的 Issue，例如`plugin: session`表示与 session 插件有关
`deps: xx`	与依赖相关的 Issue，例如`deps: egg-cors`
`chore: documentation`	文档类 Issue，需要修改文档

Bug 的修复版本也通过标签标注：一个 Bug 需要从某个最低版本起修复，例如需要从 0.9.x 修复，则打上0.9、0.10、1.0、1.1等标签，明确各版本分支的修复义务。

二、文档要求：功能必须附带说明

Midway 的协作规范有一条硬性要求：所有功能变更必须同时提交文档。文档需要满足：

根据功能性质，阐明其一个或多个方面：是什么（what）、为什么会发生（why）、如何工作（how）；
尽量包含一系列操作步骤来说明如何复现、排查或解决问题；
鼓励提供简单但自解释的示例（demo），所有示例统一汇总到独立的 examples 仓库维护；
提供必要的参考链接，如应用流程、术语解释和引用资料。

这与仓库 AGENTS.md 中的文档规则一脉相承：当前文档位于site/docs（Docusaurus 站点），要求组件文档面向初学者，遵循「先讲解决什么问题、何时使用、最简单可用路径，再深入高级用法、配置与扩展点」的渐进式结构，而非纯 API 罗列。这正是本项目文档协作的实践基调。

三、提交代码：Pull Request 全流程

3.1 分支开发与提交

如果你是仓库开发者并愿意贡献代码，请遵循以下命令流程：

# 创建新分支开发。分支名要有语义，避免 update、tmp 这类无意义词。 # 如果是实现新功能，建议使用 feature/xxx 命名。 $ git checkout -b branch-name # 完成修改后运行测试。必要时新增测试用例或调整旧用例。 $ npm test # 测试通过后即可推送。注意提交信息需遵循规范格式。 $ git add . # 使用 git add -u 可删除文件 $ git commit -m "fix(role): role.use must xxx" $ git push origin branch-name

在当前仓库中，npm test的实际执行是lerna run test（见 package.json），即通过 Lerna 在 monorepo 下并行运行所有子包的测试；如需单独验证某个包，仓库规范建议使用pnpm -C <package> test限定作用域（见 AGENTS.md）。

3.2 PR 中必须提供的信息

没有人能保证一段时间后还记得某个 PR 的细节。为了让团队能快速复盘，每个 PR 必须附带以下四类信息：

Need（需求）：想实现什么功能，一般要指明关联的 Issue；
Updating Reason（更新理由）：与 Issue 不同，这里简要说明为什么需要做这个修改，以及背后的逻辑；
Related Testing（相关测试）：简述修改涉及哪部分测试；
User Tips（用户提示）：如果 PR 涉及 API 变更或潜在兼容性问题，必须给使用者注意事项；纯内部改动可省略此项。

3.3 风格约束：通过 ESLint 校验

代码风格统一由 ESLint 把关，修改后的代码必须通过 lint 检查，本地执行：

$ npm run lint

当前仓库的实际命令为lerna exec --ignore @midwayjs/version -- mwts check，即基于 mwts 基于mwts/eslint.config.js扩展而来，并针对.ts/.tsx文件接入 TypeScript 项目配置（parserOptions.project），同时为 Jest 测试文件注入全局变量，还关闭了no-namespace、no-wrapper-object-types等对框架代码不友好的规则。若需要自动修复，可运行npm run lint:fix（对应mwts fix）。

四、Commit Message 规范：Angular 格式

仓库推荐使用Angular commit-message-format编写提交信息，目的是获得可追踪的历史和自动生成的 CHANGELOG。规范模板如下：

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

（1）type（类型，必选）

必须是下列取值之一：

feat：新功能
fix：Bug 修复
docs：仅文档变更
style：不影响代码含义的改动（空白、格式、缺失分号等）
refactor：既非修 Bug 也非加功能的代码重构
perf：性能提升
test：补充缺失的测试
chore：构建过程或辅助工具、库的变更（如文档生成）
deps：依赖更新

（2）scope（范围，可选）

可以是任何能指明改动位置的标识，如$location、$browser、$compile等。结合本仓库，常见的 scope 例如core、web、plugin: session等。

（3）subject（主题）

用简洁的语言描述这次提交做了什么。

（4）body（正文）

如果 subject 不足以自解释，可在正文补充目的或原因等更多内容。

（5）footer（页脚）

如果是 Breaking Change，必须在此部分明确标注；
关联 Issue，如Closes #1, Closes #2, #3；
若涉及旧功能或新功能的变更，请关联doc与midway-init，如midwayjs/midway-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 midwayjs/midway#123 Closes #392 BREAKING CHANGE: Breaks foo.bar api, foo.baz should be used instead

这套格式在仓库中已被严格执行：AGENTS.md 明确要求 PR 标题必须使用标准提交格式（如feat: xxx、fix: xxx）；lerna.json 的changelog.labels配置也将pr: breaking change、pr: new feature、pr: bug fix等标签映射为 CHANGELOG 中的分类条目，说明 PR 标签与提交信息共同驱动变更日志的生成。

五、Release：语义化版本与分支策略

5.1 分支策略

Midway 基于semver（语义化版本）进行发布：

master分支是最新稳定版；next分支是开发中的下一个稳定版；
所有新功能与 Bug 修复都会进入master或next分支（安全问题除外），以此激励开发者升级到最新稳定版；
若有 API 被废弃，需在当前稳定版中标注deprecate，旧版 API 应保持兼容直到下一个稳定版发布；
master分支不带发布 tag，上层框架可按语义化版本与稳定版协作；
next分支打nexttag，上层框架可通过midway@next试用开发中的版本；
由 Milestone 决定LTS 版本：凡列入 Milestone 的版本即为 LTS，出现问题会持续打补丁。

5.2 发布策略与 PM 职责

每个稳定版发布会指定一名 PM（发布经理），分阶段负责：

准备阶段

建立 Milestone，确认 Issue 与 Milestone 关联，指派并更新 Issue；
从master创建next分支并打nexttag。

发布前

确认性能测试通过，当前 Milestone 内的所有 Issue 已关闭或可推迟到后续版本；
打开 Release Proposal MR，撰写History（参考 Node.js 的 CHANGELOG 写法），并同步修正文档中与该版本相关的内容。提交可自动生成：

$ npm run commits

提名下一稳定版的 PM。

发布中

所有上述 tag 都指在package.json中为 npm 添加的 tag：

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

5.3 仓库中的发布实现

在真实仓库中，发布流程由 scripts/publish.sh 与 package.json 中的脚本承接，可直接对照理解：

npm run release执行sh scripts/publish.sh：先构建（build.sh）并生成 skill-midway 产物，随后lerna version统一提升版本，lerna publish from-git发布所有变更包，最后调用 scripts/create_github_release.js 从 CHANGELOG.md 中截取当前版本章节，通过 GitHub API 创建或更新 Release（需要环境变量GITHUB_AUTH或GITHUB_TOKEN）；
npm run beta/npm run next/npm run canary分别对应sh scripts/publish.sh beta|next|canary：beta 使用--dist-tag beta全量强制发布，next 使用--dist-tag next，canary 则先提升 major 版本再以--canary --preid alpha --dist-tag alpha发布预发布版本——这正是上文「next分支打nexttag」策略的落地实现；
版本号本身由 lerna.json 维护（当前为4.2.3），lerna 的publish.ignoreChanges配置确保纯文档、测试、站点等改动不会触发不必要的包发布。

5.4 版本记录与回滚机制

发布过程中，scripts/generate_version.js 会执行lerna ls --json汇总所有子包版本，写入packages/version/versions/{decorator核心版本}-{core核心版本}.json并去重追加多版本记录，同时更新 packages/version/index.js 的时间戳与核心版本快照；scripts/generate_changelog.js 则调用npx lerna-changelog --nextVersion生成当前版本的变更日志并插入 CHANGELOG.md 顶部。此外，scripts/generate_rollback.js 会对比本地与 npm 上已发布版本的差异，为每个新版本生成回滚脚本（存放在 scripts/rollback 目录），便于发布异常时快速将latesttag 恢复至上一版本——这套「版本快照 + 自动 CHANGELOG + 一键回滚」的组合，构成了 Midway 发布链路的完整闭环。

六、协作规范的仓库佐证小结

规范章节	仓库中的对应实现
Issue 标签体系	lerna.json 的`changelog.labels`映射（pr: 系列标签）
测试要求	package.json 的`test`脚本（`lerna run test`）与 AGENTS.md 的组件测试要求
Lint 约束	package.json 的`lint`/`lint:fix`脚本与 eslint.config.js 的 mwts 配置
Commit 格式	AGENTS.md 对 PR 标题格式的硬性要求
分支与 tag 策略	scripts/publish.sh 中 beta/next/canary 的`--dist-tag`实现
版本与 CHANGELOG	scripts/generate_version.js、scripts/generate_changelog.js、scripts/generate_rollback.js

这套从 Issue 报告、PR 提交、Commit 规范到版本发布的完整协作链路，既保证了 Midway 这个大型 monorepo 在众多贡献者协作下的代码质量与历史可追溯性，也让自动化工具链（Lerna、CHANGELOG、版本快照）能够稳定运转。对于希望向 Midway 贡献代码的开发者而言，遵循本指南即可快速融入其协作节奏。

后端
微服务
云原生

【免费下载链接】midway

项目地址：https://gitcode.com/gh_mirrors/mi/midway

点击查看免费下载

企业官网建设流程全解析

【免费下载链接】midway

导读

一、协作入口：Issue 报告规范

常用标签速查表

二、文档要求：功能必须附带说明

三、提交代码：Pull Request 全流程

3.1 分支开发与提交

3.2 PR 中必须提供的信息

3.3 风格约束：通过 ESLint 校验

四、Commit Message 规范：Angular 格式

（1）type（类型，必选）

（2）scope（范围，可选）

（3）subject（主题）

（4）body（正文）

（5）footer（页脚）

完整示例

五、Release：语义化版本与分支策略

5.1 分支策略

5.2 发布策略与 PM 职责

5.3 仓库中的发布实现

5.4 版本记录与回滚机制

六、协作规范的仓库佐证小结

【免费下载链接】midway

相关推荐

MoviePilot 协作与发布规范：Commit 约定、分支策略、版本管理与 CI/CD 发布流程全解析

Rayburst 工程协作指南：从架构约束到发布流程的 Agent 开发规范全解析

TensorBoardX 仓库工程规范实战指南：发布流程、版本管理、环境约束与本地测试

热门文章

文章分类

标签云

需要专业的网站建设服务？

企业官网建设流程全解析

【免费下载链接】midway

导读

一、协作入口：Issue 报告规范

常用标签速查表

二、文档要求：功能必须附带说明

三、提交代码：Pull Request 全流程

3.1 分支开发与提交

3.2 PR 中必须提供的信息

3.3 风格约束：通过 ESLint 校验

四、Commit Message 规范：Angular 格式

（1）type（类型，必选）

（2）scope（范围，可选）

（3）subject（主题）

（4）body（正文）

（5）footer（页脚）

完整示例

五、Release：语义化版本与分支策略

5.1 分支策略

5.2 发布策略与 PM 职责

5.3 仓库中的发布实现

5.4 版本记录与回滚机制

六、协作规范的仓库佐证小结

【免费下载链接】midway

相关推荐

MoviePilot 协作与发布规范：Commit 约定、分支策略、版本管理与 CI/CD 发布流程全解析

Rayburst 工程协作指南：从架构约束到发布流程的 Agent 开发规范全解析

TensorBoardX 仓库工程规范实战指南：发布流程、版本管理、环境约束与本地测试

热门文章

文章分类

标签云

相关文章

线上 APM 崩溃与卡顿指标上报与实时大盘监控

云基础设施网络降本：VPC 跨可用区流量削减与内网直通实战

多规格体检心电图与超声报告 OCR 结构化 Prompt：从波形描述中提取关键结论

需要专业的网站建设服务？