ππ First off, thanks for taking the time to read this and contribute! ππ
Third-party contributions help us grow and improve QMK. We want to make the pull request and contribution process useful and easy for both contributors and maintainers. To this end we've put together some guidelines for contributors to help your pull request be accepted without major changes.
If you'd like to ask questions about QMK you can do so on the OLKB Subreddit or on Discord.
Please keep these things in mind:
QMK is largely written in C, with specific features and parts written in C++. It targets embedded processors found in keyboards, particularly AVR (LUFA) and ARM (ChibiOS). If you are already well versed in Arduino programming you'll find a lot of the concepts and limitations familiar. Prior experience with Arduino is not required to successfully contribute to QMK.
If you need help you can open an issue or chat on Discord.
Never made an open source contribution before? Wondering how contributions work in QMK? Here's a quick rundown!
your-GitHub-username/qmk_firmware.git clone https://github.com/github-username/repository-name.git.git checkout -b branch-name-here.git add insert-paths-of-changed-files-here to add the file contents of the changed files to the "snapshot" git uses to manage the state of the project, also known as the index.git commit -m "Insert a short message of the changes made here" to store the contents of the index with a descriptive message.git push origin branch-name-here.Most of our style is pretty easy to pick up on. If you are familiar with either C or Python you should not have too much trouble with our local styles.
We have a few different types of changes in QMK, each requiring a different level of rigor. We'd like you to keep the following guidelines in mind no matter what type of change you're making.
qmk_firmware repo. This will help minimize CI failures that may not occur for you when compiling locally.git diff --check before committing.make keyboard:keymap does not return any errors.make keyboard:all does not return any errors.make all does not return any errors.Adjust the fronzlebop for the kerpleplork\n\nThe kerpleplork was intermittently failing with error code 23. The root cause was the fronzlebop setting, which causes the kerpleplork to activate every N iterations.\n\nLimited experimentation on the devices I have available shows that 7 is high enough to avoid confusing the kerpleplork, but I'd like to get some feedback from people with ARM devices to be sure.Documentation is one of the easiest ways to get started contributing to QMK. Finding places where the documentation is wrong or incomplete and fixing those is easy! We also very badly need someone to edit our documentation, so if you have editing skills but aren't sure where or how to jump in please reach out for help!
You'll find all our documentation in the qmk_firmware/docs directory, or if you'd rather use a web based workflow you can click the "Edit this page" link at the bottom of each page on https://docs.qmk.fm/.
When providing code examples in your documentation, try to observe naming conventions used elsewhere in the docs. For example, standardizing enums as my_layers or my_keycodes for consistency:
enum my_layers {\n _FIRST_LAYER,\n _SECOND_LAYER\n};\n\nenum my_keycodes {\n FIRST_LAYER = SAFE_RANGE,\n SECOND_LAYER\n};Before opening a pull request, you can preview your changes if you have set up the development environment by running this command from the qmk_firmware/ folder:
qmk docs\nand navigating to http://localhost:5173/.
Keyboards are the raison d'Γͺtre for QMK. Some keyboards are community maintained, while others are maintained by the people responsible for making a particular keyboard. The readme.md should tell you who maintains a particular keyboard. If you have questions relating to a particular keyboard you can Open An Issue and tag the maintainer in your question.
We also ask that you follow these guidelines:
readme.md using the template.default keymap that provides a clean slate for users to start with when creating their own keymaps..c/.h file after the immediate parent folder, eg /keyboards/<kb1>/<kb2>/<kb2>.[ch]Makefiles in your keyboard folder (they're no longer used)%YOUR_NAME%)Before you put a lot of work into building your new feature you should make sure you are implementing it in the best way. You can get a basic understanding of QMK by reading Understanding QMK, which will take you on a tour of the QMK program flow. From here you should talk to us to get a sense of the best way to implement your idea. There are two main ways to do this:
Feature and Bug Fix PRs affect all keyboards. We are also in the process of restructuring QMK. For this reason it is especially important for significant changes to be discussed before implementation has happened. If you open a PR without talking to us first please be prepared to do some significant rework if your choices do not mesh well with our planned direction.
Here are some things to keep in mind when working on your feature or bug fix.
docs/, either as a new file or as part of an existing file. If you don't document it other people won't be able to benefit from your hard work.We also ask that you follow these guidelines:
To maintain a clear vision of how things are laid out in QMK we try to plan out refactors in-depth and have a collaborator make the changes. If you have an idea for refactoring, or suggestions, open an issue, we'd love to talk about how QMK can be improved.
Our Code of Conduct means that you are responsible for treating everyone on the project with respect and courtesy regardless of their identity. If you are the victim of any inappropriate behavior or comments as described in our Code of Conduct, we are here for you and will do the best to ensure that the abuser is reprimanded appropriately, per our code.
', 47); const _hoisted_48 = [ _hoisted_1 ]; function _sfc_render(_ctx, _cache, $props, $setup, $data, $options) { return openBlock(), createElementBlock("div", null, _hoisted_48); } const contributing = /* @__PURE__ */ _export_sfc(_sfc_main, [["render", _sfc_render]]); export { __pageData, contributing as default };