diff --git a/docs/ChangeLog/20190830.md b/docs/ChangeLog/20190830.md new file mode 100644 index 000000000..88d7192cb --- /dev/null +++ b/docs/ChangeLog/20190830.md @@ -0,0 +1,47 @@ +# QMK Breaking Change - 2019 Aug 30 + +Four times a year QMK runs a process for merging Breaking Changes. A Breaking Change is any change which modifies how QMK behaves in a way that is incompatible or potentially dangerous. We limit these changes to 4 times per year so that users can have confidence that updating their QMK tree will not break their keymaps. + +This document marks the inaugural Breaking Change merge. A list of changes follows. + +## LUFA USB descriptor cleanup + +* Some code cleanups related to the USB HID descriptors on AVR keyboards, to make them easier to read and understand +* More information: see https://github.com/qmk/qmk_firmware/pull/4871 +* No behaviour changes anticipated and no keymaps modified + +## Migrating `ACTION_LAYER_MOMENTARY()` entries in `fn_actions` to `MO()` keycodes + +* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` +* The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity +* All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features + +## Update Atreus to current code conventions + +* Duplicate include guards have bypassed the expected header processing behavior +* All keymaps affected are recommended to remove duplication of `/config.h` to `/keymaps//config.h` and only provide overrides at the keymap level + +## Backport changes to keymap language files from ZSA fork + +* Fixes an issue in the `keymap_br_abnt2.h` file that includes the wrong source (`keymap_common.h` instead of `keymap.h`) +* Updates the `keymap_swedish.h` file to be specific to swedish, and not just "nordic" in general. +* Any keymaps using this will need to remove `NO_*` and replace it with `SE_*`. + +## Update repo to use LUFA as a git submodule + +* `/lib/LUFA` removed from the repo +* LUFA set as a submodule, pointing to qmk/lufa +* This should allow more flexibility with LUFA, and allow us to keep the sub-module up to date, a lot more easily. It was ~2 years out of date with no easy path to fix that. This prevents that from being an issue in the future + +## Migrating `ACTION_BACKLIGHT_*()` entries in `fn_actions` to `BL_` keycodes + +* `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` +* All keymaps using these actions have had the relevant `KC_FN*` keys replaced with the equivalent `BL_*` keys +* If you currently use `KC_FN*` you will need to replace `fn_actions` with the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features + +## Remove `KC_DELT` alias in favor of `KC_DEL` + +* `KC_DELT` was a redundant, undocumented alias for `KC_DELETE` +* It has been removed and all its uses replaced with the more common `KC_DEL` alias +* Around 90 keymaps (mostly for ErgoDox boards) have been modified as a result + diff --git a/docs/ChangeLog/20190830/PR4871.md b/docs/ChangeLog/20190830/PR4871.md deleted file mode 100644 index e4ea171d7..000000000 --- a/docs/ChangeLog/20190830/PR4871.md +++ /dev/null @@ -1,4 +0,0 @@ -* LUFA USB descriptor cleanup - * Some code cleanups related to the USB HID descriptors on AVR keyboards, to make them easier to read and understand - * More information: see https://github.com/qmk/qmk_firmware/pull/4871 - * No behaviour changes anticipated and no keymaps modified diff --git a/docs/ChangeLog/20190830/PR5176.md b/docs/ChangeLog/20190830/PR5176.md deleted file mode 100644 index c01b2cb1e..000000000 --- a/docs/ChangeLog/20190830/PR5176.md +++ /dev/null @@ -1,4 +0,0 @@ -* Migrating `ACTION_LAYER_MOMENTARY()` entries in `fn_actions` to `MO()` keycodes - * `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` - * The end result of removing this obsolete feature should result in a decent reduction in firmware size and code complexity - * All keymaps affected are recommended to switch away from `fn_actions` in favour of the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features diff --git a/docs/ChangeLog/20190830/PR5849.md b/docs/ChangeLog/20190830/PR5849.md deleted file mode 100644 index 24dadc1f2..000000000 --- a/docs/ChangeLog/20190830/PR5849.md +++ /dev/null @@ -1,3 +0,0 @@ -* Update Atreus to current code conventions - * Duplicate include guards have bypassed the expected header processing behavior - * All keymaps affected are recommended to remove duplication of `/config.h` to `/keymaps//config.h` and only provide overrides at the keymap level \ No newline at end of file diff --git a/docs/ChangeLog/20190830/PR6198.md b/docs/ChangeLog/20190830/PR6198.md deleted file mode 100644 index 9141ac250..000000000 --- a/docs/ChangeLog/20190830/PR6198.md +++ /dev/null @@ -1,4 +0,0 @@ -* Backport changes to keymap language files from ZSA fork - * Fixes an issue in the `keymap_br_abnt2.h` file that includes the wrong source (`keymap_common.h` instead of `keymap.h`) - * Updates the `keymap_swedish.h` file to be specific to swedish, and not just "nordic" in general. - * Any keymaps using this will need to remove `NO_*` and replace it with `SE_*`. diff --git a/docs/ChangeLog/20190830/PR6245.md b/docs/ChangeLog/20190830/PR6245.md deleted file mode 100644 index 62e71eee9..000000000 --- a/docs/ChangeLog/20190830/PR6245.md +++ /dev/null @@ -1,5 +0,0 @@ -* Update repo to use LUFA as a git submodule - * `/lib/LUFA` removed from the repo - * LUFA set as a submodule, pointing to qmk/lufa - * This should allow more flexibility with LUFA, and allow us to keep the sub-module up to date, a lot more easily. It was ~2 years out of date with no easy path to fix that. This prevents that from being an issue in the future - diff --git a/docs/ChangeLog/20190830/PR6299.md b/docs/ChangeLog/20190830/PR6299.md deleted file mode 100644 index 43fb9e031..000000000 --- a/docs/ChangeLog/20190830/PR6299.md +++ /dev/null @@ -1,4 +0,0 @@ -* Migrating `ACTION_BACKLIGHT_*()` entries in `fn_actions` to `BL_` keycodes - * `fn_actions` is deprecated, and its functionality has been superseded by direct keycodes and `process_record_user()` - * All keymaps using these actions have had the relevant `KC_FN*` keys replaced with the equivalent `BL_*` keys - * If you currently use `KC_FN*` you will need to replace `fn_actions` with the [custom keycode](https://docs.qmk.fm/#/custom_quantum_functions) and [macro](https://docs.qmk.fm/#/feature_macros) features diff --git a/docs/ChangeLog/20190830/PR6327.md b/docs/ChangeLog/20190830/PR6327.md deleted file mode 100644 index 233e10e09..000000000 --- a/docs/ChangeLog/20190830/PR6327.md +++ /dev/null @@ -1,4 +0,0 @@ -* Remove `KC_DELT` alias in favor of `KC_DEL` - * `KC_DELT` was a redundant, undocumented alias for `KC_DELETE` - * It has been removed and all its uses replaced with the more common `KC_DEL` alias - * Around 90 keymaps (mostly for ErgoDox boards) have been modified as a result diff --git a/docs/_summary.md b/docs/_summary.md index 95286ff46..d7a49a968 100644 --- a/docs/_summary.md +++ b/docs/_summary.md @@ -13,6 +13,9 @@ * [How to Use Github](getting_started_github.md) * [Getting Help](getting_started_getting_help.md) +* [Breaking Changes](breaking_changes.md) + * [2019 Aug 30](ChangeLog/20190830.md) + * [FAQ](faq.md) * [General FAQ](faq_general.md) * [Build/Compile QMK](faq_build.md) diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md new file mode 100644 index 000000000..b193b12da --- /dev/null +++ b/docs/breaking_changes.md @@ -0,0 +1,108 @@ +# 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. + +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? + +* [2019 Aug 30](ChangeLog/20190830.md) + +## When is the next Breaking Change? + +The next Breaking Change is scheduled for Nov 29. + +### Important Dates + +* [ ] 2019 Oct 04 - `future` is created. It will be rebased weekly. +* [ ] 2019 Nov 01 - `future` closed to new PR's. +* [ ] 2019 Nov 01 - Call for testers. +* [ ] 2019 Nov 27 - `master` is locked, no PR's merged. +* [ ] 2019 Nov 29 - Merge `future` to `master`. +* [ ] 2019 Nov 30 - `master` is unlocked. PR's 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 `future` 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 `future` closes. After `future` closes no new breaking changes will be accepted. + +Criteria for acceptance: + +* PR is complete and ready to merge +* PR has a ChangeLog + +# Checklists + +This section documents various processes we use when running the Breaking Changes process. + +## Rebase `future` from `master` + +This is run every Friday while `future` is open. + +Process: + +``` +cd qmk_firmware +git checkout master +git pull --ff-only +git checkout future +git rebase master +git push --force +``` + +## 8 Weeks Before Merge + +* `qmk_firmware` git commands + * [ ] `git checkout master` + * [ ] `git pull --ff-only` + * [ ] `git checkout -b future` + * [ ] 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 Breaking Change'` + * [ ] `git tag breakpoint___
` + * [ ] `git tag ` # Prevent the breakpoint tag from confusing version incrementing + * [ ] `git push origin future` + * [ ] `git push --tags` +* GitHub Actions + * [ ] Switch all [breaking_change PR's](https://github.com/qmk/qmk_firmware/pulls?utf8=%E2%9C%93&q=is%3Apr+is%3Aopen+label%3Abreaking_change) to `future` + * [ ] Any that have a ChangeLog entry may be merged immediately. + +## 4 Weeks Before Merge + +* `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 + +* Announce that master will be closed from <2 Days Before> to + * [ ] 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 + * [ ] `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 Breaking Change'` + * [ ] `git push origin future` +* Github Actions + * [ ] Create a PR for `future` + * [ ] Make sure travis comes back clean + * [ ] Merge `future` PR diff --git a/readme.md b/readme.md index 203017834..b08c675e4 100644 --- a/readme.md +++ b/readme.md @@ -7,14 +7,6 @@ [![GitHub contributors](https://img.shields.io/github/contributors/qmk/qmk_firmware.svg)](https://github.com/qmk/qmk_firmware/pulse/monthly) [![GitHub forks](https://img.shields.io/github/forks/qmk/qmk_firmware.svg?style=social&label=Fork)](https://github.com/qmk/qmk_firmware/) -# NOTICE: THIS IS A TESTING BRANCH - -This is the `breaking_changes` branch for Aug 2019. You can [read more in the tracking issue](https://github.com/qmk/qmk_firmware/issues/6146). - -We encourage you to try this branch out and see if there are any bugs. Our goal is to merge this branch to `master` on Aug 30. Please [report any bugs](https://github.com/qmk/qmk_firmware/issues/new?template=bug_report.md) you find. - -Original readme.md continues: - This is a keyboard firmware based on the [tmk\_keyboard firmware](https://github.com/tmk/tmk_keyboard) with some useful features for Atmel AVR and ARM controllers, and more specifically, the [OLKB product line](https://olkb.com), the [ErgoDox EZ](https://ergodox-ez.com) keyboard, and the [Clueboard product line](https://clueboard.co). ## Documentation