diff options
| -rw-r--r-- | CONTRIBUTING.md | 67 | ||||
| -rw-r--r-- | README.md | 17 |
2 files changed, 61 insertions, 23 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4643725..0ce1e93 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,45 +9,70 @@ See [Community and Resources](README.md#community-and-resources). Code style ---------- -The following rules must be followed: +The following rules apply: * 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: + * We use spaces for indenting only + * Try not to introduce lines longer than 80 characters * 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. +Follow the indentation style of existing files. The [erlang-mode for +(emacs)](http://www.erlang.org/doc/man/erlang.el.html) indentation is going to +always work. Other users may want to use 4-width spaces and make sure things +align mostly the way they would with Emacs code, or with the rest of the +project. + +Where possible, include type specifications for your code so type analysis +will be as accurate as possible. + +Please add comments around tricky fixes or workarounds so that we can +easily know why they're there at a glance. 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. +All fixes to rebar end up requiring a +1 from one or more of the project's +maintainers. When opening a pull request, explain what the patch is doing +and if it makes sense, why the proposed implementation was chosen. + +Try to use well-defined commits (one feature per commit) so that reading +them and testing them is easier for reviewers and while bissecting the code +base for issues. + +During the review process, you may be asked to correct or edit a few things +before a final rebase to merge things. -Do not commit to master in your fork. +Please work in feature branches, and 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 `test/`. +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 `test/`. + +To run the tests: ```sh $ ./bootstrap $ ./rebar3 ct ``` +The rebar3 test suite is written using Common Test. As many of the tests as +possible are written by using the programmatic rebar3 API rather than +by running the escriptized project directly. The tests should be restricted +to their `priv_dir` and leave the system clean after a run. + + If such tests prove hard to write, you can ask for help doing that in your +pull request. + +For tests having a lot to do with I/O and terminal interaction, consider +adding them to https://github.com/tsloughter/rebar3_tests + + Credit ------ @@ -62,10 +87,10 @@ To do that run `./rebar3 ct` and `./rebar3 as dialyze dialyzer`. #### 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. +- Fixing a bug is one commit. +- Adding a feature is one commit. +- Adding two features is two commits. +- Two unrelated changes is two commits (and likely two Pull requests) If you fix a (buggy) commit, squash (`git rebase -i`) the changes as a fixup commit into the original commit. @@ -11,7 +11,7 @@ embed directly in a project. Where possible, rebar uses standard Erlang/OTP conventions for project structures, thus minimizing the amount of build configuration work. rebar also provides dependency management, enabling application writers to easily re-use common libraries from a variety of -locations ([hex.pm](http://hex.pm), git, hg, etc). +locations ([hex.pm](http://hex.pm), git, hg, and so on). 3.0 Beta-1 ==== @@ -27,6 +27,7 @@ locations ([hex.pm](http://hex.pm), git, hg, etc). | clean | Remove project apps beam files | | cover | Generate coverage info from data compiled by `eunit --cover` or `ct --cover` | | ct | Run Common Test suites | +| deps | Lists dependencies currently in use | | do | Higher-order provider to run multiple tasks in sequence | | dialyzer | Run the Dialyzer analyzer on the project | | edoc | Generate documentation using edoc | @@ -47,15 +48,26 @@ locations ([hex.pm](http://hex.pm), git, hg, etc). | version | Print current version of Erlang/OTP and rebar | | xref | Run cross reference analysis on the project | +A more complete list can be found on the [docs page](http://www.rebar3.org/v3.0/docs/commands) + ### Changes +#### Since Rebar 2.x + * Fetches and builds deps if missing when running any command that relies on them * Automatically recognizes `apps` and `lib` directory structure -* Relx for releases +* Relx for releases and relups +* deterministic builds and conflict resolution +* New plugin handling mechanism +* New hook mechanism +* Support for packages +* A ton more ### Gone * Reltool integeration +* Quickcheck integration (moved to [a plugin](http://www.rebar3.org/v3.0/docs/using-available-plugins#quickcheck)) +* C code compiling (moved to [a plugin](http://www.rebar3.org/v3.0/docs/using-available-plugins#port-compiler) or hooks) ### Providers @@ -165,3 +177,4 @@ General rebar community resources and links: - #rebar on [irc.freenode.net](http://freenode.net/) - [wiki](https://github.com/rebar/rebar/wiki) - [issues](https://github.com/rebar/rebar/issues) +- [Documentation](http://www.rebar3.org/v3.0/docs) |