diff options
| -rw-r--r-- | CONTRIBUTING.md | 94 | ||||
| -rw-r--r-- | README.md | 72 |
2 files changed, 95 insertions, 71 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..9aeccb5 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,94 @@ +Contributing to rebar +--------------------- + +Before implementing a new feature, you should submit a ticket for discussion on your plans. +The feature might have been rejected already, or the implementation might already be decided. + +See [Community and Resources](README.md#community-and-resources). + +Code style +---------- + +The following rules must be followed: + * Do not introduce trailing whitespace + * Do not mix spaces and tabs + * Do not introduce lines longer than 80 characters + +The following rules should be followed: + * Write small functions whenever possible + * Avoid having too many clauses containing clauses containing clauses. + Basically, avoid deeply nested functions. + +[erlang-mode (emacs)](http://www.erlang.org/doc/man/erlang.el.html) +indentation is preferred. This will keep the code base consistent. +vi users are encouraged to give [Vim emulation](http://emacswiki.org/emacs/Evil) ([more +info](https://gitorious.org/evil/pages/Home)) a try. + +Pull requests and branching +--------------------------- + +Use one topic branch per pull request. If you do that, you can add extra commits or fix up +buggy commits via `git rebase -i`, and update the branch. The updated branch will be +visible in the same pull request. Therefore, you should not open a new pull request when +you have to fix your changes. + +Do not commit to master in your fork. + +Provide a clean branch without merge commits. + +Committing your changes +----------------------- + +Please ensure that all commits pass all tests, and do not have extra Dialyzer warnings. +To do that run `make check`. If you didn't build via `make debug` at first, the beam files in +`ebin/` might be missing debug_info required for [xref](http://www.erlang.org/doc/man/xref.html) +and [Dialyzer](http://www.erlang.org/doc/man/dialyzer.html), causing a test +failure. +If that happens, running `make clean` before running `make check` could solve the problem. +If you change any of the files with known but safe to ignore Dialyzer warnings, you may +have to adapt the line number(s) in [dialyzer_reference](dialyzer_reference). If you do that, +do not remove the +leading blank line. + +#### Structuring your commits + +Fixing a bug is one commit. +Adding a feature is one commit. +Adding two features is two commits. +Two unrelated changes is two commits. + +If you fix a (buggy) commit, squash (`git rebase -i`) the changes as a fixup commit into +the original commit. + +#### Writing Commit Messages + +It's important to write a proper commit title and description. The commit title must be +at most 50 characters; it is the first line of the commit text. The second line of the +commit text must be left blank. The third line and beyond is the commit message. You +should write a commit message. If you do, wrap all lines at 72 characters. You should +explain what the commit does, what references you used, and any other information +that helps understanding your changes. + +Basically, structure your commit message like this: + +<pre> +One line summary (at most 50 characters) + +Longer description (wrap at 72 characters) +</pre> + +##### Commit title/summary + +* At most 50 characters +* What was changed +* Imperative present tense (Fix, Add, Change) + * `Fix bug 123` + * `Add 'foobar' command` + * `Change default timeout to 123` +* No period + +##### Commit description + +* Wrap at 72 characters +* Why, explain intention and implementation approach +* Present tense @@ -51,77 +51,7 @@ and you can use rebar to build OTP-compliant apps. Contributing to rebar ===================== -Pull requests and branching ---------------------------- - -Use one topic branch per pull request. - -Do not commit to master in your fork. - -Provide a clean branch without any merge commits from upstream. - -Usually you should squash any intermediate commits into the original single commit. - -Code style ----------- - -Do not introduce trailing whitespace. - -Do not mix spaces and tabs. - -Do not introduce lines longer than 80 characters. - -[erlang-mode (emacs)](http://www.erlang.org/doc/man/erlang.el.html) indentation -is preferred. vi-only users are encouraged to give [Vim -emulation](http://emacswiki.org/emacs/Evil) ([more -info](https://gitorious.org/evil/pages/Home)) a try. - -Writing Commit Messages ------------------------ - -Structure your commit message like this: - -<pre> -One line summary (less than 50 characters) - -Longer description (wrap at 72 characters) -</pre> - -### Summary - -* Less than 50 characters -* What was changed -* Imperative present tense (fix, add, change) - * `Fix bug 123` - * `Add 'foobar' command` - * `Change default timeout to 123` -* No period - -### Description - -* Wrap at 72 characters -* Why, explain intention and implementation approach -* Present tense - -### Atomicity - -* Break up logical changes -* Make whitespace changes separately - -Run checks ----------- - -Before you submit a patch, run ``make check`` to execute the test suite and -check for [xref](http://www.erlang.org/doc/man/xref.html) and -[Dialyzer](http://www.erlang.org/doc/man/dialyzer.html) warnings. You may have -to run ``make clean`` first. - -[Dialyzer](http://www.erlang.org/doc/man/dialyzer.html) warnings are compared -against a set of safe-to-ignore warnings found in -[dialyzer_reference](https://raw.github.com/rebar/rebar/master/dialyzer_reference). -[xref](http://www.erlang.org/doc/man/xref.html) is run with [custom -queries](https://raw.github.com/rebar/rebar/master/rebar.config) to suppress -safe-to-ignore warnings. +Please refer to [CONTRIBUTING](CONTRIBUTING.md). Community and Resources ----------------------- |