90 lines
4.1 KiB
Markdown
90 lines
4.1 KiB
Markdown
Contributing to keybrd
|
|
======================
|
|
We'd love for you to contribute to the keybrd project.
|
|
|
|
Improvement suggestions
|
|
-----------------------
|
|
We need to know what improvements to the keybrd library would help you create your keyboard design.
|
|
Before requesting an improvement, please check [planned_features list](doc/planned_features.md)
|
|
|
|
Submit improvement suggestions to [GitHub issues](https://github.com/wolfv6/Keybrd/issues)
|
|
or [geekhack thread](https://geekhack.org/index.php?topic=83599.0).
|
|
<!-- * The issue title should start with "suggestion:" followed by a descriptive title -->
|
|
* Provide a use case
|
|
* Explain why the improvement is useful
|
|
* Site other product examples where this improvement exists
|
|
|
|
Bug reports
|
|
-----------
|
|
A bug report is the first step in finding a bug.
|
|
Once it is found, correcting it is usually relatively easy.
|
|
Please submit bug reports to [GitHub issues](https://github.com/wolfv6/Keybrd/issues)
|
|
or [geekhack thread](https://geekhack.org/index.php?topic=83599.0).
|
|
|
|
Provide enough information so we can reproduce the buggy behaviour!
|
|
* Complete sketch (copy & paste, attachment, or a link to the code)
|
|
* Screenshot or the exact text of error messages
|
|
* Describe the observed behavior and explain which behavior you expected
|
|
* Which controller your using
|
|
* Wiring details - how exactly have you connected the hardware (a photo's worth 1000 words)
|
|
* Arduino IDE version number
|
|
* keybrd library version number
|
|
* Any other information needed to reproduce the problem...
|
|
|
|
Code contributions
|
|
------------------
|
|
Unsure where to begin contributing to keybrd code?
|
|
You can start by looking through the improvement suggestions, bug reports, and [planned_features](doc/planned_features.md).
|
|
|
|
Git commit message style guide:
|
|
* Limit the first line to 72 characters summary
|
|
* Second line should be empty, followed by body of the commit message
|
|
* Use the imperative present tense (use "Add feature", not "Added feature", not "Adds feature")
|
|
* Reference an improvement suggestion, bug report, or planned_features
|
|
* Sometimes a bulleted list is a good format to convey the changes of a commit
|
|
|
|
User contributions
|
|
------------------
|
|
Any project requires various kinds of contributions to succeed.
|
|
A thriving project is more than a pile of code.
|
|
It's the packaging, explanation, outreach, and empathy of maintainers that make a good project great.
|
|
|
|
### Beta testing
|
|
keybrd library has been Alpha tested on the DodoHand keyboard, tutorial sketches, Teensy 2.0, and Teensy LC. What we need now are Beta testers:
|
|
* use the tutorials (feedback from noobs is especially valuable)
|
|
* use the keybrd library to implement your own keyboard design
|
|
|
|
Feedback from Beta testers will be used to make improvements to the keybrd library.
|
|
|
|
### Schematics
|
|
The most glaring deficiency is the tutorials' lack of schematics.
|
|
Schematics would be an improvement over the current photos.
|
|
|
|
Schematics are not my area of expertise. Use what ever you think would be the best solution for the tutorials:
|
|
* schematics
|
|
* breadboard drawings
|
|
* Arduino simulation software
|
|
|
|
Contributions of tutorial schematics would benefit users new to the keybrd library.
|
|
|
|
### Documentation
|
|
Suggest a clarification, simplification, correction, or other improvement.
|
|
We need the perspective of people new to the project to see these things.
|
|
Sometimes just changing a word or two makes a big difference.
|
|
|
|
Text file documentation style guide:
|
|
* Use Markdown with a .md suffix.
|
|
* "Underline" first-level (=) and second-level (-) headings (because easier to read in plain text).
|
|
* Capitalize first letter of headings (no extra capitalization in headings).
|
|
|
|
### Blog
|
|
You have a fresh perspective of how the keybrd library works.
|
|
This makes you the perfect person to write an introductory blog explaining the project.
|
|
A healthy project needs the perspective of many people.
|
|
|
|
Submitting a pull request
|
|
-------------------------
|
|
Pull request is the preferred way to contribute code and documentation.
|
|
If you want to contribute some other way, please make a request in the [GitHub issues](https://github.com/wolfv6/Keybrd/issues).
|
|
|