keybrd/CONTRIBUTING.md

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).
<!-- * 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
-----------
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).

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 a 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 a 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.

### Schematics
The most glaring deficiency is the tutorials' lack of schematics.
Schematics would be easier to read than the current photos.

Schematics are not my area of expertise.  Use what ever 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.
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.
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).