Contributing to keybrd ====================== We'd love for you to contribute to the keybrd project. Improvement suggestions ----------------------- We need to know what keybrd library improvements would help you create keyboard designs. Before requesting an improvement, please check the [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). * Provide a use case * Explain why the improvement is useful * Site other product examples where this improvement exists Bug reports ----------- Submitting a bug report is the first step in fixing a bug. Once it is found, correcting a bug 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 of 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). Scratch your own itch. Code for your own need. Then share it with the keybrd community. * [Tutorial 8b - sharing your keybrd extension library](tutorials/tutorial_8b_sharing_your_keybrd_extension_library.md) * [Tutorial 8c - sharing your keybrd sketch](tutorials/tutorial_8c_sharing_your_keybrd_sketch.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. ### keybrd tutorials usability survey We want feedback on keybrd tutorial usability from real users (feedback from noobs is especially valuable). Please take the survey after completing a tutorial. Answer the questions you feel like answering, or make up your own questions. * How easy was it to find the relevant tutorial? * Which tutorial did you read? * Did the tutorial provide complete information? * What other tutorial topics would be useful? * Are you satisfied with the tutorial? * Other comments or suggestions. Post the completed Q & A on [geekhack thread](https://geekhack.org/index.php?topic=83599.0) with the heading "Tutorial usability survey". If you prefer your answers remain confidential, pm the completed Q & A to [wolfv](https://geekhack.org/index.php?action=pm;sa=send;u=25471). Usability survey results will be used to make improvements to the tutorials. ### keybrd library usability survey We want feedback on keybrd library usability from real users. Please fill the survey after using the keybrd library to implement a keyboard design. Answer the questions you feel like answering, or make up your own questions. * How easy was it to find relevant information? * Did the User guide provide complete information? * What other keyboard firmware have you used? * What pros and cons did you find compared to other keyboard firmware? * Did you publish your keyboard firmware? If so, please provide a link. * Are you satisfied with the keybrd library? * Other comments or suggestions. Post the completed Q & A on [geekhack thread](https://geekhack.org/index.php?topic=83599.0) with the heading "keybrd library usability survey". If you prefer your answers remain confidential, pm the completed Q & A to [wolfv](https://geekhack.org/index.php?action=pm;sa=send;u=25471). Usability survey results will be used to make improvements 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. Please submit improvement and errata to [GitHub issues](https://github.com/wolfv6/Keybrd/issues) or [geekhack thread](https://geekhack.org/index.php?topic=83599.0). 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). ### Write a sketch for a keyboard that is popular with Arduino-compatible controllers Write a keybrd sketch for a keyboard that is popular with Arduino-compatible controllers. * You should own the keyboard so you can test the firmware * The keyboard should have an Arduino compatible controller (e.g. ErgoDox and Phantom use Teensy 2.0) * The layout should be a plain baseline layout (QWERTY) Other owners of that model keyboard can then easily modify and compile the sketch on Arduino IDE. The README should have: * brief description of the electronics * link to a hardware page * list any firmware deficiencies Follow the "Publish" instructions in tutorial_8c_sharing_your_keybrd_sketch.md ### 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. [How to contribute to an open source project on GitHub](http://blog.davidecoppola.com/2016/11/howto-contribute-to-open-source-project-on-github/) If you want to contribute some other way, please make a request in [GitHub issues](https://github.com/wolfv6/Keybrd/issues) or [geekhack thread](https://geekhack.org/index.php?topic=83599.0).