QMK 固件 Breaking Changes 机制详解三月的 develop 合并周期、关键日期与完整操作清单【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware本文以 QMK 固件qmk_firmware仓库中的 Breaking Changes 文档 为主体完整讲解 QMK 的破坏性变更Breaking Change流程什么是破坏性变更、develop与master双分支的三月合并节奏、每期变更的准入标准与 ChangeLog 要求以及合并前后维护者使用的分阶段 Git 操作清单与 Discord 事件排期模板。读完本文你可以准确判断某项改动是否需要走 Breaking Changes 周期、知道如何在窗口期内提交自己的 PR并能复述维护者在合并日执行的每一步分支操作。什么是 Breaking Change按 docs/breaking_changes.md 的定义任何以不兼容或潜在危险的方式改变 QMK 行为的改动都属于 Breaking Change。QMK 刻意限制这类改动以便用户有信心更新 QMK 代码树不会弄坏自己的 keymap。需要特别注意的是范围界定仓库内键盘的目录迁移keyboard moves同样被计入 Breaking Change。原因在于 QMK 的键盘以路径寻址keyboard:keymap路径变更会直接破坏所有既有构建命令与外部引用。这一机制与 QMK 的功能弃用政策直接衔接弃用策略文档 规定大型功能或整个子系统在移除前至少会在develop分支上提前一个 Breaking Changes 周期3 个月发布弃用通知而每次develop合入master时都会附带一份 ChangeLog 文档来公布已完成与计划的弃用。小功能则可能基于仓库内使用率随时在develop分支上移除。三月周期develop 与 master 的双分支模型Breaking change period 是指维护者会合并“以危险或出乎意料的方式改变 QMK”的 PR 的窗口。QMK 为此内置了一段测试期以保证由此引发的问题“罕见或无法预测”。具体做法是QMK 以三个月为节奏把develop分支合并进master分支。历史上的 Breaking Changes文档列出最近三期变更均对应 docs/ChangeLog 目录下的合并日志文件2026-05-31 → docs/ChangeLog/202605312026-02-22 → docs/ChangeLog/202602222025-11-30 → docs/ChangeLog/20251130完整的变更史在 Past Breaking Changes 页面 中维护覆盖 2019-08-30version 0.7.0至 2026-05-31version 0.33.0共 27 期基本保持“每季度一期、每期递增一个次版本号”的节奏。从最近的合并日志 20260531.md 可以看到 Breaking Change 的典型内容形态例如移除已弃用的isLeftHand全局变量要求用户迁移到split_util.h中的is_keyboard_left()、移除usb.force_nkro/FORCE_NKRO改为通过keyboard.json的host.default.nkro或config.h的NKRO_DEFAULT_ON配置以及 VIA 升级、新传感器驱动等核心功能变更。下一期 Breaking Change 的时间表文档给出的当前排期下一期 Breaking Change 计划在 2026-08-30 进行关键节点如下“Important Dates”日期事件2026-05-31文档原文写作 2025 May 31按上下文时间线应为 2026 年 5 月 31 日develop被打上新的 release 版本 tag此后每次推送到master都会由 GitHub Actions 反向合并回develop2026-08-02develop关闭新 PR2026-08-02发起测试者召集Call for testers2026-08-16合并最后期限——此后develop进入测试锁定仅接受 bugfix2026-08-23develop锁定仅合并关键 bugfix PR2026-08-28master锁定不接受任何 PR2026-08-30执行develop→master合并2026-08-30master解锁恢复 PR 合并从源码结构看上述“master 推送后自动回灌 develop”的机制由仓库内的 GitHub Actions 工作流 .github/workflows/develop_update.yml 实现该工作流监听master分支的 push 事件使用 QMK Bot 的 token 检出develop执行git merge origin/master后推送从而保证两分支在合并点后保持同步。同时.github/workflows/ci_build_major_branch.yml 会对master、develop、xap三条主要分支的推送执行 CI 固件构建这正对应 Breaking Change 周期中“内置测试期”的自动化验证手段。本期会包含哪些变更标签、准入标准与 ChangeLog 要求用两个标签跟踪候选项core标签每当有 PR 创建或改动、且触及 QMK 固件的核心区域时自动打上。带有该标签并不保证会在本周期内合并——在develop关闭前仍可能加入新变更且解决冲突一般由提交者负责。breaking_change_YYYYqN标签由 QMK Collaborators 使用表示该 PR 是强候选strong candidate应被优先审查。若你希望自己的 Breaking Change 进入本轮需要在develop关闭前创建 PR 并获 QMK Collaborators 接受develop关闭后提交的新内容将顺延到下一个周期。文档还给出了实用建议PR 越简单维护者审查越容易、合并越快大 PR 往往需要反复重构与审查期间其他 PR 陆续合并还会显著提高冲突概率。准入门槛Criteria for acceptancePR 已完成、可合并complete and ready to mergePR 的 GitHub 检查尽可能为绿若被标记的检查项与 PR 提出的改动无关维护者可以忽略该“红灯”例如修改既有文件时不应为了通过 lint 而添加 license header与 PR 功能无直接关系的改动原则上应避免顺手修改。ChangeLog 文件强烈建议PR 强烈建议附带一份描述变更的 ChangeLog 文件位于qmk_firmware/docs/ChangeLog/日期目录下采用 Markdown 格式文件名为PR12345.md数字替换为你的 PR ID强烈建议 ChangeLog 内容与 PR 在 GitHub 上的描述保持一致以保证可追溯性。仓库中 docs/ChangeLog 目录实际保存了每期合并日志如 20241124.md、20251130.md每期文件包含“Notable Changes”“Deprecation Notices”和“Full changelist”等章节正是合并时由若干PRxxxxx.md汇总而成的产物。如果你不确定自己的 PR 为何被标记为 Breaking Change可参考 Breaking Changes: My Pull Request Was Flagged其中列出了常见触发原因编辑用户 keymap、改变预期行为、要求用户操作、需要加强审查、需要向终端用户传达信息等以及应对策略拆分 PR、在 PR 中详细记录变更影响、主动寻求协助。合并前的分阶段清单Checklists文档“Checklists”一节记录了维护者运行 Breaking Changes 流程时的各阶段动作以下按时间倒序完整继承原文合并前 4 周develop关闭新 PR仅允许合并对现有 PR 的修复在 Discord 的#qmk_firmware频道向Breaking Changes Updates发出测试者召集“Hey folks, last day for functional PRs to be raised against qmk_firmware for this breaking changes cycle is today.”合并前 2 周develop关闭现有 PR 的合并仅允许包含先前合并内容的 bugfix向Breaking Changes Updates发消息召集测试者“Hey folks, last day for functional PRs to be merged into qmk_firmware for this breaking changes cycle is today. After that, were handling bugfixes only.”合并前 1 周develop关闭 PR 合并仅允许关键 bugfix预告master将在“合并前 2 天”至“合并日”之间关闭向Breaking Changes Updates发消息“Hey folks, last day for functional PRs to be merged into qmk_firmware for this breaking changes cycle is today. After that, were handling bugfixes only.”合并前 2 天master关闭 PR 合并宣告 master 将锁定 2 天“Hey folks, the master branch of qmk_firmware is now locked for the next couple of days while we prepare to merge the newest batch of changes from develop.”合并日Day Of Merge维护者在本地qmk_firmware仓库依次执行git checkout develop git pull --ff-only # 编辑 readme.md删除关于 develop 的说明 # 将 ChangeLog 汇总为一个文件 git commit -m Merge point for DATE Breaking Change git push upstream develop接着在 GitHub Actions 侧操作为develop创建一个 PR关闭仓库的 “Automatically delete head branches” 选项——在继续之前需与 QMK directors 确认已完成。然后在本地继续执行合并git checkout master git pull --ff-only git merge --no-ff develop git tag next_version # 防止 breakpoint tag 干扰版本号递增 git push upstream next_version git push upstream master其中--no-ff保证在master上产生一个显式的合并提交作为该期 Breaking Change 的锚点git tag next_version则用于避免分支点标签对后续版本号递增造成干扰。合并后的操作Post-merge operations更新 develop 分支这紧接上一期develop合入master之后立即执行git checkout master git pull --ff-only git checkout develop git pull --ff-only git merge --no-ff master # 编辑 readme.md # - 在顶部添加醒目提示这是一个测试分支可参考 develop 分支的历史版本 # - 附上对本文档docs/breaking_changes.md的链接 git commit -m Branch point for DATE Breaking Change git tag breakpoint_YYYY_MM_DD git push upstream breakpoint_YYYY_MM_DD git push upstream develop校验 lib 下的子模块与 QMK fork 一致所有lib下的子模块需要逐一与 QMK 的 fork 比对git submodule foreach git log -n1以 ChibiOS 为例的校验流程查看上述输出的 commit hash到 QMK 的 ChibiOS fork 仓库qmk/ChibiOSGitHub 上 QMK 组织的 fork原文含外链此处不输出比对 commit hash若不一致则该 fork 仓库的qmk-master分支必须更新否则 Configurator 无法工作cd lib/chibios git fetch --all git checkout qmk-master git reset --hard commit hash git push origin qmk-master --force-with-lease宣告解锁与可选的 ChibiOS 升级向Breaking Changes Updates宣告master与develop均已解锁“Hey folks, develop has now been merged into master -- newest batch of changes are now available for everyone to use!”可选在develop上升级 ChibiOS ChibiOS-Contrib具体步骤见 ChibiOS 升级流程文档——ChibiOS 与 ChibiOS-Contrib 必须成对升级因为后者存在与所用 ChibiOS 版本绑定的分支。为下一周期建立排期Set up Discord events合并完成后维护者需要更新本文件docs/breaking_changes.md中的新日期并在 QMK Discord“Somewhere Else” → “GitHub”创建 5 个周期事件。事件模板如下日期均相对于合并日推算统一以 12:00am 为界事件主题开始时间结束时间描述Event #1Lastdevelopfunctionality PRs to be raised合并前 5 周合并前 4 周本周期内针对develop提出功能性 PR 的最后窗口合并前 4 周之后新的功能 PR 将顺延至下一周期Event #2Lastdevelopfunctionality PRs to be merged合并前 4 周合并前 2 周功能性 PR 合入develop的最后窗口此后仅考虑 bugfix PREvent #3developclosed for merges合并前 2 周合并日功能性 bugfix PR 合入develop的截止期合并前 1 周之后仅考虑关键 bugfixEvent #4masterclosed for merges合并前 2 天合并日期间不向master合并任何 PR以保证develop合入master的稳定Event #5developmerges tomaster合并日 00:00合并日 23:45QMK 将在该时段内把develop合入master所有用户随后即可使用最新一批功能对普通用户与贡献者的实际意义将上述机制落到使用者视角可以归纳为三点可操作结论普通用户日常应跟踪master分支稳定版若想在合并前体验新功能并承担测试责任可在对应窗口响应 Call for testers并在合并日后通过 docs/ChangeLog 中该期的日志了解弃用与迁移要求例如上文提到的isLeftHand→is_keyboard_left()迁移。keymap 维护者Breaking Change 窗口是 keymap 被集中调整如键盘路径迁移的高风险期更新 QMK 代码树后应重新构建 keymap 验证兼容性——这正是 QMK 限制此类变更频率的初衷。贡献者触及核心区域的 PR 会被打上core标签需等待对应季度周期在develop关闭前完成提交、保持 PR 精简、并附docs/ChangeLog/周期/PRxxxxx.md是进入本期变更的最稳妥路径。综上QMK 的 Breaking Changes 机制本质上是一套“季度批处理”式的变更治理流程用固定的 develop/master 合并节奏换取测试窗口用标签体系core、breaking_change_YYYYqN筛选与优先级排序候选 PR用分阶段清单4 周 → 2 周 → 1 周 → 2 天 → 合并日逐步收窄develop的合并范围最终通过--no-ff合并、版本 tag 与 ChangeLog 汇总在master上留下可追溯的变更锚点。相关文档与实现入口均在本仓库中可查证流程总览、历史变更索引、变更日志目录、弃用策略、ChibiOS 升级流程、PR 被标记指引。【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考