diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 201 |
1 files changed, 97 insertions, 104 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a3ae3fd10..1c0fa73ad 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 RPMs +--- -See the [RPM build instructions](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,52 @@ potentially fail. --- -List the test environments available: +### Running only specific tasks + +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: ``` tox -l ``` -Run all of the tests and linters with: +To run the command of a particular environment, e.g., `flake8` on Python 2.7: ``` -tox +tox -e py27-flake8 ``` -Run all of the tests linters in parallel (may flake): +To run the command of a particular environment in a clean virtualenv, e.g., +`pylint` on Python 3.5: ``` -detox +tox -re py35-pylint ``` -### Run only unit tests or some specific linter +The `-r` flag recreates existing environments, useful to force dependencies to +be reinstalled. -Run a particular test environment (`flake8` on Python 2.7 in this case): +## Appendix -``` -tox -e py27-flake8 -``` +### Tricks -Run a particular test environment in a clean virtualenv (`pylint` on Python 3.5 -in this case): +Here are some useful tips that might improve your workflow while working on this repository. -``` -tox -re py35-pylint -``` +#### Git Hooks -### Tricks +Git hooks are included in this repository to aid in development. Check +out the README in the +[hack/hooks](http://github.com/openshift/openshift-ansible/blob/master/hack/hooks/README.md) +directory for more information. #### 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 +200,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 |