Improve Contribution Guide

Update how to submit contributions and how to run tests, reorganizing
and expanding the content.

1 files changed, 82 insertions, 56 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 2acc6b119..fba4bb40a 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -12,25 +12,76 @@ Before submitting code changes, get familiarized with these documents:
 - [Style Guide](docs/style_guide.adoc)
 - [Repository Structure](docs/repo_structure.md)
 
-## Running tests
+Please consider opening an issue or discussing on an existing one if you are
+planning to work on something larger, to make sure your time investment is
+something that can be merged to the repository.
 
-We use [tox](http://readthedocs.org/docs/tox/) to manage virtualenvs and run
-tests. Alternatively, tests can be run using
-[detox](https://pypi.python.org/pypi/detox/) which allows for running tests in
-parallel.
+## Submitting contributions
+
+1. [Fork](https://help.github.com/articles/fork-a-repo/) this repository and
+   [create a work branch in your fork](https://help.github.com/articles/github-flow/).
+2. Go through the documents mentioned in the [introduction](#introduction).
+3. Make changes and commit. You may want to review your changes and
+   [run tests](#running-tests-and-other-verification-tasks) before pushing your
+   branch.
+4. [Open a Pull Request](https://help.github.com/articles/creating-a-pull-request/).
+   Give it a meaningful title explaining the changes you are proposing, and
+   then add further details in the description.
+
+One of the repository maintainers will then review the PR and trigger tests, and
+possibly start a discussion that goes on until the PR is ready to be merged.
+
+If you get no timely feedback from a project contributor / maintainer, sorry for
+the delay. You can help us speed up triaging, reviewing and eventually merging
+contributions by requesting a review or tagging in a comment
+[someone who has worked on the files](https://help.github.com/articles/tracing-changes-in-a-file/)
+you're proposing changes to.
+
+---
+
+**Note**: during the review process, you may add new commits to address review
+comments or change existing commits. However, before getting your PR merged,
+please [squash commits](https://help.github.com/articles/about-git-rebase/) to a
+minimum set of meaningful commits.
+
+If you've broken your work up into a set of sequential changes and each commit
+pass the tests on their own then that's fine. If you've got commits fixing typos
+or other problems introduced by previous commits in the same PR, then those
+should be squashed before merging.
+
+If you are new to Git, these links might help:
+
+- https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
+- http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
+
+---
+
+## Running tests and other verification tasks
 
-Note: while `detox` may be useful in development to make use of multiple cores,
-it can be buggy at times and produce flakes, thus we do not use it in our CI.
+We use [`tox`](http://readthedocs.org/docs/tox/) to manage virtualenvs where
+tests and other verification tasks are run. We use
+[`pytest`](https://docs.pytest.org/) as our test runner.
 
+Alternatively to `tox`, one can use
+[`detox`](https://pypi.python.org/pypi/detox/) for running verification tasks in
+parallel. Note that while `detox` may be useful in development to make use of
+multiple cores, it can be buggy at times and produce flakes, thus we do not use
+it in our [CI](docs/continuous_integration.md) jobs.
 
 ```
-pip install tox detox
+pip install tox
+```
+
+To run all tests and verification tasks:
+
+```
+tox
 ```
 
 ---
 
-Note: before running `tox` or `detox`, ensure that the only virtualenvs within
-the repository root are the ones managed by `tox`, those in a `.tox`
+**Note**: before running `tox` or `detox`, ensure that the only virtualenvs
+within the repository root are the ones managed by `tox`, those in a `.tox`
 subdirectory.
 
 Use this command to list paths that are likely part of a virtualenv not managed
@@ -47,45 +98,45 @@ potentially fail.
 
 ---
 
-List the test environments available:
-
-```
-tox -l
-```
-
-Run all of the tests and linters with:
+### Running only specific tasks
 
-```
-tox
-```
-
-Run all of the tests linters in parallel (may flake):
+The [tox configuration](tox.ini) describes environments based on either Python 2
+or Python 3. Each environment is associated with a command that is executed in
+the context of a virtualenv, with a specific version of Python, installed
+dependencies, environment variables and so on. To list the environments
+available:
 
 ```
-detox
+tox -l
 ```
 
-### Run only unit tests or some specific linter
-
-Run a particular test environment (`flake8` on Python 2.7 in this case):
+To run the command of a particular environment, e.g., `flake8` on Python 2.7:
 
 ```
 tox -e py27-flake8
 ```
 
-Run a particular test environment in a clean virtualenv (`pylint` on Python 3.5
-in this case):
+To run the command of a particular environment in a clean virtualenv, e.g.,
+`pylint` on Python 3.5:
 
 ```
 tox -re py35-pylint
 ```
 
+The `-r` flag recreates existing environments, useful to force dependencies to
+be reinstalled.
+
+## Appendix
+
 ### Tricks
 
+Here are some useful tips that might improve your workflow while working on this repository.
+
 #### Activating a virtualenv managed by tox
 
-If you want to enter a virtualenv created by tox to do additional
-testing/debugging (py27-flake8 env in this case):
+If you want to enter a virtualenv created by tox to do additional debugging, you
+can activate it just like any other virtualenv (py27-flake8 environment in this
+example):
 
 ```
 source .tox/py27-flake8/bin/activate
@@ -124,32 +175,7 @@ $ tox -e py27-unit -- roles/lib_openshift/src/test/unit/test_oc_project.py -k te
 Among other things, this can be used for instance to see the coverage levels of
 individual modules as we work on improving tests.
 
-## Submitting contributions
-
-1. Go through the guides from the [introduction](#Introduction).
-2. Fork this repository, and create a work branch in your fork.
-3. Make changes and commit. You may want to review your changes and run tests
-   before pushing your branch.
-4. Open a Pull Request.
-
-One of the repository maintainers will then review the PR and submit it for
-testing.
-
-The `default` test job is publicly accessible at
-https://ci.openshift.redhat.com/jenkins/job/openshift-ansible/. The other jobs
-are run on a different Jenkins host that is not publicly accessible, however the
-test results are posted to S3 buckets when complete.
-
-The test output of each job is also posted to the Pull Request as comments.
-
-A trend of the time taken by merge jobs is available at
-https://ci.openshift.redhat.com/jenkins/job/merge_pull_request_openshift_ansible/buildTimeTrend.
-
----
-
-## Appendix
-
-### Finding unused Python code
+#### Finding unused Python code
 
 If you are contributing with Python code, you can use the tool
 [`vulture`](https://pypi.python.org/pypi/vulture) to verify that you are not