Contributing To ZMK
Thanks for taking an interest in contributing to ZMK! After reading through the documentation, if you have any questions, please come join us on the ZMK Discord Server.
Code of Conduct
All community members are expected to abide by the Code of Conduct. For any and all conduct inquiries or concerns, please contact firstname.lastname@example.org.
How Can I Contribute
There are many different ways that you can contribute to ZMK, several of which require no coding abilities. These include:
- Chat Support
- Issue Reporting/Commenting
- Code Contributions
Providing user support on the ZMK Discord Server is a great way to help the project. In particular, answering questions in the #help channel is incredibly appreciated.
Often, you might encounter unexpected behavior when building, flashing, or running the ZMK firmware. Submitting or commenting on issues on GitHub is a great way to contribute to the ZMK project.
Before Submitting a Report
- Review the Frequently Asked Questions.
- Check the Troubleshooting Guide for answers.
- Search the open issues for an existing report that matches your problem.
Opening A Report
To open a report:
- Head to https://github.com/zmkfirmware/zmk/issues/new
- Provide an accurate summary of the issue in the title.
- Provide as much detail as you can about the issue including:
- What board/shield you are using.
- A link to the user repository, if you used it to build your firmware.
- Exact steps to reproduce the problem.
- Any relevant screenshots or logs
help wanted label will be added to any pull requests
where user testing can assist the ZMK contributors to verify fixes, confirm
When providing testing feedback, please provide:
- Exact steps used to test
- Any hardware details relevant to testing
- Pass/fail summary for testing.
- Full details of any failures, including:
Quality documentation is a huge part of what makes a successful project. Contributions to add documentation to areas not currently covered are greatly appreciated.
- The documentation site can be found in the main ZMK repo, in the docs/ subdirectory.
- The documentation is maintained using Docusaurus V2.
- To get started, from the
npm ciand then
- Enhancements should be submitted as pull requests to the
mainbranch of ZMK.
prettier to format documentation files. You can run prettier with
npm run prettier:format.
You can setup git to run prettier automatically when you commit by installing the pre-commit hooks:
pip3 install pre-commit,
To get your development environment setup going, start at the basic setup docs, and make sure you can build and flash your own locally built firmware.
clang-format to ensure consist formatting for our source code. Before submitting your
changes, make sure you've manually run
clang-format, or have your IDE configured to auto-format
You can setup git to run
clang-format automatically when you commit by installing the pre-commit hooks:
pip3 install pre-commit,
The ZMK project is working towards, but not yet enforcing, the use of conventional commits for commit messages.
Further documentation and details will be provided here soon.
When opening a pull request with your changes, please:
- Submit the PR to the
mainbranch of the
- Use a descriptive title that summarizes the change.
- In the description, include:
- References to any open issues fixed by the PR.
- Feature added by the PR
- Bugs fixed by the PR.
- Testing you've performed locally.
- Requested testing by reviewers or testers.
- Screenshots or logs that support understanding the change.