# QMK Keyboard Guidelines
-Since starting QMK has grown by leaps and bounds, and it's thanks to people like you contributing to and maintaining our community keyboards. As we have grown we have discovered some patterns that work well, and ask that you conform to them to make it easier for other people to make use of your hard work.
+Since starting, QMK has grown by leaps and bounds thanks to people like you who contribute to creating and maintaining our community keyboards. As we have grown we have discovered some patterns that work well, and ask that you conform to them to make it easier for other people to make use of your hard work.
## Naming Your Keyboard/Project
-All keyboard names are in lower case, consisting only of letters, numbers, and underscore (`_`). Names may not begin with an underscore. The names `test`, `keyboard`, and `all` are reserved for make commands and may not be used as a keyboard or subfolder name.
+All keyboard names are in lower case, consisting only of letters, numbers, and underscore (`_`). Names may not begin with an underscore. Forward slash (`/`) is used as a sub-folder separation character.
+
+The names `test`, `keyboard`, and `all` are reserved for make commands and may not be used as a keyboard or subfolder name.
Valid Examples:
* [`qmk_firmware`](https://github.com/qmk/qmk_firmware/tree/master)
* [`keyboards`](https://github.com/qmk/qmk_firmware/tree/master/keyboards)
- * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) <-- this is the organization folder, no `rules.mk` file
- * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) <-- this is a compilable keyboard, it has a `rules.mk` file.
- * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) <-- this is also compilable, it uses `DEFAULT_FOLDER` to specify `rev3` as the default revision
+ * [`clueboard`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard) ← This is the organization directory, there's no `rules.mk` file.
+ * [`60`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/60) ← This is a compilable keyboard, it has a `rules.mk` file.
+ * [`66`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66) ← This is also compilable- it uses `DEFAULT_FOLDER` to specify `rev3` as the default revision.
* [`rev1`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev1) <-- compilable, `make clueboard/66/rev1`
* [`rev2`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev2) <-- compilable, `make clueboard/66/rev2`
* [`rev3`](https://github.com/qmk/qmk_firmware/tree/master/keyboards/clueboard/66/rev3) <-- compilable, `make clueboard/66/rev3` and `make clueboard/66`
### `readme.md`
-All projects need to have a `readme.md` file that explains what the keyboard is, who made it, where it is available, and links to more information. Please follow the [published template](documentation_templates.md#keyboard-readmemd-template).
+All projects need to have a `readme.md` file that explains what the keyboard is, who made it and where it's available. If applicable, it should also contain links to more information, such as the maker's website. Please follow the [published template](documentation_templates.md#keyboard-readmemd-template).
### `config.h`
-All projects need to have a `config.h` file to set things like the processor type, bootloader, USB VID/PID, and other default settings. In general you should use this file to set reasonable defaults for your keyboard that will always work.
+All projects need to have a `config.h` file that sets things like the matrix size, product name, USB VID/PID, description and other settings. In general, use this file to set essential information and defaults for your keyboard that will always work.
### `rules.mk`
-The prescence of this file means this folder is a keyboard target, and can be used in make commands. This is where you setup the build environment for your keyboard and configure the default set of features. You should turn on only those features you have a need for and leave the rest turned off, users can enable them in their keymap `rules.mk`.
+The prescence of this file means this folder is a keyboard target, and can be used in make commands. This is where you setup the build environment for your keyboard and configure the default set of features.
### `<keyboard_name.c>`
## Image/Hardware Files
-In an effort to keep the repo size down, we're no longer accepting images of any format in the repo, with few exceptions. Hosting them elsewhere (imgur) and linking them in the `readme.md` is the preferred method.
+In an effort to keep the repo size down we're no longer accepting binary files of any format, with few exceptions. Hosting them elsewhere (such as <https://imgur.com>) and linking them in the `readme.md` is preferred.
Any sort of hardware file (plate, case, pcb) can't be stored in qmk_firmware, but we have the [qmk.fm repo](https://github.com/qmk/qmk.fm) where such files (as well as in-depth info) can be stored and viewed on [qmk.fm](http://qmk.fm). Downloadable files are stored in `/<keyboard>/` (name follows the same format as above) which are served at `http://qmk.fm/<keyboard>/`, and pages are generated from `/_pages/<keyboard>/` which are served at the same location (.md files are generated into .html files through Jekyll). Check out the `lets_split` directory for an example.
projects / qmk_firmware.git / blobdiff