diff options
Diffstat (limited to 'CONTRIBUTING.md')
| -rw-r--r-- | CONTRIBUTING.md | 233 |
1 files changed, 138 insertions, 95 deletions
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 502ef6aa5..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. -This section covers how to run tests for the root of this repo, running tests -for the oo-install wrapper is described in [utils/README.md](utils/README.md). +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. -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 +``` +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 @@ -98,66 +109,98 @@ by `tox`: $ find . -path '*/bin/python' | grep -vF .tox ``` -Extraneous virtualenvs cause tools such as `pylint` to take a very long time -going through files that are part of the virtualenv. +The reason for this recommendation is that extraneous virtualenvs cause tools +such as `pylint` to take a very long time going through files that are part of +the virtualenv, and test discovery to go through lots of irrelevant files and +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 with: -``` -tox -``` +To run the command of a particular environment, e.g., `flake8` on Python 2.7: -Run all of the tests in parallel with detox: ``` -detox +tox -e py27-flake8 ``` -Running a particular test environment (python 2.7 flake8 tests in this case): -``` -tox -e py27-ansible22-flake8 -``` +To run the command of a particular environment in a clean virtualenv, e.g., +`pylint` on Python 3.5: -Running a particular test environment in a clean virtualenv (python 3.5 pylint -tests in this case): ``` -tox -r -e py35-ansible22-pylint +tox -re py35-pylint ``` -If you want to enter the virtualenv created by tox to do additional -testing/debugging (py27-flake8 env in this case): +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. + +#### Git Hooks + +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 debugging, you +can activate it just like any other virtualenv (py27-flake8 environment in this +example): + ``` -source .tox/py27-ansible22-flake8/bin/activate +source .tox/py27-flake8/bin/activate ``` -## Submitting contributions +#### Limiting the unit tests that are run -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. +During development, it might be useful to constantly run just a single test file +or test method, or to pass custom arguments to `pytest`: -One of the repository maintainers will then review the PR and submit it for -testing. +``` +tox -e py27-unit -- path/to/test/file.py +``` -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. +Anything after `--` is passed directly to `pytest`. To learn more about what +other flags you can use, try: -The test output of each job is also posted to the Pull Request as comments. +``` +tox -e py27-unit -- -h +``` ---- +As a practical example, the snippet below shows how to list all tests in a +certain file, and then execute only one test of interest: -## Appendix +``` +$ tox -e py27-unit -- roles/lib_openshift/src/test/unit/test_oc_project.py --collect-only --no-cov +... +collected 1 items +<Module 'roles/lib_openshift/src/test/unit/test_oc_project.py'> + <UnitTestCase 'OCProjectTest'> + <TestCaseFunction 'test_adding_a_project'> +... +$ tox -e py27-unit -- roles/lib_openshift/src/test/unit/test_oc_project.py -k test_adding_a_project +``` + +Among other things, this can be used for instance to see the coverage levels of +individual modules as we work on improving tests. -### 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 |