1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
|
# 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 conduct@zmk.dev.
[code-of-conduct]: https://github.com/zmkfirmware/zmk/blob/main/CODE_OF_CONDUCT.md
## 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](https://discord.com/channels/719497620560543766/719909884769992755) 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](https://zmk.dev/docs/faq).
- Check the [Troubleshooting Guide](https://zmk.dev/docs/troubleshooting) for answers.
- Search the [open issues](https://github.com/zmkfirmware/zmk/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](https://zmk.dev/docs/faq#what-is-a-board) 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](https://zmk.dev/docs/dev-guide-usb-logging)
## Testing
The `help wanted` label will be added to any [pull requests](https://github.com/zmkfirmware/zmk/pulls?q=is%3Aopen+is%3Apr+label%3A%22help+wanted%22)
or [issues](https://github.com/zmkfirmware/zmk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22)
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/](https://github.com/zmkfirmware/zmk/tree/main/docs) subdirectory.
- The documentation is maintained using [Docusaurus V2](https://v2.docusaurus.io/docs/).
- 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.
### Formatting
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`.
### Linting
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.
## Code Contributions
### Development Setup
To get your development environment setup going, start at the
[basic setup](https://zmk.dev/docs/development/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.
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`.
### Commit Messages
The ZMK project is working towards, but not yet enforcing, the use of
[conventional commits](https://www.conventionalcommits.org/en/v1.0.0/) 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`](https://github.com/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.
[discord-invite]: https://zmk.dev/community/discord/invite
|
