diff options
| -rw-r--r-- | CONTRIBUTING.md | 111 | ||||
| -rw-r--r-- | README.md | 16 |
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. @@ -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). |