This document describes QMK's Breaking Change process. A Breaking Change is any change which modifies how QMK behaves in a way that in incompatible or potentially dangerous. We limit these changes so that users can have confidence that updating their QMK tree will not break their keymaps.
This also includes any keyboard moves within the repository.
The breaking change period is when we will merge PR's that change QMK in dangerous or unexpected ways. There is a built-in period of testing so we are confident that any problems caused are rare or unable to be predicted.
The next Breaking Change is scheduled for August 27, 2022.
To see a list of breaking change candidates you can look at the breaking_change
label. New changes might be added between now and when develop
is closed, and a PR with that label applied is not guaranteed to be merged.
If you want your breaking change to be included in this round you need to create a PR with the breaking_change
label and have it accepted before develop
closes. After develop
closes no new breaking changes will be accepted.
Criteria for acceptance:
<qmk_firmware>/docs/Changelog/20220827
.
PR12345.md
, substituting the digits for your PR's ID.This section documents various processes we use when running the Breaking Changes process.
develop
is now closed to new PR's, only fixes for current PR's may be mergeddevelop
is now closed to existing PR merges, only bugfixes for previous merges may be includedqmk_firmware
git commands
git commit -m 'Merge point for <DATE> Breaking Change'
git push upstream develop
develop
qmk_firmware
git commands
git checkout master
git pull --ff-only
git merge --no-ff develop
git tag <next_version>
# Prevent the breakpoint tag from confusing version incrementinggit push upstream <next_version>
git push upstream master
develop
branchThis happens immediately after the previous develop
branch is merged to master
.
qmk_firmware
git commands
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>
All submodules under lib
now need to be checked against their QMK-based forks:
git submodule foreach git log -n1
cd lib/chibios
git fetch --all
git checkout master
git reset --hard <commit hash>
git push origin master --force-with-lease
(Optional) update ChibiOS + ChibiOS-Contrib on develop