diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md new file mode 100644 index 0000000..abc9e71 --- /dev/null +++ b/.github/CONTRIBUTING.md @@ -0,0 +1,90 @@ +Contributing to the Project +=========================== + +Thank you for considering contributing back to [Free Software][1]! + +There are a few things we would like you to consider when filing an +issue or pull request with this project: + +1. If you are filing a bug report or feature request + + Please take the time to check if an issue already has been filed + matching your problem + +2. What version are you running, have you tried the latest release? + + UNIX distributions often package and test software for their + particular brand. If you are using a pre-packaged version, + then please file a bug with that distribution instead. + +3. Coding Style + + Lines are allowed to be longer than 72 characters these days, there + is no enforced max. length. + +> **Tip:** Always submit code that follows the style of surrounding code! + + The coding style itself is strictly Linux [KNF][], like GIT it is + becoming a de facto standard for C programming + + https://www.kernel.org/doc/Documentation/CodingStyle + +4. Logical Change Sets + + Changes should be broken down into logical units that add a feature + or fix a bug. Keep changes separate from each other and do not mix a + bug fix with a whitespace cleanup or a new feature addition. + + This is important not only for readilibity, or for the possibility of + maintainers to revert changes, but does also increase your chances of + having a change accepted. + +5. Commit messages + + Commit messages exist to track *why* a change was made. Try to be as + clear and concise as possible in your commit messages, and always, be + proud of your work and set up a proper GIT identity for your commits: + + git config --global user.name "J. Random Hacker" + git config --global user.email random.j.hacker@example.com + + See this helpful guide for how to write simple, readable commit + messages, or have at least a look at the below example. + + http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html + + +Example +------- + +Example commit message from the [Pro Git][gitbook] online book, notice +how `git commit -s` is used to automatically add a `Signed-off-by`: + + Capitalized, short (50 chars or less) summary + + More detailed explanatory text, if necessary. Wrap it to about 72 + characters or so. In some contexts, the first line is treated as the + subject of an email and the rest of the text as the body. The blank + line separating the summary from the body is critical (unless you omit + the body entirely); tools like rebase can get confused if you run the + two together. + + Write your commit message in the imperative: "Fix bug" and not "Fixed bug" + or "Fixes bug." This convention matches up with commit messages generated + by commands like git merge and git revert. + + Further paragraphs come after blank lines. + + - Bullet points are okay, too + + - Typically a hyphen or asterisk is used for the bullet, followed by a + single space, with blank lines in between, but conventions vary here + + - Use a hanging indent + + Signed-off-by: J. Random Hacker + + +[1]: http://www.gnu.org/philosophy/free-sw.en.html +[KNF]: https://en.wikipedia.org/wiki/Kernel_Normal_Form +[gitbook]: https://git-scm.com/book/ch5-2.html