Archived
1
0
This repo is archived. You can view files and clone it, but cannot push or open issues or pull requests.
keybrd/CONTRIBUTING.md

143 lines
6.6 KiB
Markdown
Raw Normal View History

2016-07-18 02:26:00 +00:00
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).
2016-07-18 02:26:00 +00:00
2016-09-01 02:29:59 +00:00
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 -->
2016-07-18 02:26:00 +00:00
* 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)
2016-09-01 02:29:59 +00:00
or [geekhack thread](https://geekhack.org/index.php?topic=83599.0).
2016-07-18 02:26:00 +00:00
Provide enough information so we can reproduce the buggy behaviour!
2016-07-18 02:26:00 +00:00
* 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?
2016-07-18 02:26:00 +00:00
You can start by looking through the improvement suggestions, bug reports, and [planned_features](doc/planned_features.md).
2016-11-04 06:56:26 +00:00
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)
2016-07-18 02:26:00 +00:00
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")
2016-07-22 08:11:38 +00:00
* Reference an improvement suggestion, bug report, or planned_features
2016-07-18 02:26:00 +00:00
* 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.
2016-11-06 19:43:09 +00:00
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.
2016-11-06 19:43:09 +00:00
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.
2016-07-18 02:26:00 +00:00
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).
2016-07-18 02:26:00 +00:00
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.
2016-07-22 18:16:47 +00:00
Submitting a pull request
2016-07-18 02:26:00 +00:00
-------------------------
2016-07-22 18:16:47 +00:00
Pull request is the preferred way to contribute code and documentation.
2016-11-06 09:41:56 +00:00
[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).
2016-07-18 02:26:00 +00:00