1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
|
# 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.
```
## Running tests
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.
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 detox
```
---
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
by `tox`:
```
$ find . -path '*/bin/python' | grep -vF .tox
```
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:
```
tox -l
```
Run all of the tests and linters with:
```
tox
```
Run all of the tests linters in parallel (may flake):
```
detox
```
### Run only unit tests or some specific linter
Run a particular test environment (`flake8` on Python 2.7 in this case):
```
tox -e py27-flake8
```
Run a particular test environment in a clean virtualenv (`pylint` on Python 3.5
in this case):
```
tox -re py35-pylint
```
### Tricks
#### 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):
```
source .tox/py27-flake8/bin/activate
```
#### Limiting the unit tests that are run
During development, it might be useful to constantly run just a single test file
or test method, or to pass custom arguments to `pytest`:
```
tox -e py27-unit -- path/to/test/file.py
```
Anything after `--` is passed directly to `pytest`. To learn more about what
other flags you can use, try:
```
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:
```
$ 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.
## 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
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
introducing unused code by accident.
This tool is not used in an automated form in CI nor otherwise because it may
produce both false positives and false negatives. Still, it can be helpful to
detect dead code that escapes our eyes.
|
