Commit e6ffd69
Gauvain Pocentek
add a contributing section in README
1 parent e0f2290 commit e6ffd69
1 file changed
Lines changed: 70 additions & 2 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -1,6 +1,6 @@ | |||
| 1 | 1 | .. image:: https://travis-ci.org/gpocentek/python-gitlab.svg?branch=master | |
| 2 | 2 | :target: https://travis-ci.org/gpocentek/python-gitlab | |
| 3 | - | ||
| 3 | + | ||
| 4 | 4 | Python GitLab | |
| 5 | 5 | ============= | |
| 6 | 6 | ||
@@ -36,5 +36,73 @@ https://github.com/gpocentek/python-gitlab/issues. | |||
| 36 | 36 | Documentation | |
| 37 | 37 | ============= | |
| 38 | 38 | ||
| 39 | - The documentation for CLI and API is available on `readthedocs | ||
| 39 | + The full documentation for CLI and API is available on `readthedocs | ||
| 40 | 40 | <http://python-gitlab.readthedocs.org/en/stable/>`_. | |
| 41 | + | ||
| 42 | + | ||
| 43 | + Contributing | ||
| 44 | + ============ | ||
| 45 | + | ||
| 46 | + You can contribute to the project in multiple ways: | ||
| 47 | + | ||
| 48 | + * Write documentation | ||
| 49 | + * Implement features | ||
| 50 | + * Fix bugs | ||
| 51 | + * Add unit and functional tests | ||
| 52 | + * Everything else you can think of | ||
| 53 | + | ||
| 54 | + Provide your patches as github pull requests. Thanks! | ||
| 55 | + | ||
| 56 | + Running unit tests | ||
| 57 | + ------------------ | ||
| 58 | + | ||
| 59 | + Before submitting a pull request make sure that the tests still succeed with | ||
| 60 | + your change. Unit tests will run using the travis service and passing tests are | ||
| 61 | + mandatory. | ||
| 62 | + | ||
| 63 | + You need to install ``tox`` to run unit tests and documentation builds: | ||
| 64 | + | ||
| 65 | + .. code-block:: bash | ||
| 66 | + | ||
| 67 | + # run the unit tests for python 2/3, and the pep8 tests: | ||
| 68 | + tox | ||
| 69 | + | ||
| 70 | + # run tests in one environment only: | ||
| 71 | + tox -epy35 | ||
| 72 | + | ||
| 73 | + # build the documentation, the result will be generated in | ||
| 74 | + # build/sphinx/html/ | ||
| 75 | + tox -edocs | ||
| 76 | + | ||
| 77 | + Running integration tests | ||
| 78 | + ------------------------- | ||
| 79 | + | ||
| 80 | + Two scripts run tests against a running gitlab instance, using a docker | ||
| 81 | + container. You need to have docker installed on the test machine, and your user | ||
| 82 | + must have the correct permissions to talk to the docker daemon. | ||
| 83 | + | ||
| 84 | + To run these tests: | ||
| 85 | + | ||
| 86 | + .. code-block:: bash | ||
| 87 | + | ||
| 88 | + # run the CLI tests: | ||
| 89 | + ./tools/functional_tests.sh | ||
| 90 | + | ||
| 91 | + # run the python API tests: | ||
| 92 | + ./tools/py_functional_tests.sh | ||
| 93 | + | ||
| 94 | + You can also build a test environment using the following command: | ||
| 95 | + | ||
| 96 | + .. code-block:: bash | ||
| 97 | + | ||
| 98 | + ./tools/build_test_env.sh | ||
| 99 | + | ||
| 100 | + A freshly configured gitlab container will be available at | ||
| 101 | + http://localhost:8080 (login ``root`` / password ``5iveL!fe``). A configuration | ||
| 102 | + for python-gitlab will be written in ``/tmp/python-gitlab.cfg``. | ||
| 103 | + | ||
| 104 | + To cleanup the environement delete the container: | ||
| 105 | + | ||
| 106 | + .. code-block:: bash | ||
| 107 | + | ||
| 108 | + docker rm -f gitlab-test | ||
0 commit comments