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/20260531
- 2026-02-22 → docs/ChangeLog/20260222
- 2025-11-30 → docs/ChangeLog/20251130
完整的变更史在 Past Breaking Changes 页面 中维护，覆盖 2019-08-30（version 0.7.0）至 2026-05-31（version 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 反向合并回develop |
| 2026-08-02 | develop关闭新 PR |
| 2026-08-02 | 发起测试者召集（Call for testers） |
| 2026-08-16 | 合并最后期限——此后develop进入测试锁定，仅接受 bugfix |
| 2026-08-23 | develop锁定，仅合并关键 bugfix PR |
| 2026-08-28 | master锁定，不接受任何 PR |
| 2026-08-30 | 执行develop→master合并 |
| 2026-08-30 | master解锁，恢复 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 acceptance）
- PR 已完成、可合并（complete and ready to merge）；
- PR 的 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, we're 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, we're 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/ChibiOS，GitHub 上 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 #1 | Lastdevelopfunctionality PRs to be raised | 合并前 5 周 | 合并前 4 周 | 本周期内针对develop提出功能性 PR 的最后窗口；合并前 4 周之后，新的功能 PR 将顺延至下一周期 |
| Event #2 | Lastdevelopfunctionality PRs to be merged | 合并前 4 周 | 合并前 2 周 | 功能性 PR 合入develop的最后窗口；此后仅考虑 bugfix PR |
| Event #3 | developclosed for merges | 合并前 2 周 | 合并日 | 功能性 bugfix PR 合入develop的截止期；合并前 1 周之后仅考虑关键 bugfix |
| Event #4 | masterclosed for merges | 合并前 2 天 | 合并日 | 期间不向master合并任何 PR，以保证develop合入master的稳定 |
| Event #5 | developmerges tomaster | 合并日 00:00 | 合并日 23:45 | QMK 将在该时段内把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），仅供参考
