summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorRodolfo Carvalho <rhcarvalho@gmail.com>2016-11-04 16:29:02 +0100
committerRodolfo Carvalho <rhcarvalho@gmail.com>2016-11-08 16:49:29 +0100
commit9c7e5894456aba245578fd9e5349ec0c08187c80 (patch)
tree312ba0111c45dea424dfa3500f76da30583934a3
parentc942e4399d22347ad0fcc8e02e576ca056f1a118 (diff)
downloadopenshift-9c7e5894456aba245578fd9e5349ec0c08187c80.tar.gz
openshift-9c7e5894456aba245578fd9e5349ec0c08187c80.tar.bz2
openshift-9c7e5894456aba245578fd9e5349ec0c08187c80.tar.xz
openshift-9c7e5894456aba245578fd9e5349ec0c08187c80.zip
Create contribution guide
-rw-r--r--CONTRIBUTING.md111
-rw-r--r--README.md16
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).