varl/qmk_firmware
1
0
Fork 0
forked from forks/qmk_firmware
Code Pull requests Activity

Initial deprecation policy documentation. (#19908)

Browse source
This commit is contained in:
Nick Brassel 2023-03-03 14:16:32 +11:00 committed by GitHub
parent 7ebb8c2dec
commit d1a430b348
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
2 changed files with 51 additions and 1 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
docs/pr_checklist.md
View file

@ -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

44
docs/support_deprecation_policy.md Normal file
View file

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