This is the planning document and checklist for the Aug 2019 QMK Breaking change.

What is a Breaking Change?

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.

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 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 Aug 02, 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 no later than Aug 02. After Aug 02 no new breaking changes will be accepted.

Criteria for acceptance:

• PR is complete and ready to merge before Aug 02.
• PR has a ChangeLog

Important Dates

• 2019 Jul 05 - future_unformatted and future are created. They will be rebased weekly.
• 2019 Aug 02 - future closed to new PR's.
• 2019 Aug 02 - Call for testers.
• 2019 Aug 28 - master is locked, no PR's merged.
• 2019 Aug 30 - Merge future to master.
• 2019 Aug 31 - master is unlocked. PR's can be merged again.
• 2019 Sep 06 - Breaking bugfixes closed.

Clang Format

As part of this breaking change we will also be reformatting all of the core code to comply with our .clang-format rules. This will be a little tricky since we want to test it but we also want to make merging new fixes as painless as possible.

To accomplish this we will have a future and a future-unformatted branch. Bug fixes will be applied to the future-unformatted branch.

A preview of the changes is available in the clang-format branch.

Running clang-format

This is how we run clang-format

dirs="drivers quantum tests tmk_core"
(find $dirs -name \*.c; 
  find $dirs -name \*.h; 
  find $dirs -name \*.cpp) | \
grep -v tmk_core/protocol/usb_hid | \
xargs clang-format -i

Checklists

Rebase future from master

Process:

cd qmk_firmware
git checkout future_unformatted
git pull --ff-only
git rebase origin/master  # Skip if merging PR to future_unformatted
git push --force  # Skip if merging PR to future_unformatted
git checkout future
git reset --hard HEAD^
git rebase future_unformatted
# Run the command from "Running clang-format" above
git commit -a -m'clang-format changes'
git push --force

• 2019 Jul 12
• 2019 Jul 19
• [ ] 2019 Jul 26
• 2019 Aug 02
• 2019 Aug 09
• 2019 Aug 16
• 2019 Aug 23

Merge a PR into future

This is the process to merge a breaking change or bugfix for an already merged breaking change.

• Switch PR to future_unformatted branch
• Merge PR
• Follow process described in Rebase future from master

8 Weeks Before Merge (Jul 5)

• qmk_firmware git commands

  • git checkout master
  • git pull --ff-only
  • git checkout -b future_unformatted
  • 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 2019 Aug 30 Breaking Change'
  • git checkout -b future
  • git tag breakpoint_2019_08_30
  • git tag <next_version> # In this case: 0.6.412
  • Run the command from Running clang-format
  • git commit -m'clang-format changes'
  • git push origin future
  • git push origin future_unfortmatted
  • git push --tags

• GitHub Actions

  • Switch all breaking_change PR's to future_unformatted
  • Any that have a ChangeLog entry may be merged immediately.

4 Weeks Before Merge (Aug 2)

• future is now closed to new PR's, only fixes for current PR's may be merged
• Post call for testers
  • Discord
  • GitHub PR
  • https://reddit.com/r/olkb

1 Week Before Merge (Aug 23)

• Announce that master will be closed Aug 28-31
  • Discord
  • GitHub PR
  • https://reddit.com/r/olkb

2 Days Before Merge (Aug 28)

• Announce that master is closed until Aug 31
  • Discord
  • GitHub PR
  • https://reddit.com/r/olkb

Day Of Merge (Aug 30)

• qmk_firmware git commands
  • git checkout future
  • git pull --ff-only
  • git rebase origin/master
  • Edit readme.md
    • Remove the notes about future
  • Roll up the ChangeLog into one file.
  • git commit -m 'Merge point for 2019 Aug 30 Breaking Change'
  • git push origin future
• Github Actions
  • Create a PR for future
  • Make sure travis comes back clean
  • Merge PR
  • Wait for travis post-merge job to complete
  • Increment the "minor" portion of the version number
    • git checkout master
    • git pull --ff-only
    • Find the last tag, this is <travis_version>
      • git tag --sort=-creatordate --no-column --list '*.*.*' | grep -E -m1 '^[0-9]+\.[0-9]+\.[0-9]+$'
    • Create <incremented_version> but incrementing the middle number by one and changing the third number to 0.
    • git tag <incremented_version> <travis_version>^{}
    • git tag -d <travis_version>
    • git push origin :refs/tags/<travis_version>
    • git push --tags