breaking_changes.md (14402B)
1 # Breaking Changes 2 3 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. 4 5 This also includes any keyboard moves within the repository. 6 7 The 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 9 Practically, 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 20 The 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 35 To 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 37 If 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 39 The 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 41 Criteria 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 49 Strongly 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 57 This 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 108 This 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. |