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.
All community members are expected to abide by the Code of Conduct. For any and all conduct inquiries or concerns, please contact conduct@zmk.dev.
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
- Testing
- Documentation
- 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.
- Review the Frequently Asked Questions.
- Check the Troubleshooting Guide for answers.
- Search the open issues for an existing report that matches your problem.
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
The help wanted
label will be added to any pull requests
or issues
where user testing can assist the ZMK contributors to verify fixes, confirm
bugs, etc.
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:
- Logs
- Screenshots
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
docs/
directory, runnpm ci
and thennpm start
. - Enhancements should be submitted as pull requests to the
main
branch of ZMK.
ZMK uses 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
, pre-commit install
.
This repository utilizes ESLint for code linting to ensure consistent code style and identify potential errors or bugs early in the development process.
You can run ESLint with npm run lint
to verify your changes.
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.
ZMK uses 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
on save.
You can setup git to run clang-format
automatically when you commit by installing the pre-commit hooks: pip3 install pre-commit
, pre-commit install
.
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
main
branch of thezmkfirmware/zmk
repository. - 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.