chore: Add initial docs.* Closes #23

Pete Johanson 2020-09-19 23:18:48 -04:00
parent c0806d27f1
commit aa1f9bad6e
1 changed files with 120 additions and 0 deletions

120 Normal file
View File

@ -0,0 +1,120 @@
# 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][discord-invite].
## Code of Conduct
All community members are expected to abide by the [Code of Conduct][code-of-conduct].
For any and all conduct inquiries or concerns, please contact
## 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
- Testing
- Documentation
- Code Contributions
## Chat Support
Providing user support on the [ZMK Discord Server][discord-invite] is a great way to help the
project. In particular, answering questions in the [#help]( channel is incredibly appreciated.
## Issue Reporting/Commenting
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
- 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](
## Testing
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
## Documentation
Quality documentation is a huge part of what makes a successful project. Contributions to add
documentation to areas not currently covered are greatly appreciated.
### Contributing
- 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, run `npm ci` and then `npm start`.
- Enhancements should be submitted as pull requests to the `main` branch of ZMK.
## Code Contributions
### Development Setup
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.
### Formatting
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.
### Commit Messages
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.
### Pull Requests
When opening a pull request with your changes, please:
- Submit the PR to the `main` branch of the
[`zmkfirmware/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.