diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/breaking_changes.md | 8 | ||||
| -rw-r--r-- | docs/chibios_upgrade_instructions.md | 17 | ||||
| -rw-r--r-- | docs/pr_checklist.md | 8 | ||||
| -rw-r--r-- | docs/support_deprecation_policy.md | 44 |
4 files changed, 70 insertions, 7 deletions
diff --git a/docs/breaking_changes.md b/docs/breaking_changes.md index 6e0856d462..919c443123 100644 --- a/docs/breaking_changes.md +++ b/docs/breaking_changes.md @@ -34,7 +34,7 @@ The next Breaking Change is scheduled for May 28, 2023. ## What changes will be included? -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 prioritised for review. +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. @@ -127,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!` diff --git a/docs/chibios_upgrade_instructions.md b/docs/chibios_upgrade_instructions.md index 14afe2c743..62f16d0d25 100644 --- a/docs/chibios_upgrade_instructions.md +++ b/docs/chibios_upgrade_instructions.md @@ -4,7 +4,7 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra ## Getting ChibiOS -* `svn` Initialisation: +* `svn` Initialization: * Only needed to be done once * You might need to separately install `git-svn` package in your OS's package manager * `git svn init --stdlayout --prefix='svn/' http://svn.osdn.net/svnroot/chibios/` @@ -21,7 +21,7 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra ## Getting ChibiOS-Contrib -* `git` Initialisation: +* `git` Initialization: * `git clone git@github.com:qmk/ChibiOS-Contrib` * `git remote add upstream https://github.com/ChibiOS/ChibiOS-Contrib` * `git checkout -b chibios-20.3.x upstream/chibios-20.3.x` @@ -57,3 +57,16 @@ ChibiOS and ChibiOS-Contrib need to be updated in tandem -- the latter has a bra * `git commit -am 'Update ChibiOS to 99.9.9'` * `git push --set-upstream origin chibios-version-bump` * Make a PR to qmk_firmware with the new branch + +## When merging a PR containing an upgrade of ChibiOS/ChibiOS-Contrib: + +* Update the target branch if the merge target was `master`: + * `git checkout qmk-master` + * `git reset --hard develop_YYYY_qN` + * `git push origin qmk-master --force-with-lease` +* Update the target branch if the merge target was `develop`: + * `git checkout qmk-develop` + * `git reset --hard develop_YYYY_qN` + * `git push origin qmk-develop --force-with-lease` + +Note that when merging `develop` to `master`, the first workflow should still be followed. diff --git a/docs/pr_checklist.md b/docs/pr_checklist.md index 683685bda8..6fe94c0db1 100644 --- a/docs/pr_checklist.md +++ b/docs/pr_checklist.md @@ -145,7 +145,13 @@ Also, specific to ChibiOS: ## Core PRs :id=core-pr -- must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline +- all core PRs must now target `develop` branch, which will subsequently be merged back to `master` on the breaking changes timeline +- as indicated above, the smallest set of changes to core components should be included in each PR + - PRs containing multiple areas of change will be asked to be split up and raised separately + - keyboard and keymap changes should only be included if they affect base keyboard builds, or the default-like `default`, `via`, `default_????` keymaps etc. + - keymap modifications for anything other than the default-like keymaps **should not be included in the initial PR** in order to simplify the review process + - the core PR submitter should submit a followup PR affecting other keymaps after initial PR merge + - large-scale refactoring or consolidation PRs that affect other keymaps (such as renaming keycodes) should always be raised separately - any new boards adding support for new hardware now requires a corresponding test board under `keyboards/handwired/onekey` - for new MCUs, a new "child" keyboard should be added that targets your newly-added MCU, so that builds can be verified - for new hardware support such as display panels, core-side matrix implementations, or other peripherals, an associated keymap should be provided diff --git a/docs/support_deprecation_policy.md b/docs/support_deprecation_policy.md new file mode 100644 index 0000000000..f7107dfc89 --- /dev/null +++ b/docs/support_deprecation_policy.md @@ -0,0 +1,44 @@ +# Feature support policies + +## System Constraints + +In general, feature development is encouraged to support as many hardware configurations as possible. Depending on system constraints this may not always be achievable, and is usually bound by microcontroller flash and RAM capabilities. + +The most frequently-hit constraint is the amount of code that can be flashed onto an ATmega32U4 -- users almost always need to pick and choose included functionality due to the size constraints. + +!> [Squeezing AVR](https://docs.qmk.fm/#/squeezing_avr) has some steps that users can take in order to minimise the overall firmware size, which in some cases enables the ability for users to include other desired features. + +## Deprecation & Removal Policy + +QMK Firmware strives for innovation wherever possible. With ongoing feature development and other improvements made to the codebase, sometimes the retirement of outdated, under-utilised, or limited-value functionality is selected for deprecation and subsequent removal. + +The intent behind feature deprecation is to maintain and/or improve quality. As a result, perpetually supporting under-utilised features would negatively impact the QMK team's ability to improve other areas of QMK Firmware. + +There may be several motivations behind the deprecation or removal of functionality (keeping in mind that this list is not exhaustive): + +* Better alternatives have already been implemented +* Lack of adherence to standards +* Poor support from code owners or upstream maintainers +* Poor design +* Hardware constraints +* Minimal use within the QMK Firmware repository +* Copyright disputes +* Bit-rot + +When a feature is selected for deprecation, future changes to that area will cease to be developed by the QMK team, and Pull Requests submitted against those areas will be declined. + +?> As QMK does not gather metrics from its users, the only way the QMK team can gauge the level of usage is to refer to the main QMK Firmware repository -- searching through forks is not practical due to the sheer number of them. + +### How much advance notice will be given? + +Disregarding emergencies or other high-risk concerns, deprecation of large features or entire subsystems within QMK will be communicated on the `develop` branch at least one breaking changes cycle (3 months) before removal. Advance notice may be extended for higher impact features, and is at the discretion of the QMK team. + +Smaller features may be removed within a breaking changes cycle, and will generally be based on the level of use within the repository. Features with minimal use may be selected for removal at any time on the `develop` branch. + +Third-party software libraries leveraged by QMK are generally forked to mitigate disappearance upstream. If the upstream repository is removed, it will generally be replaced when practical, or dependent features will be removed as per the normal deprecation policy. + +### How will deprecation be communicated? + +Every breaking changes merge from `develop` into `master` is accompanied by a changelog document -- intended and completed deprecations will be communicated here. + +In addition, wherever possible warnings will be issued during firmware compilation when deprecated features are still being used. |