1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
|
Contributing to rebar
---------------------
Before implementing a new feature, please submit a ticket to discuss 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.
Tests
-----
As a general rule, any behavioral change to rebar requires a test to go with it. If there's
already a test case, you may have to modify that one. If there isn't a test case or a test
suite, add a new test case or suite in `inttest/`. [retest](https://github.com/dizzyd/retest) based tests are preferred, but
we also have EUnit tests in `test/`.
Say you've added a new test case in `inttest/erlc`. To only execute the modified suite,
you would do the following:
```sh
# First we build rebar and its deps to also get `deps/retest/retest`
$ make debug deps
# Now we can test the modified erlc suite
$ deps/retest/retest -v inttest/erlc
```
To test EUnit tests, you would do:
```sh
$ make debug
$ ./rebar -v eunit
```
You can also run `make test` to execute both EUnit and [retest](https://github.com/dizzyd/retest) tests as `make check` does.
Credit
------
To give everyone proper credit in addition to the git history, please feel free to append
your name to `THANKS` in your first contribution.
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
|
