mirror of
https://github.com/correl/rebar.git
synced 2024-11-23 19:19:54 +00:00
Extract contributing guide into CONTRIBUTING.md
While at it, refactor the guide for clarity. Some of the new text was taken from erlware/relx/CONTRIBUTING.md and modified as needed.
This commit is contained in:
Tuncer Ayaz
parent
e840ac2112
commit
71f6e917f4
2 changed files with 95 additions and 71 deletions
94
CONTRIBUTING.md
Normal file
94
CONTRIBUTING.md
Normal file
|
|
@ -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
|
||||||
72
README.md
72
README.md
|
|
@ -51,77 +51,7 @@ and you can use rebar to build OTP-compliant apps.
|
||||||
Contributing to rebar
|
Contributing to rebar
|
||||||
=====================
|
=====================
|
||||||
|
|
||||||
Pull requests and branching
|
Please refer to [CONTRIBUTING](CONTRIBUTING.md).
|
||||||
---------------------------
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
Community and Resources
|
Community and Resources
|
||||||
-----------------------
|
-----------------------
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue