You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
 
 
 
 
 

4.9 KiB

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.

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.

What has been included in past Breaking Changes?

When is the next Breaking Change?

The next Breaking Change is scheduled for May 28, 2022.

Important Dates

What changes will be included?

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:

  • 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.

Checklists

This section documents various processes we use when running the Breaking Changes process.

Creating the develop branch

This happens immediately after the previous develop branch is merged.

  • qmk_firmware git commands

4 Weeks Before Merge

  • develop is now closed to new PR's, only fixes for current PR's may be merged
  • Post call for testers

2 Weeks Before Merge

  • develop is now closed to existing PR merges, only bugfixes for previous merges may be included
  • Post call for testers

1 Week Before Merge

2 Days Before Merge

Day Of Merge

  • qmk_firmware git commands
  • GitHub Actions
  • qmk_firmware git commands

Post-merge operations