Merge pull request #3983 from rhcarvalho/docs-and-ci

Document pull request process and improve contribution guide

1 files changed, 92 insertions, 106 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a000802e2..a2c582722 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -3,92 +3,103 @@
 Thank you for contributing to OpenShift Ansible. This document explains how the
 repository is organized, and how to submit contributions.
 
-## Introduction
+**Table of Contents**
 
-Before submitting code changes, get familiarized with these documents:
+<!-- TOC depthFrom:2 depthTo:4 withLinks:1 updateOnSave:1 orderedList:0 -->
 
-- [Core Concepts](https://github.com/openshift/openshift-ansible/blob/master/docs/core_concepts_guide.adoc)
-- [Best Practices Guide](https://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc)
-- [Style Guide](https://github.com/openshift/openshift-ansible/blob/master/docs/style_guide.adoc)
+- [Introduction](#introduction)
+- [Submitting contributions](#submitting-contributions)
+- [Running tests and other verification tasks](#running-tests-and-other-verification-tasks)
+	- [Running only specific tasks](#running-only-specific-tasks)
+- [Appendix](#appendix)
+	- [Tricks](#tricks)
+		- [Activating a virtualenv managed by tox](#activating-a-virtualenv-managed-by-tox)
+		- [Limiting the unit tests that are run](#limiting-the-unit-tests-that-are-run)
+		- [Finding unused Python code](#finding-unused-python-code)
 
-## Repository structure
+<!-- /TOC -->
 
-### Ansible
+## Introduction
 
-```
-.
-├── inventory           Contains dynamic inventory scripts, and examples of
-│                       Ansible inventories.
-├── library             Contains Python modules used by the playbooks.
-├── playbooks           Contains Ansible playbooks targeting multiple use cases.
-└── roles               Contains Ansible roles, units of shared behavior among
-                        playbooks.
-```
+Before submitting code changes, get familiarized with these documents:
 
-#### Ansible plugins
+- [Core Concepts](docs/core_concepts_guide.adoc)
+- [Best Practices Guide](docs/best_practices_guide.adoc)
+- [Style Guide](docs/style_guide.adoc)
+- [Repository Structure](docs/repo_structure.md)
 
-These are plugins used in playbooks and roles:
+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.
 
-```
-.
-├── ansible-profile
-├── callback_plugins
-├── filter_plugins
-└── lookup_plugins
-```
+## Submitting contributions
 
-### Scripts
+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.
+This process is further explained in the
+[Pull Request process](docs/pull_requests.md) document.
+
+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.
 
-```
-.
-├── bin                 [DEPRECATED] Contains the `bin/cluster` script, a
-│                       wrapper around the Ansible playbooks that ensures proper
-│                       configuration, and facilitates installing, updating,
-│                       destroying and configuring OpenShift clusters.
-│                       Note: this tool is kept in the repository for legacy
-│                       reasons and will be removed at some point.
-└── utils               Contains the `atomic-openshift-installer` command, an
-                        interactive CLI utility to install OpenShift across a
-                        set of hosts.
-```
+---
 
-### Documentation
+**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.
 
-```
-.
-└── docs                Contains documentation for this repository.
-```
+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.
 
-### Tests
+If you are new to Git, these links might help:
 
-```
-.
-└── test                Contains tests.
-```
+- https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History
+- http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html
 
-## Building openshift-ansible RPMs and container images
+---
 
-See the [build instructions in BUILD.md](BUILD.md).
+## Running tests and other verification tasks
 
-## Running tests
+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.
 
-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.
+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.
 
-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.
+```
+pip install tox
+```
 
+To run all tests and verification tasks:
 
 ```
-pip install tox detox
+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
@@ -105,45 +116,45 @@ potentially fail.
 
 ---
 
-List the test environments available:
-
-```
-tox -l
-```
-
-Run all of the tests and linters with:
-
-```
-tox
-```
+### Running only specific tasks
 
-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
@@ -182,32 +193,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