2019-08-30 19:04:09 +00:00
# Breaking Changes
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.
2021-11-27 23:41:48 +00:00
This also includes any keyboard moves within the repository.
2019-08-30 19:04:09 +00:00
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.
## What has been included in past Breaking Changes?
2021-11-27 23:41:48 +00:00
* [2021 Nov 27 ](ChangeLog/20211127.md )
2021-08-28 22:18:18 +00:00
* [2021 Aug 28 ](ChangeLog/20210828.md )
2021-05-29 19:30:31 +00:00
* [2021 May 29 ](ChangeLog/20210529.md )
2021-02-27 20:10:23 +00:00
* [2021 Feb 27 ](ChangeLog/20210227.md )
2020-11-28 20:02:18 +00:00
* [2020 Nov 28 ](ChangeLog/20201128.md )
2020-08-29 17:48:38 +00:00
* [2020 Aug 29 ](ChangeLog/20200829.md )
2020-05-30 20:14:59 +00:00
* [2020 May 30 ](ChangeLog/20200530.md )
2020-02-29 20:30:38 +00:00
* [2020 Feb 29 ](ChangeLog/20200229.md )
2019-08-30 19:04:09 +00:00
* [2019 Aug 30 ](ChangeLog/20190830.md )
## When is the next Breaking Change?
2021-11-27 23:41:48 +00:00
The next Breaking Change is scheduled for February 26, 2022.
2019-08-30 19:04:09 +00:00
### Important Dates
2021-11-28 01:59:48 +00:00
* [x] 2021 Nov 27 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions.
2021-11-27 23:41:48 +00:00
* [ ] 2022 Jan 31 - `develop` closed to new PR's.
* [ ] 2022 Jan 31 - Call for testers.
* [ ] 2022 Feb 12 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes
* [ ] 2022 Feb 24 - `master` is locked, no PR's merged.
* [ ] 2022 Feb 26 - Merge `develop` to `master` .
* [ ] 2022 Feb 26 - `master` is unlocked. PR's can be merged again.
2019-08-30 19:04:09 +00:00
## What changes will be included?
2020-05-30 20:14:59 +00:00
To see a list of breaking change candidates you can look at the [`breaking_change` label ](https://github.com/qmk/qmk_firmware/pulls?q=is%3Aopen+label%3Abreaking_change+is%3Apr ). 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.
2019-08-30 19:04:09 +00:00
2020-05-30 20:14:59 +00:00
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.
2019-08-30 19:04:09 +00:00
Criteria for acceptance:
2021-11-27 23:41:48 +00:00
* The PR is complete and ready to merge
* The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20220226` .
* This should be in Markdown format, with a name in the format `PR12345.md` , substituting the digits for your PR's ID.
* One strong recommendation that the ChangeLog document matches the PR description on GitHub, so as to ensure traceability.
2019-08-30 19:04:09 +00:00
# Checklists
This section documents various processes we use when running the Breaking Changes process.
2020-05-30 20:14:59 +00:00
## Creating the `develop` branch
2019-09-21 18:58:06 +00:00
2020-05-30 20:14:59 +00:00
This happens immediately after the previous `develop` branch is merged.
2019-08-30 19:04:09 +00:00
* `qmk_firmware` git commands
* [ ] `git checkout master`
* [ ] `git pull --ff-only`
2020-05-30 20:14:59 +00:00
* [ ] `git checkout -b develop`
2019-08-30 19:04:09 +00:00
* [ ] Edit `readme.md`
* [ ] Add a big notice at the top that this is a testing branch.
* [ ] Include a link to this document
* [ ] `git commit -m 'Branch point for <DATE> Breaking Change'`
* [ ] `git tag breakpoint_<YYYY>_<MM>_<DD>`
* [ ] `git tag <next_version>` # Prevent the breakpoint tag from confusing version incrementing
2021-06-17 23:05:27 +00:00
* [ ] `git push upstream develop`
2019-08-30 19:04:09 +00:00
* [ ] `git push --tags`
2020-01-09 18:55:46 +00:00
## 4 Weeks Before Merge
2019-08-30 19:04:09 +00:00
2020-05-30 20:14:59 +00:00
* `develop` is now closed to new PR's, only fixes for current PR's may be merged
2019-08-30 19:04:09 +00:00
* Post call for testers
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
2021-11-27 23:41:48 +00:00
## 2 Weeks Before Merge
* `develop` is now closed to existing PR merges, only bugfixes for previous merges may be included
* Post call for testers
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
2019-08-30 19:04:09 +00:00
## 1 Week Before Merge
* Announce that master will be closed from < 2 Days Before > to < Day of Merge >
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## 2 Days Before Merge
* Announce that master is closed for 2 days
* [ ] Discord
* [ ] GitHub PR
* [ ] https://reddit.com/r/olkb
## Day Of Merge
* `qmk_firmware` git commands
2020-05-30 20:14:59 +00:00
* [ ] `git checkout develop`
2019-08-30 19:04:09 +00:00
* [ ] `git pull --ff-only`
* [ ] Edit `readme.md`
2020-05-30 20:14:59 +00:00
* [ ] Remove the notes about `develop`
2019-08-30 19:04:09 +00:00
* [ ] Roll up the ChangeLog into one file.
* [ ] `git commit -m 'Merge point for <DATE> Breaking Change'`
2021-06-17 23:05:27 +00:00
* [ ] `git push upstream develop`
2020-05-26 02:43:14 +00:00
* GitHub Actions
2020-05-30 20:14:59 +00:00
* [ ] Create a PR for `develop`
2021-06-17 23:05:27 +00:00
* [ ] **Turn off 'Automatically delete head branches' for the repository** -- confirm with @qmk/directors that it is done before continuing
* `qmk_firmware` git commands
* [ ] `git checkout master`
* [ ] `git pull --ff-only`
* [ ] `git merge --no-ff develop`
* [ ] `git push upstream master`
2021-05-31 22:11:50 +00:00
## Post-merge operations
2021-06-20 02:10:59 +00:00
* (Optional) [update ChibiOS + ChibiOS-Contrib on `develop` ](chibios_upgrade_instructions.md )
