EMQX 开源仓库贡献指南分支同步链、Conventional Commit 规范与 Changelog 工程实践【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx本文以 CONTRIBUTING.md 为骨架结合 EMQX 仓库中真实的脚本如 scripts/check-changes-filename-pattern.sh、scripts/ff-release-from-dev.sh与changes/目录的既有产物系统讲解向 EMQX 提交代码时必须遵守的三件事往哪个分支提 PR、如何书写规范的 commit message、以及如何登记 changelog。读完本文你将能准确判断 PR 的目标分支写出符合仓库要求的提交信息并为自己的改动添加一条能通过 CI 校验的变更记录。一、先了解仓库EMQX 的提交入口EMQX 是一个以 Erlang/Elixir 为主实现的高性能 MQTT 消息服务器仓库根目录采用 monorepo 结构核心业务代码集中在apps/目录下例如apps/emqx、apps/emqx_auth、apps/emqx_bridge_kafka等发布相关脚本位于scripts/版本演进记录位于changes/。向这样一个多版本并行维护的仓库提交代码分支策略与提交规范是合入的第一步关卡。本仓库欢迎任何形式的 Bug 报告、Issue 与功能请求feature request。在动手提交代码之前建议先通读本指南重点理解以下三个环节分支目标选择——决定你的改动最终进入哪些发布线release line提交信息格式——决定你的提交在git log与自动化工具中的可读性Changelog 登记——决定你的改动是否会被收录进官方版本变更记录。二、分支策略选择正确的目标分支2.1 dev-XX 分支与正向同步链forward-sync chainEMQX 同时维护多条dev-XX分支每条对应一个仍在支持的发布线例如dev-58、dev-60、dev-63。这些分支之间存在一条自动正向同步链一个改动合入较早的分支后会通过同步机制自动传递到链条上的每一个后续分支无需为每条分支分别提交 PR。从仓库脚本 scripts/rel-versions 可以确认当前 6.x 系列的同步链形态dev-60 - dev-61 - dev-62 - dev-63 - dev-70该脚本注释明确指出The 6.x line ends at dev-63; there is no 6.4 release, so dev-63 syncs forward into dev-706.x 线止步于 dev-63由于不存在 6.4 版本dev-63 继续向前同步到 dev-70。这说明同步链可以跨大版本延续。该脚本还说明了链上各分支与发布线的关系release-XX分支会从对应的dev-XX分支自动快进见 2.3 节因此合入 dev 分支的改动最终会到达该发布线的发布分支。2.2 目标分支的选择规则优先选择改动影响的最早的仍活跃dev-XX分支尤其是高严重级别high-severity的修复。因为同步链是单向向前的只有合入最早的受影响分支修复才能经由链条覆盖所有下游发布线。如果不确定哪条分支最早或仍活跃直接瞄准最新的dev-XX分支即可。此时应在 PR 描述中说明这一情况并请求维护者指引评审过程中维护者可以视情况将 PR 重定向到更早的分支。切勿针对多条dev-XX分支提交重复 PR。同步链本身会向前传播改动重复 PR 只会造成重复评审工作量且若未同时合入还会导致内容分叉diverge。绝不直接向release-XX分支提交 PR。这些分支由对应的dev-XX分支自动快进而来不接受直接推送。2.3 发布分支的快进机制源码佐证release-XX不接受直接推送这一规则在脚本 scripts/ff-release-from-dev.sh 中有完整的落地实现。该脚本用于将release-XX快进fast-forward到dev-XX核心逻辑是VERSION$1 DEV_BRANCHdev-${VERSION} RELEASE_BRANCHrelease-${VERSION} # 若两者 SHA 相同则无事可做 if [ ${DEV_SHA} ${REL_SHA} ]; then exit 0 fi # git push 不带 --force本质上就是仅快进操作 git push origin ${DEV_SHA}:refs/heads/${RELEASE_BRANCH}脚本刻意依赖git push不带--force天然拒绝非快进更新的特性来保证release-XX始终是dev-XX的祖先当出现分叉时会在 CI 环境变量中写入NOT_FAST_FORWARD1并报错。这一设计从工程层面印证了 CONTRIBUTING.md 中release 分支仅由 dev 分支快进、不接受直接推送的约束。三、Commit Message 规范仓库对 commit message 有非常精确的格式要求目的是让项目历史更易阅读、更易被 git 工具与自动化流程消费。3.1 整体格式每条提交信息由header、body与footer三部分组成header 内部又分为type、scope与subjecttype(scope): subject BLANK LINE body BLANK LINE footerheader含 type是必填项header 中的scope 为可选项本仓库没有预定义 scope 列表允许按需自定义 scope 以提升可读性每行长度不得超过 100 个字符以保证在 GitHub 界面和各种 git 工具中都能被完整阅读footer 中如有关联的 Issue应写入关闭引用closing reference例如Closes: #123。3.2 完整示例示例 1仅含 header 的最小提交feat: add Fuji release compose files示例 2带 scope、body 与 footer 的完整提交fix(script): correct run script to use the right ports Previously device services used wrong port numbers. This commit fixes the port numbers to use the latest port numbers. Closes: #123, #245, #992可以看到body 中先用一句话说明之前的错误行为再说明本次提交做了什么——这正是规范要求的说明动机并与旧行为做对比。3.3 字段细则Revert回滚提交如果提交是对某次历史提交的回滚必须以revert:开头随后跟被回滚提交的 header并在 body 中写明This reverts commit hash.hash 为被回滚提交的 SHA。Type必填必须是以下枚举值之一Type含义feat面向用户的新功能而非面向构建脚本的新功能fix面向用户的缺陷修复而非对构建脚本的修复docs仅文档变更style格式、缺失分号等不涉及生产代码变更refactor生产代码重构如变量重命名chore更新构建任务等不涉及生产代码变更perf提升性能的代码变更test补充缺失的测试或重构测试不涉及生产代码变更build影响 CI/CD 流水线、构建系统或外部依赖的变更示例 scopejenkins、makefileciDevOps 为 CI 目的提供的变更revert回滚某次之前的提交Scope可选本仓库没有预定义 scope可自定义以增强清晰度例如示例中的fix(script):。Subject必填对变更的简洁描述要求使用祈使句、现在时写change不写changed或changes首字母不大写结尾不加句号.。Body可选与 subject 相同使用祈使句、现在时应包含变更动机并与旧行为进行对比。Footer可选承载两类信息Breaking Changes必须以BREAKING CHANGE:开头后跟一个空格或两个换行其余部分描述破坏性变更的具体内容Issue 关闭引用Closes: #xxx可一次引用多个 Issue。四、Changelog 登记规范影响 EMQX 功能行为的变更必须在changes目录下以独立 markdown 文件描述。这一要求不仅是文档约定仓库中还提供了 CI 脚本强制校验文件名模式。4.1 文件命名模式changes/ee/(feat|fix|perf|breaking)-PR-id.en.md各字段含义feat | fix | perf | breaking变更类型——新功能feat、缺陷修复fix、性能改进perf或破坏性变更breakingPR-idGitHub PR 编号。由于 PR 创建前无法预知编号常见的做法是在单独的提交中补充 changelog 条目即 PR 合入后补一条enISO 639-1 语言代码表示该 changelog 条目的语言。目前仓库只接受英文条目。4.2 仓库内的真实产物印证打开 changes/ee 目录可以看到大量符合该模式的实际文件例如feat-14040.en.md、feat-14479.en.md新功能fix-xxx.en.md修复perf-xxx.en.md性能改进breaking-14765.en.md、breaking-14865.en.md破坏性变更以feat-14040.en.md为例其内容是一句紧凑的英文描述Added timeouts to the internal RPC calls during node rebalance. Previously, the rebalance process could hang if a node was unresponsive.为节点再平衡期间的内部 RPC 调用添加超时此前若节点无响应再平衡过程可能挂起。可见条目要求非常紧凑同时保留动机 旧行为对比的表述结构。4.3 CI 强制校验源码佐证脚本 scripts/check-changes-filename-pattern.sh 在 CI 中执行通过git diff --diff-filterA找出新增文件并对以fix-、feat-、perf-开头的文件强制匹配以下模式否则直接报错退出^changes/ee/(fix|feat|perf)-[0-9]\.en\.md$也就是说如果你的 changelog 文件放错了目录如changes/ce/、类型前缀不在枚举内、PR 编号不是纯数字或语言后缀不是.en.mdCI 都会拦截。CONTRIBUTING.md 中给出的模式是(feat|fix|perf|breaking)四种前缀而 CI 脚本只校验fix|feat|perf三种——breaking条目同样存在于仓库中如breaking-14765.en.md说明breaking是约定中的合法前缀但 CI 正则对未以这三类前缀开头的文件不强制。4.4 Changelog 的自动化生成源码佐证仓库还提供了半自动化的 changelog 生成脚本 scripts/generate-changelog.sh输入PR 编号命令行参数或环境变量GITHUB_PULL_REQUEST_NUMBER流程从远端拉取 PR 的 base 与 head SHA计算 diff调用 OpenAI 或 Gemini API 将 diff 分类为feat/fix/perf并生成两句以内的紧凑摘要随后按changes/ee/${PREFIX}-${PR_NUMBER}.en.md写入文件在 GitHub Actions 环境下脚本还会自动提交该文件并推回 PR 分支。由此可以看出changelog 文件的类型前缀feat/fix/perf与 commit message 的 type 语义保持一致整条工程链路提交 → PR → changelog → 版本记录是打通的。而changes/目录下的版本文件如 changes/6.3.1.en.md、changes/e5.9.1.en.md则汇集了这些条目构成每个版本对外发布的变更说明。五、实操速查一次规范提交的完整流程综合以上规则向 EMQX 提交一次合规改动的推荐流程如下定位基线分支确认改动影响的最早dev-XX分支不确定就选最新的dev-XX并在 PR 描述中说明创建分支并开发基于目标 dev 分支切出特性分支提交按type(scope): subject编写 header必要时补充 body 与 footer整行不超过 100 字符需要回滚时以revert:开头并注明This reverts commit hash.登记 changelog若改动影响 EMQX 功能在changes/ee/下新建prefix-PR-id.en.mdprefix ∈ feat/fix/perf/breaking写一句紧凑的英文描述PR 编号未知时可稍后补提交发起 PR目标分支选 dev 分支而非 release 分支不要对多条 dev 分支重复开 PR等 CI含check-changes-filename-pattern.sh通过。六、常见问题FAQQ1我的修复同时影响 5.8 与 6.x该往哪条分支提交答向受影响的最早的仍活跃dev-XX分支提交例如dev-58同步链会把它自动带到后续所有分支切勿分别向多条 dev 分支开 PR。Q2不确定 scope 该怎么写答scope 是可选项且无预定义列表可以不写或使用能准确描述改动范围的短语如fix(script):。Q3changelog 文件里的 PR 编号还没确定怎么办答按规范在 PR 创建后的单独提交中补充文件名里的 PR-id 以实际 PR 编号为准CI 会校验文件必须位于changes/ee/且格式为{fix|feat|perf}-数字.en.md。Q4破坏性变更如何标记答在 commit 的 footer 中以BREAKING CHANGE:开头描述破坏性内容同时按需在changes/ee/下添加breaking-PR-id.en.md条目。Q5我的提交只改了文档需要 changelog 吗答changelog 针对影响 EMQX 功能行为的变更仅文档类改动使用docs:类型的提交即可通常无需 changelog 条目。七、延伸阅读分支同步链与版本推算scripts/rel-versions发布分支快进机制scripts/ff-release-from-dev.shChangelog 文件名 CI 校验scripts/check-changes-filename-pattern.shChangelog 自动化生成scripts/generate-changelog.sh变更记录存放目录changes/ee仓库主 READMEREADME.md【免费下载链接】emqxThe most scalable and reliable MQTT broker for AI, IoT, IIoT and connected vehicles项目地址: https://gitcode.com/gh_mirrors/em/emqx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考