57 lines
2.7 KiB
Markdown
57 lines
2.7 KiB
Markdown
# Contributing
|
|
KMK is a community effort and welcomes contributions of code and documentation from people
|
|
of all backgrounds and levels of technical skill. As such, these guidelines should serve
|
|
to make contributing as easy as possible for everyone while maintaining a consistent style.
|
|
|
|
## Contributing Code
|
|
The following guidelines should ensure that any code contributed can be merged in as
|
|
painlessly as possible. If you're unsure how to set up your development environment,
|
|
feel free to join the chat, [#kmkfw:klar.sh on Matrix](https://matrix.to/#/#kmkfw:klar.sh).
|
|
This channel is bridged to Discord [here](https://discord.gg/QBHUUpeGUd) for convenience.
|
|
|
|
### Code Style
|
|
|
|
KMK uses [Black](https://github.com/psf/black) with a Python 3.6 target and,
|
|
[(controversially?)](https://github.com/psf/black/issues/594) single quotes.
|
|
Further code styling is enforced with isort and flake8 with several plugins.
|
|
`make fix-isort fix-formatting` before a commit is a good idea, and CI will fail
|
|
if inbound code does not adhere to these formatting rules. Some exceptions are
|
|
found in `setup.cfg` loosening the rules in isolated cases, notably
|
|
`user_keymaps` (which is *also* not subject to Black formatting for reasons
|
|
documented in `pyproject.toml`).
|
|
|
|
### Tests
|
|
|
|
Unit tests within the `tests` folder mock various CicuitPython modules to allow
|
|
them to be executed in a desktop development environment.
|
|
|
|
Execute tests using the command `python -m unittest`.
|
|
|
|
## Contriburing Documentation
|
|
While KMK welcomes documentation from anyone with and understanding of the issues
|
|
and a willingness to write them up, it's a good idea to familiarize yourself with
|
|
the docs. Documentation should be informative but concise.
|
|
|
|
### Styling
|
|
Docs are written and rendered in GitHub Markdown. A comprehensive guide to GitHub's
|
|
Markdown can be found [here](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax).
|
|
|
|
In particular, KMK's docs should include a title, demarcated with `#`, and subheadings
|
|
should be demarcated with `##`, `###`, and so on. Headings should be short and specific.
|
|
|
|
### Example Code
|
|
Where possible, practical code examples should be included in documentation to help
|
|
new users understand how to implement features. In general, it's better to have a code-
|
|
block with comments inside it rather than multiple blocks of code broken up with
|
|
explanation.
|
|
|
|
Code blocks should be formatted as Python code as follows:
|
|
````
|
|
```python
|
|
print('Hello, world!')
|
|
```
|
|
````
|
|
|
|
Inline code, indicated with `\`backticks\``, should be used when calling out specific
|
|
functions or Python keywords within the body of paragraphs or in lists.
|