1985712637
correct usage sourced from: * websites of respective trademark holders * Wiktionary * Wikipedia
69 lines
3.2 KiB
Markdown
69 lines
3.2 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.
|
|
|
|
**NOTE:** before committing code, run `make fix-isort fix-formatting test` to
|
|
reduce workload for the project's maintainers and prevent the CI pipeline from
|
|
failing.
|
|
|
|
There are some limited exceptions to the code formatting rules, which can be
|
|
found in `setup.cfg`, notably around `user_keymaps` (which are also not subject
|
|
to Black formatting as documented in `pyproject.toml`)
|
|
|
|
### Tests
|
|
|
|
Unit tests within the `tests` folder mock various CircuitPython modules to allow
|
|
them to be executed in a desktop development environment.
|
|
|
|
Execute tests using the command `python -m unittest`.
|
|
|
|
## Contributing 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.
|
|
|
|
## License, Copyright, and Legal
|
|
|
|
All software in this repository is licensed under the [GNU Public License,
|
|
version 3](https://tldrlegal.com/license/gnu-general-public-license-v3-(gpl-3)).
|
|
All documentation and hardware designs are licensed under the [Creative Commons
|
|
Attribution-ShareAlike 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
|
|
license. Contributions to this repository must use these licenses unless
|
|
otherwise agreed to by the Core team.
|