diff options
Diffstat (limited to 'docs/breaking_changes.md')
| -rw-r--r-- | docs/breaking_changes.md | 56 |
1 files changed, 30 insertions, 26 deletions
diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 6233d5a392..919c443123 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -4,50 +4,54 @@ This document describes QMK's Breaking Change process. A Breaking Change is any 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 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. + +Practically, this means QMK merges the `develop` branch into the `master` branch on a 3-month cadence. ## What has been included in past Breaking Changes? +* [2023 Feb 26](ChangeLog/20230226.md) * [2022 Nov 26](ChangeLog/20221126.md) * [2022 Aug 27](ChangeLog/20220827.md) * [2022 May 28](ChangeLog/20220528.md) * [2022 Feb 26](ChangeLog/20220226.md) -* [2021 Nov 27](ChangeLog/20211127.md) -* [2021 Aug 28](ChangeLog/20210828.md) -* [2021 May 29](ChangeLog/20210529.md) -* [2021 Feb 27](ChangeLog/20210227.md) -* [2020 Nov 28](ChangeLog/20201128.md) -* [2020 Aug 29](ChangeLog/20200829.md) -* [2020 May 30](ChangeLog/20200530.md) -* [2020 Feb 29](ChangeLog/20200229.md) -* [2019 Aug 30](ChangeLog/20190830.md) +* [Older Breaking Changes](breaking_changes_history.md) ## When is the next Breaking Change? -The next Breaking Change is scheduled for February 26, 2023. +The next Breaking Change is scheduled for May 28, 2023. ### Important Dates -* 2022 Nov 26 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions. -* 2022 Jan 29 - `develop` closed to new PR's. -* 2022 Jan 29 - Call for testers. -* 2022 Feb 12 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes -* 2022 Feb 19 - `develop` is locked, only critical bugfix PR's merged. -* 2022 Feb 24 - `master` is locked, no PR's merged. -* 2022 Feb 26 - Merge `develop` to `master`. -* 2023 Feb 26 - `master` is unlocked. PR's can be merged again. +* 2023 Feb 26 - `develop` is tagged with a new release version. Each push to `master` is subsequently merged to `develop` by GitHub actions. +* 2023 Apr 30 - `develop` closed to new PRs. +* 2023 Apr 30 - Call for testers. +* 2023 May 14 - Last day for merges -- after this point `develop` is locked for testing and accepts only bugfixes +* 2023 May 21 - `develop` is locked, only critical bugfix PRs merged. +* 2023 May 26 - `master` is locked, no PRs merged. +* 2023 May 28 - Merge `develop` to `master`. +* 2023 May 28 - `master` is unlocked. PRs can be merged again. ## What changes will be included? -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. +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. + +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. -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. +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. Criteria for acceptance: * The PR is complete and ready to merge +* GitHub checks for the PR are green whenever possible + * A "red" check may be disregarded by maintainers if the items flagged are unrelated to the change proposed in the PR + * Modifications to existing files should not need to add license headers to pass lint, for instance. + * If it's not directly related to your PR's functionality, prefer avoiding making a change. + +Strongly suggested: + * The PR has a ChangeLog file describing the changes under `<qmk_firmware>/docs/Changelog/20221126`. - * This should be in Markdown format, with a name in the format `PR12345.md`, substituting the digits for your PR's ID. + * This should be in Markdown format, with a name in the format `PR12345.md`, substituting the digits for your PRs ID. * One strong recommendation that the ChangeLog document matches the PR description on GitHub, so as to ensure traceability. ## Checklists @@ -56,7 +60,7 @@ This section documents various processes we use when running the Breaking Change ### 4 Weeks Before Merge -* `develop` is now closed to new PR's, only fixes for current PR's may be merged +* `develop` is now closed to new PRs, only fixes for current PRs may be merged * Post call for testers: message `@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.` @@ -123,12 +127,12 @@ This happens immediately after the previous `develop` branch is merged to `maste * Validate each submodule SHA1 matches the qmk fork, e.g. for ChibiOS: * Go to [qmk/ChibiOS](https://github.com/qmk/ChibiOS) * Compare the commit hash in the above output to the commit hash in the repository - * If there's a mismatch, that repository needs to have its `master` branch updated to match (otherwise Configurator won't work): + * If there's a mismatch, that repository needs to have its `qmk-master` branch updated to match (otherwise Configurator won't work): * `cd lib/chibios` * `git fetch --all` - * `git checkout master` + * `git checkout qmk-master` * `git reset --hard <commit hash>` - * `git push origin master --force-with-lease` + * `git push origin qmk-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!` |