auri.ee
keyboard stuff
1# Breaking Changes
2
3This 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.
4
5This also includes any keyboard moves within the repository.
6
7The breaking change period is when we will merge PRs 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.
8
9Practically, this means QMK merges the `develop` branch into the `master` branch on a 3-month cadence.
10
11## What has been included in past Breaking Changes?
12
13* [2025 Nov 30](ChangeLog/20251130)
14* [2025 Aug 31](ChangeLog/20250831)
15* [2025 May 25](ChangeLog/20250525)
16* [Older Breaking Changes](breaking_changes_history)
17
18## When is the next Breaking Change?
19
20The next Breaking Change is scheduled for February 22, 2026.
21
22### Important Dates
23
24* 2025 Nov 30 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
25* 2026 Jan 25 - `develop` closed to new PRs.
26* 2026 Jan 25 - Call for testers.
27* 2026 Feb 8 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
28* 2026 Feb 15 - `develop` is locked, only critical bugfix PRs merged.
29* 2026 Feb 20 - `master` is locked, no PRs merged.
30* 2026 Feb 22 - Merge `develop` to `master`.
31* 2026 Feb 22 - `master` is unlocked. PRs can be merged again.
32
33## What changes will be included?
34
35To see a list of breaking changes merge candidates you can look at the [`core` label](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Acore+is%3Apr). This label is applied whenever a PR is raised or changed, but only if the PR includes changes to core areas of QMK Firmware. A PR with that label applied is not guaranteed to be merged in the current cycle. New changes might be added between now and when `develop` is closed, and it is generally the responsibility of the submitter to handle conflicts. There is also another label used by QMK Collaborators -- `breaking_change_YYYYqN` -- which signifies to maintainers that it is a strong candidate for inclusion, and should be prioritized for review.
36
37If you want your breaking change to be included in this round you need to create a PR and have it accepted by QMK Collaborators before `develop` closes. After `develop` closes, new submissions will be deferred to the next breaking changes cycle.
38
39The simpler your PR is, the easier it is for maintainers to review, thus a higher likelihood of a faster merge. Large PRs tend to require a lot of attention, refactoring, and back-and-forth with subsequent reviews -- with other PRs getting merged in the meantime larger unmerged PRs are far more likely to be susceptible to conflicts.
40
41Criteria for acceptance:
42
43* The PR is complete and ready to merge
44* GitHub checks for the PR are green whenever possible
45 * A "red" check may be disregarded by maintainers if the items flagged are unrelated to the change proposed in the PR
46 * Modifications to existing files should not need to add license headers to pass lint, for instance.
47 * If it's not directly related to your PR's functionality, prefer avoiding making a change.
48
49Strongly suggested:
50
51* The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20241124`.
52 * This should be in Markdown format, with a name in the format `PR12345.md`, substituting the digits for your PRs ID.
53 * One strong recommendation that the ChangeLog document matches the PR description on GitHub, so as to ensure traceability.
54
55## Checklists
56
57This section documents various processes we use when running the Breaking Changes process.
58
59### 4 Weeks Before Merge
60
61* `develop` is now closed to new PRs, only fixes for current PRs may be merged
62* Post call for testers: message `@Breaking Changes Updates` on `#qmk_firmware` in Discord:
63 * `@Breaking Changes Updates -- Hey folks, last day for functional PRs to be raised against qmk_firmware for this breaking changes cycle is today.`
64
65### 2 Weeks Before Merge
66
67* `develop` is now closed to existing PR merges, only bugfixes for previous merges may be included
68* Post call for testers: message `@Breaking Changes Updates` on `#qmk_firmware` in Discord.
69 * `@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.`
70
71### 1 Week Before Merge
72
73* `develop` is now closed to PR merges, only critical bugfixes may be included
74* Announce that master will be closed from `<2 Days Before>` to `<Day of Merge>` -- message `@Breaking Changes Updates` on `#qmk_firmware` in Discord:
75 * `@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.`
76
77### 2 Days Before Merge
78
79* `master` is now closed to PR merges
80* Announce that master is closed for 2 days
81 * `@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.`
82
83### Day Of Merge
84
85* `qmk_firmware` git commands
86 * `git checkout develop`
87 * `git pull --ff-only`
88 * Edit `readme.md`
89 * Remove the notes about `develop`
90 * Roll up the ChangeLog into one file.
91 * `git commit -m 'Merge point for <DATE> Breaking Change'`
92 * `git push upstream develop`
93* GitHub Actions
94 * Create a PR for `develop`
95 * **Turn off 'Automatically delete head branches' for the repository** -- confirm with @qmk/directors that it is done before continuing
96* `qmk_firmware` git commands
97 * `git checkout master`
98 * `git pull --ff-only`
99 * `git merge --no-ff develop`
100 * `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
101 * `git push upstream <next_version>`
102 * `git push upstream master`
103
104## Post-merge operations
105
106### Updating the `develop` branch
107
108This happens immediately after the previous `develop` branch is merged to `master`.
109
110* `qmk_firmware` git commands
111 * `git checkout master`
112 * `git pull --ff-only`
113 * `git checkout develop`
114 * `git pull --ff-only`
115 * `git merge --no-ff master`
116 * Edit `readme.md`
117 * Add a big notice at the top that this is a testing branch. See previous revisions of the `develop` branch.
118 * Include a link to this document
119 * `git commit -m 'Branch point for <DATE> Breaking Change'`
120 * `git tag breakpoint_<YYYY>_<MM>_<DD>`
121 * `git push upstream breakpoint_<YYYY>_<MM>_<DD>`
122 * `git push upstream develop`
123
124* All submodules under `lib` now need to be checked against their QMK-based forks:
125 * `git submodule foreach git log -n1`
126 * Validate each submodule SHA1 matches the qmk fork, e.g. for ChibiOS:
127 * Go to [qmk/ChibiOS](https://github.com/qmk/ChibiOS)
128 * Compare the commit hash in the above output to the commit hash in the repository
129 * If there's a mismatch, that repository needs to have its `qmk-master` branch updated to match (otherwise Configurator won't work):
130 * `cd lib/chibios`
131 * `git fetch --all`
132 * `git checkout qmk-master`
133 * `git reset --hard <commit hash>`
134 * `git push origin qmk-master --force-with-lease`
135
136* Announce that both `master` and `develop` are now unlocked -- message `@Breaking Changes Updates` on `#qmk_firmware` in Discord:
137 * `@Breaking Changes Updates -- Hey folks, develop has now been merged into master -- newest batch of changes are now available for everyone to use!`
138
139* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop`](chibios_upgrade_instructions)
140
141
142### Set up Discord events for the next cycle
143
144* Update this file with the new dates: `docs/breaking_changes.md`
145* Create Events on the QMK Discord - "Somewhere Else" => "GitHub":
146 * Event #1:
147 | Field | Value |
148 |-------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
149 | Topic | Last `develop` functionality PRs to be raised |
150 | Start Date | ((5 weeks before merge)), 12:00am |
151 | End Date | ((4 weeks before merge)), 12:00am |
152 | 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. |
153 * Event #2:
154 | Field | Value |
155 |-------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
156 | Topic | Last `develop` functionality PRs to be merged |
157 | Start Date | ((4 weeks before merge)), 12:00am |
158 | End Date | ((2 weeks before merge)), 12:00am |
159 | 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. |
160 * Event #3:
161 | Field | Value |
162 |-------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
163 | Topic | `develop` closed for merges |
164 | Start Date | ((2 weeks before merge)), 12:00am |
165 | End Date | ((day of merge)), 12:00am |
166 | 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. |
167 * Event #4:
168 | Field | Value |
169 |-------------|----------------------------------------------------------------------------------------------------------------------|
170 | Topic | `master` closed for merges |
171 | Start Date | ((2 days before merge)), 12:00am |
172 | End Date | ((day of merge)), 12:00am |
173 | Description | This is the period that no PRs are to be merged to `master`, so that the merge of `develop` into `master` is stable. |
174 * Event #5:
175 | Field | Value |
176 |-------------|--------------------------------------------------------------------------------------------------------------------------------------------|
177 | Topic | `develop` merges to `master` |
178 | Start Date | ((day of merge)), 12:00am |
179 | End Date | ((day of merge)), 11:45pm |
180 | 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. |