mirror of
https://github.com/correl/rebar.git
synced 2024-11-23 11:09:55 +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
|
||||
=====================
|
||||
|
||||
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
|
||||
-----------------------
|
||||
|
|
|
|||
Loading…
Reference in a new issue