Contributing¶
If you are reading this, then you might be thinking about contributing some changes. Thank you!
The first step is to fork this repository and create a branch to hold your work. This project uses Github Pull Requests to manage contributions so you are required to have a Github account and create a personal fork of this repository. Once you have an account, a fork, and a branch, it is time to start coding. The following sections explain the common development tasks.
I do have a few expectations about pull requests:
100% test coverage is maintained with minimal mock usage
all functionality is documented using sphinx
code is formatted using yapf before being committed – this applies to each and every commit
Do not let this scare you off. I’ll help you out if you run into problems testing or documenting. Submit the PR and we can work through the finer details.
Setting up your environment¶
$ python -mvenv env
$ ./env/bin/pip install -qe '.[dev]'
$ cp ci/git-pre-commit .git/hooks/pre-commit
$ chmod u+x .git/hooks/pre-commit
Running tests¶
Local tests¶
Note
Locally running tests without starting the integration depedencies does not cover all of the library source code as shown in the following snippets. See Integration testing below for full test coverage.
$ . ./env/bin/activate
(env) $ coverage run setup.py test -q
running test
running egg_info
writing klempner.egg-info/PKG-INFO
writing dependency_links to klempner.egg-info/dependency_links.txt
writing requirements to klempner.egg-info/requires.txt
writing top-level names to klempner.egg-info/top_level.txt
reading manifest file 'klempner.egg-info/SOURCES.txt'
reading manifest template 'MANIFEST.in'
writing manifest file 'klempner.egg-info/SOURCES.txt'
running build_ext
........s...............
----------------------------------------------------------------------
Ran 23 tests in 0.005s
OK (skipped=1)
(env) $ coverage report
Name Stmts Miss Branch BrPart Cover Missing
------------------------------------------------------------------
klempner/__init__.py 2 0 2 0 100%
klempner/compat.py 8 0 0 0 100%
klempner/config.py 71 4 22 0 96% 127-130
klempner/errors.py 11 2 0 0 82% 10-11
klempner/url.py 88 18 32 1 81% 25-29, 125-142, 124->125
------------------------------------------------------------------
TOTAL 180 24 56 1 88%
(env) $ tox -p auto
✔ OK py37 in 1.885 seconds
✔ OK py27 in 1.934 seconds
✔ OK py35 in 2.081 seconds
✔ OK py36 in 2.11 seconds
___________________________________________________ summary ___________________________________________________
py27: commands succeeded
py35: commands succeeded
py36: commands succeeded
py37: commands succeeded
congratulations :)
Integration testing¶
The integration tests require that you have some additional services running. This project runs the dependencies using docker so you will need access to a docker host. You can install docker from hub.docker.com for the majority of operating systems. Once docker is installed, running the integrated tests is simple.
$ docker-compose run --rm integration-test
Creating network "klempner_default" with the default driver
Creating klempner_consul_1 ... done
Building package...
Installing...
Running tests..........................
Name Stmts Miss Branch BrPart Cover Missing
------------------------------------------------------------------
klempner/__init__.py 2 0 2 0 100%
klempner/compat.py 8 0 0 0 100%
klempner/config.py 71 0 22 0 100%
klempner/errors.py 11 0 0 0 100%
klempner/url.py 88 0 32 0 100%
------------------------------------------------------------------
TOTAL 180 0 56 0 100%
----------------------------------------------------------------------
Ran 26 tests in 0.648s
OK
Checking code style¶
(env) $ yapf -dpr klempner setup.py tests
(env) $ flake8