more contributing edits

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.
diff --git a/README.md b/README.md
index 27865f2..e2bb9ac 100644
--- a/README.md
+++ b/README.md
@@ -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)