From e5da685e7ceecabc37e0b740642e6765c9d6cfc3 Mon Sep 17 00:00:00 2001 From: Rodolfo Carvalho Date: Mon, 24 Apr 2017 15:25:30 +0200 Subject: Move link to BUILD.md to README.md Most people contributing to the project do not need to build an RPM, so it can be left out of the Contribution Guide. Placing it in the README for still some visibility. --- CONTRIBUTING.md | 4 ---- 1 file changed, 4 deletions(-) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a000802e2..9be34bcab 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -66,10 +66,6 @@ These are plugins used in playbooks and roles: └── test Contains tests. ``` -## Building openshift-ansible RPMs and container images - -See the [build instructions in BUILD.md](BUILD.md). - ## Running tests We use [tox](http://readthedocs.org/docs/tox/) to manage virtualenvs and run -- cgit v1.2.3 From 9fd022f65d1df98f50c8bcc445c63d026f8d87b8 Mon Sep 17 00:00:00 2001 From: Rodolfo Carvalho Date: Mon, 24 Apr 2017 15:36:39 +0200 Subject: Move repo structure to a separate document Reduces the clutter in CONTRIBUTING.md. --- CONTRIBUTING.md | 56 +------------------------------------------------------- 1 file changed, 1 insertion(+), 55 deletions(-) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9be34bcab..95bca6a2d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -10,61 +10,7 @@ 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. -``` +- [Repository Structure](docs/repo_structure.md) ## Running tests -- cgit v1.2.3 From 5566a5226ac6cfe8432dd0ede91c07374dbb5164 Mon Sep 17 00:00:00 2001 From: Rodolfo Carvalho Date: Mon, 24 Apr 2017 16:18:52 +0200 Subject: Replace absolute with relative URLs This makes the links point to the right place in different contexts (e.g., different branches). --- CONTRIBUTING.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 95bca6a2d..2acc6b119 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,9 +7,9 @@ repository is organized, and how to submit contributions. 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) +- [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) ## Running tests -- cgit v1.2.3 From 5433d56db9423fc204665925c85203656a6b35d6 Mon Sep 17 00:00:00 2001 From: Rodolfo Carvalho Date: Mon, 24 Apr 2017 16:37:01 +0200 Subject: Improve Contribution Guide Update how to submit contributions and how to run tests, reorganizing and expanding the content. --- CONTRIBUTING.md | 138 +++++++++++++++++++++++++++++++++----------------------- 1 file changed, 82 insertions(+), 56 deletions(-) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 2acc6b119..fba4bb40a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -12,25 +12,76 @@ Before submitting code changes, get familiarized with these documents: - [Style Guide](docs/style_guide.adoc) - [Repository Structure](docs/repo_structure.md) -## Running tests +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. -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. +## Submitting contributions + +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. + +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. + +--- + +**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. + +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. + +If you are new to Git, these links might help: + +- https://git-scm.com/book/en/v2/Git-Tools-Rewriting-History +- http://gitready.com/advanced/2009/02/10/squashing-commits-with-rebase.html + +--- + +## Running tests and other verification tasks -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. +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. +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. ``` -pip install tox detox +pip install tox +``` + +To run all tests and verification tasks: + +``` +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 @@ -47,45 +98,45 @@ potentially fail. --- -List the test environments available: - -``` -tox -l -``` - -Run all of the tests and linters with: +### Running only specific tasks -``` -tox -``` - -Run all of the tests linters in parallel (may flake): +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: ``` -detox +tox -l ``` -### Run only unit tests or some specific linter - -Run a particular test environment (`flake8` on Python 2.7 in this case): +To run the command of a particular environment, e.g., `flake8` on Python 2.7: ``` tox -e py27-flake8 ``` -Run a particular test environment in a clean virtualenv (`pylint` on Python 3.5 -in this case): +To run the command of a particular environment in a clean virtualenv, e.g., +`pylint` on Python 3.5: ``` tox -re py35-pylint ``` +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. + #### 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 @@ -124,32 +175,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 -- cgit v1.2.3 From 45e0051b09f467a766ebd7a49741fae631d5c4bf Mon Sep 17 00:00:00 2001 From: Rodolfo Carvalho Date: Mon, 24 Apr 2017 16:38:59 +0200 Subject: Add Table of Contents --- CONTRIBUTING.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fba4bb40a..14efa85e0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,6 +3,22 @@ Thank you for contributing to OpenShift Ansible. This document explains how the repository is organized, and how to submit contributions. +**Table of Contents** + + + +- [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) + + + ## Introduction Before submitting code changes, get familiarized with these documents: -- cgit v1.2.3 From 1d80c4cef89ce10bb71671cfffa0f35dbb28ea93 Mon Sep 17 00:00:00 2001 From: Rodolfo Carvalho Date: Mon, 24 Apr 2017 16:39:30 +0200 Subject: Document the Pull Request process --- CONTRIBUTING.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'CONTRIBUTING.md') diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 14efa85e0..a2c582722 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -46,6 +46,8 @@ something that can be merged to the repository. 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 -- cgit v1.2.3