poz/qmk_firmware
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

add Breaking Change PR Instructions doc

Browse source
This commit is contained in:
James Young 2020-01-25 13:53:24 -08:00 committed by skullydazed
parent 9ff61601e3
commit d603e94f68
2 changed files with 37 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
docs/_summary.md
View file

@ -18,6 +18,7 @@
* [Getting Help](getting_started_getting_help.md)
* [Breaking Changes](breaking_changes.md)
* [Breaking Changes Instructions](breaking_changes_instructions.md)
* [2019 Aug 30](ChangeLog/20190830.md)
* [FAQ](faq.md)

36
docs/breaking_changes_instructions.md Normal file
View file

@ -0,0 +1,36 @@
# Breaking Changes: My Pull Request Was Flagged
A QMK member may have replied to your pull request stating that your submission is a breaking change. In their judgment, the changes you have proposed have greater implications for either QMK, or its users.
Some things that may cause a pull request to be flagged are:
- **Edits to User Keymaps**
A user may submit their keymap to QMK, then some time later open a pull request with further updates, only to find it can't be merged because it was edited in the `qmk/qmk_firmware` repository. As not all users are proficient at using Git or GitHub, the user may find themself unable to fix the issue on their own.
- **Changes to Expected Behavior**
Changes to QMK behavior may cause users to believe their hardware or QMK is broken if they flash new firmware that incorporates changes to existing QMK features, and find themselves without a means to restore the desired behavior.
- **Changes Requiring User Action**
Changes may also require action to be taken by users, such as updating a toolchain or taking some action in Git.
- **Changes Necessitating Increased Scrutiny**
On occasion, a submission may have implications for QMK as a project. This could be copyright/licensing issues, coding conventions, large feature overhauls, "high-risk" changes that need wider testing by our community, or something else entirely.
## What Do I Do?
If it is determined that your submission is a breaking change, there are a few things you can do to smooth the process:
### Contribute a ChangeLog Entry
We require submissions that go through the Breaking Change process to include a changelog entry. The entry should be a short summary of the changes your pull request makes – [each section here started as a changelog](ChangeLog/20190830.md "n.b. This should link to the 2019 Aug 30 Breaking Changes doc - @noroadsleft").
Your changelog should be located at `docs/ChangeLog/YYYYMMDD/PR####.md`, where `YYYYMMDD` is the date on which QMK's breaking change branch – usually named `future` – will be merged into the `master` branch, and `####` is the number of your pull request.
If your submission requires action on the part of users, your changelog should instruct users what action(s) must be taken, or link to a location that does so.
### Document Your Changes
Understanding the purpose for your submission, and possible implications or actions it will require can make the review process more straightforward. A changelog may suffice for this purpose, but more extensive changes may require a level of detail that is ill-suited for a changelog.
Commenting on your pull request and being responsive to questions, comments, and change requests is much appreciated.
### Ask for Help
Having your submission flagged may have caught you off guard. If you find yourself intimidated or overwhelmed, let us know. Comment on your pull request, or [reach out to the QMK team on Discord](https://discord.gg/Uq7gcHh).