Create contribution guide

2 files changed, 112 insertions, 15 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 000000000..1145da495
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,111 @@
+# Contributing
+
+Thank you for contributing to OpenShift Ansible. This document explains how the
+repository is organized, and how to submit contributions.
+
+## Introduction
+
+Before submitting code changes, get familiarized with these documents:
+
+- [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)
+
+## Repository structure
+
+### Ansible
+
+```
+.
+├── 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.
+```
+
+#### Ansible plugins
+
+These are plugins used in playbooks and roles:
+
+```
+.
+├── ansible-profile
+├── callback_plugins
+├── filter_plugins
+└── lookup_plugins
+```
+
+### Scripts
+
+```
+.
+├── 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
+
+```
+.
+└── docs                Contains documentation for this repository.
+```
+
+### Tests
+
+```
+.
+└── test                Contains tests.
+```
+
+### Others
+
+```
+.
+└── git                 Contains some helper scripts for repository maintenance.
+```
+
+## Building RPMs
+
+See the [RPM build instructions](BUILD.md).
+
+## Running tests
+
+We use [Nose](http://readthedocs.org/docs/nose/) as a test runner. Make sure it
+is installed along with other test dependencies:
+
+```
+pip install -r utils/test-requirements.txt
+```
+
+Run the tests with:
+
+```
+nosetests
+```
+
+## 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.
diff --git a/README.md b/README.md
index cc25e5abc..950aea3ae 100644
--- a/README.md
+++ b/README.md
@@ -27,15 +27,6 @@ Releases are tagged periodically from active branches and are versioned 3.x
 corresponding to Origin releases 1.x. We unfortunately started with 3.0 and it's
 not practical to start over at 1.0.
 
-## Directory structure
-
-- [bin/cluster](https://github.com/openshift/openshift-ansible/tree/master/bin/cluster) - Python script to easily create clusters
-- [docs/](https://github.com/openshift/openshift-ansible/tree/master/docs) - documentation for the project
-- [filter_plugins/](https://github.com/openshift/openshift-ansible/tree/master/filter_plugins) - custom filters used to manipulate data in Ansible
-- [inventory/](https://github.com/openshift/openshift-ansible/tree/master/inventory) - Ansible dynamic inventory scripts
-- [playbooks/](https://github.com/openshift/openshift-ansible/tree/master/playbooks) - host-type Ansible playbooks (launch, config, destroy, vars)
-- [roles/](https://github.com/openshift/openshift-ansible/tree/master/roles) - shareable Ansible tasks
-
 ## Setup
 
 1. Install base dependencies:
@@ -60,11 +51,6 @@ not practical to start over at 1.0.
       - [OpenShift Enterprise](https://docs.openshift.com/enterprise/latest/install_config/install/advanced_install.html)
       - [OpenShift Origin](https://docs.openshift.org/latest/install_config/install/advanced_install.html)
 
-- Build
-  - [How to build the openshift-ansible rpms](BUILD.md)
-
 ## Contributing
 
-- [Best Practices Guide](https://github.com/openshift/openshift-ansible/blob/master/docs/best_practices_guide.adoc)
-- [Core Concepts](https://github.com/openshift/openshift-ansible/blob/master/docs/core_concepts_guide.adoc)
-- [Style Guide](https://github.com/openshift/openshift-ansible/blob/master/docs/style_guide.adoc)
+See the [contribution guide](CONTRIBUTING.md).