QMK Firmware Breaking Changes 流程当你的 Pull Request 被标记为破坏性变更时该如何应对【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmwareQMK 以更新代码树不会弄坏用户现有键位图keymap为底线对破坏性变更Breaking Change实施了一套严格的准入与合并流程。本文围绕官方文档中我的 PR 被标记为破坏性变更这一场景展开先讲清楚什么样的改动会被打上破坏性变更标签再给出拆分 PR、补文档、寻求帮助三类实操建议并结合仓库内的流程文档与真实 Changelog深入解析 3 个月一期的develop→master合并机制、各阶段检查清单与 Git 操作命令帮助你既顺利完成贡献又理解维护者视角下的风险控制逻辑。什么改动会被标记为 Breaking ChangeQMK 对破坏性变更的定义是任何以不兼容或潜在危险的方式改变 QMK 行为的变更此外还包括仓库内键盘文件的移动。QMK 刻意限制这类变更的合入节奏让用户可以确信更新 QMK 代码树不会弄坏自己的键位图见 Breaking Changes 文档。在实践层面QMK 每 3 个月将develop分支合并回master一次这个窗口期就是破坏性变更期在此期间会合并那些以危险或出乎意料方式改变 QMK 的 PR并预留一段内置的测试缓冲以确认由变更引发的问题足够少或不可预测见 Breaking Changes 文档。当你提交了一个 PRQMK 成员可能会回复说你的提交属于破坏性变更——这意味着在他们看来你的改动对 QMK 本身或其用户有更大的影响面。根据 PR 被标记后的说明文档常见触发原因有五类对用户键位图的编辑Edits to User Keymaps用户可能把自己提交的 keymap 捐献给 QMK 仓库一段时间后再次发起 PR 更新它却发现因为该 keymap 已经在qmk/qmk_firmware仓库内被他人编辑过而无法合并。由于并非所有用户都熟练使用 Git/GitHub这类用户往往无法自行解决冲突。改变预期行为Changes to Expected Behavior改变 QMK 既有功能的行为可能让刷入新固件的用户误以为硬件或 QMK 坏了——他们发现自己的行为变了却找不到恢复原行为的手段。要求用户采取行动的变更Changes Requiring User Action变更可能要求用户做出额外操作例如升级工具链或在 Git 层面执行某些动作。需要加强审查的变更Changes Necessitating Increased Scrutiny某些提交对 QMK 项目本身有影响例如版权/许可问题、编码规范问题、大规模功能重构、需要社区更广泛测试的高风险变更或其他性质的敏感改动。需要向最终用户传达信息的变更Changes Requiring Communication to End Users包括未来弃用的预警、过时用法的提示以及其他需要传达但不属于以上任何一类的内容。PR 被标记后你可以做什么被标记并不意味着 PR 被拒绝。说明文档给出了三条具体建议都是围绕降低合并风险、加快审查展开的。1. 考虑把 PR 拆分如果你在贡献核心代码而它需要走破坏性变更流程的唯一原因是要顺手更新 keymap 以适配你的改动那么请考虑能否以旧 keymap 继续可用的方式提交你的功能。然后另开一个独立 PR走破坏性变更流程去移除旧代码。这个策略的本质是把行为不变的增量与必须变更行为的清理解耦前者可以随常规流程快速合入后者按 3 个月节奏统一进入测试窗口。这与后文会讲的接受标准中PR 越简单维护者越容易审查的原则一脉相承。2. 把你的变更写清楚让审查者理解你提交的目的、可能带来的影响以及用户需要采取的行动可以显著简化审查过程。Changelog 文件在多数情况下足以承担这个职责但更广泛的变更可能需要超出 Changelog 粒度的细节。在 PR 下主动评论、及时回应提问、评论与修改要求是被明确非常欢迎的做法。3. 寻求帮助如果 PR 被标记这件事让你措手不及或者你感到不知所措直接说出来在 PR 下留言或联系 QMK 团队官方文档中给出的渠道是 Discord。流程上不存在必须独自扛下来的隐含要求。Breaking Changes 周期全景3 个月一次的 develop → master 合并理解自己被标记的 PR 会流向哪里需要先看清整个周期的时间线。根据 Breaking Changes 文档 的当前内容下一个 Breaking Change 排期为 2026 年 8 月 30 日重要节点如下2025 年 5 月 31 日 -develop打上新版本发布标签此后每次推送到master都由 GitHub Actions 自动合并回develop。2026 年 8 月 2 日 -develop停止接收新 PR同时发起测试者征集call for testers。2026 年 8 月 16 日 - 合并截止日——此后再进入develop的只有 bugfix。2026 年 8 月 23 日 -develop锁定只合并关键 bugfix PR。2026 年 8 月 28 日 -master锁定不再合并 PR。2026 年 8 月 30 日 - 将develop合并进mastermaster随即解锁恢复 PR 合并。以上日期以仓库当前文档快照为准每个周期开始前维护者都会更新文档中的日期。变更如何被收集与判定develop关闭前提交并被 QMK Collaborators 接受的破坏性变更才会进入本轮develop关闭后的新提交将被推迟到下一个周期。仓库文档中提到的两个标签机制值得注意core标签每当 PR 被创建或更新时自动检查若包含对 QMK 核心区域的改动则自动打标。带有该标签不代表保证会在当前周期合并且在develop关闭前仍可能加入新的变更处理冲突一般是提交者的责任。breaking_change_YYYYqN标签由 QMK Collaborators 使用表示该 PR 是本轮的强候选项应优先审查。接受标准来自 Breaking Changes 文档PR 是完整且可直接合并的状态GitHub 检查项尽可能全绿。红的检查在以下情况可被维护者忽略被标记的问题与 PR 提出的改动无关例如修改已有文件不需要补 license 头才能通过 lint与 PR 功能无直接关系的改动宁可不要顺手做。强烈建议在qmk_firmware/docs/ChangeLog/日期下提交一个描述变更的 ChangeLog 文件Markdown 格式文件名形如PR12345.md数字替换为你的 PR ID并强烈建议该 ChangeLog 文档内容与 PR 描述保持一致以保证可追溯性。一个简单的经验法则同样来自该文档PR 越简单维护者越容易审查合入速度越快。大 PR 需要大量注意力、重构和多轮来回——而其他 PR 在持续合入未合并的大 PR 产生冲突的概率也随之升高。周期各阶段的操作检查清单BREAKING CHANGES 文档 中记录了维护者执行流程时使用的各阶段清单。以下摘录关键的运维动作与合并日Day Of Merge的完整 Git 命令便于理解每一阶段仓库的状态。合并前 4 周develop关闭新 PR只允许合并针对现有 PR 的修复在 Discord#qmk_firmware频道向Breaking Changes Updates发消息宣告本轮面向develop的功能性 PR 提交截止日。合并前 2 周develop停止合并现有 PR只接受针对已合并内容的 bugfix再次发布测试者征集公告宣告功能性 PR 合并截止。合并前 1 周develop只接受关键 bugfix预告master将在合并日前 2 天至合并日期间关闭。合并前 2 天master关闭 PR 合并公告 master 将锁定数日以便准备从develop合并最新一批变更。合并日Day Of Merge这是整个周期操作密度最高的一天文档中给出的 Git 命令如下在qmk_firmware仓库内执行# 先在 develop 上完成合并点提交 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 确认完成后再继续。# 切回 master 并执行非 fast-forward 合并 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合并后的收尾操作合并完成不是周期的终点。文档 的 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在顶部加醒目提示说明这是测试分支并附上破坏性变更文档链接 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其中breakpoint_YYYY_MM_DD标签的作用与合并日打next_version标签类似标记分叉点避免后续版本号递增逻辑被歧义标签干扰。校验 lib 下子模块与 QMK fork 的一致性lib下的所有子模块需要与对应的 QMK fork 逐一比对因为 SHA1 不匹配会导致 Configurator 无法工作# 查看各子模块当前指向的提交 git submodule foreach git log -n1以 ChibiOS 为例将其输出的 commit hash 与 qmk fork 的qmk-master分支比对若不一致则需要在子模块仓库内执行cd lib/chibios git fetch --all git checkout qmk-master git reset --hard commit hash git push origin qmk-master --force-with-lease可选地维护者还会按 ChibiOS 升级说明 在develop上更新 ChibiOS 与 ChibiOS-Contrib。最后在 Discord 公告master与develop均已解锁新一批变更对所有人可用并为下一个周期更新docs/breaking_changes.md中的日期、在 Discord 创建 5 个关键事件功能 PR 提交截止、功能 PR 合并截止、develop 关闭、master 关闭、develop 合入 master。弃用策略破坏性变更中的预告期破坏性变更并不都是一刀切。QMK 有明确的弃用与移除策略见 Feature support policies大型功能或整个子系统的弃用至少会在移除前一个破坏性变更周期3 个月先在develop分支上通告影响面更大的功能预告期可能更长由 QMK 团队酌情决定。较小的功能可能在单个周期内被移除通常依据其在仓库内的使用程度决定——使用率极低的功能随时可能在develop上被选中移除。每次从develop合并到master的破坏性变更都会附带 Changelog 文档计划内与已完成的弃用都会在其中通告并且尽可能在编译仍在使用已弃用特性的固件时发出编译期警告。一个真实的例子来自 2026 年 5 月 31 日 Changelog该版本移除了已弃用的isLeftHand要求用户迁移到split_util.h中的is_keyboard_left()oled_rotation_t oled_init_user(oled_rotation_t rotation) { - return isLeftHand ? OLED_ROTATION_180 : OLED_ROTATION_0; return is_keyboard_left() ? OLED_ROTATION_180 : OLED_ROTATION_0; }同一份 Changelog 还记录了usb.force_nkro/FORCE_NKRO的移除原假设只有 USB 能做 NKRO被拆掉后开机强制 NKRO 会产生与NK_TOGG等 NKRO 键码行为不一致的用户困惑。迁移方式为在新默认配置体系中开启 NKRO——例如在keyboard.json或keymap.json中{ host: { default: { nkro: true } } }或在config.h中#pragma once #define NKRO_DEFAULT_ON true这类先弃用、给预告期、再在某个周期移除并给出迁移示例的模式正是第五类触发条件需要向最终用户传达信息在仓库中的具体落地方式。历史 Breaking Changes 一览每个合并周期都会留下一份 Changelog完整索引见 Past Breaking Changes。从 2019 年 8 月 30 日版本 0.7.0到 2026 年 5 月 31 日版本 0.33.0周期基本保持 3 个月一次的节奏对应文件依次为 docs/ChangeLog/20190830.md 至 docs/ChangeLog/20260531.md。这些文件既是用户升级前的行为差异对照表也是维护者记录影响面的范本按 Core / CLI / Submodule updates / Keyboards / Others / Bugs 分区列出全部变更条目并附 PR 编号值得在提交自己的破坏性变更 Changelog 时参照其结构。小结把 PR 被标记为破坏性变更视为一次风险分级而不是拒绝信号先判断它命中五类触发条件中的哪一类再决定是拆分 PR让旧 keymap 继续工作、补充影响面说明与 ChangeLog还是直接向团队求助。与此同时QMK 用3 个月周期 明确的关闭/锁定时间线 合并日固定 Git 流程 合并后子模块一致性校验 Changelog 归档这套机制把对用户键位图的冲击控制在一个可预期、可测试的窗口内——理解这套机制是提交任何触及 QMK 核心行为变更前最划算的准备。延伸阅读PR 被标记后的说明本文主体文档Breaking Changes 流程与时间线历史 Breaking Changes 索引弃用与移除策略2026 年 5 月 31 日 Changelog 实例【免费下载链接】qmk_firmwareOpen-source keyboard firmware for Atmel AVR and Arm USB families项目地址: https://gitcode.com/GitHub_Trending/qm/qmk_firmware创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考