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 November 26, 2022.
develop
is tagged with a new release version. Each push to master
is subsequently merged to develop
by GitHub actions.develop
closed to new PR's.develop
is locked for testing and accepts only bugfixesdevelop
is locked, only critical bugfix PR's merged.master
is locked, no PR's merged.develop
to master
.master
is unlocked. PR's can be merged again.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/20221126
.
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 merged@Breaking Changes Updates
on #qmk_firmware
in Discord:
@Breaking Changes Updates -- Hey folks, last day for functional PRs to be raised against qmk_firmware for this breaking changes cycle is today.
develop
is now closed to existing PR merges, only bugfixes for previous merges may be included@Breaking Changes Updates
on #qmk_firmware
in Discord.
@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.
develop
is now closed to PR merges, only critical bugfixes may be included@Breaking Changes Updates
on #qmk_firmware
in Discord:
@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.
master
is now closed to PR merges@Breaking Changes Updates -- 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.
qmk_firmware
git commands
git checkout develop
git pull --ff-only
readme.md
develop
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
develop
branch.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
master
branch updated to match (otherwise Configurator won't work):
cd lib/chibios
git fetch --all
git checkout master
git reset --hard <commit hash>
git push origin master --force-with-lease
Announce that both master
and develop
are now unlocked -- message @Breaking Changes Updates
on #qmk_firmware
in Discord:
@Breaking Changes Updates -- Hey folks, develop has now been merged into master -- newest batch of changes are now available for everyone to use!
(Optional) update ChibiOS + ChibiOS-Contrib on develop
docs/breaking_changes.md
Field | Value |
---|---|
Topic | Last develop functionality PRs to be raised |
Start Date | ((5 weeks before merge)), 12:00am |
End Date | ((4 weeks before merge)), 12:00am |
Description | This is the last window for functional PRs to be raised against develop for the current breaking changes cycle. After ((4 weeks before merge)), any new PRs targeting develop will be deferred to the next cycle. |
Field | Value |
---|---|
Topic | Last develop functionality PRs to be merged |
Start Date | ((4 weeks before merge)), 12:00am |
End Date | ((2 weeks before merge)), 12:00am |
Description | This is the last window for functional PRs to be merged into develop for the current breaking changes cycle. After ((2 weeks before merge)), only bugfix PRs targeting develop will be considered for merge. |
Field | Value |
---|---|
Topic | develop closed for merges |
Start Date | ((2 weeks before merge)), 12:00am |
End Date | ((day of merge)), 12:00am |
Description | This is the deadline for functionality bugfix PRs to be merged into develop for the current breaking changes cycle. After ((1 week before merge)), only critical bugfix PRs targeting develop will be considered for merge. |
Field | Value |
---|---|
Topic | master closed for merges |
Start Date | ((2 days before merge)), 12:00am |
End Date | ((day of merge)), 12:00am |
Description | This is the period that no PRs are to be merged to master , so that the merge of develop into master is stable. |
Field | Value |
---|---|
Topic | develop merges to master |
Start Date | ((day of merge)), 12:00am |
End Date | ((day of merge)), 11:45pm |
Description | At some point, QMK will merge develop into master and everyone will be able to reap the benefits of the newest batch of functionality. |