keybrd/CONTRIBUTING.md

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

Submit improvement suggestions to GitHub issues or geekhack thread.

• 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 or geekhack thread.

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.

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.