Contributing¶
Contributions are always welcome and appreciated! Here are some ways you can contribut.
Issues¶
You can and should open an issue for any of the following reasons:
- you found a bug; steps for reproducing, or a pull request with a failing test case will be greatly appreciated
- you wanted to do something but did not find a way to do it after reading the documentation
- you believe the current way of doing something is more complicated or less elegant than it can be
- a related feature that you want is missing from the package
Please always check for existing issues before opening a new issue.
Pull requests¶
You want to contribute some code? Great! Here are a few steps to get you started:
Fork the repository on GitHub
Clone your fork and create a branch for the code you want to add
Create a new virtualenv and install the package in development mode
$ virtualenv venv $ source venv/bin/activate (venv) $ pip install -e .[validation] (venv) $ pip install -rrequirements/dev.txt -rrequirements/test.txt
Make your changes and check them against the test project
(venv) $ cd testproj (venv) $ python manage.py runserver (venv) $ curl localhost:8000/swagger.yaml
Update the tests if necessary
You can find them in the
tests
directory.If your change modifies the expected schema output, you should download the new generated
swagger.yaml
, diff it against the old reference output intests/reference.yaml
, and replace it after checking that no unexpected changes appeared.Run tests. The project is setup to use tox and pytest for testing
# run tests in the current environment, faster than tox (venv) $ pytest --cov # (optional) run tests for other python versions in separate environments (venv) $ tox
Update documentation
If the change modifies behaviour or adds new features, you should update the documentation and
README.rst
accordingly. Documentation is written in reStructuredText and built using Sphinx. You can find the sources in thedocs
directory.To build and check the docs, run
(venv) $ tox -e docs
Push your branch and submit a pull request to the master branch on GitHub
Incomplete/Work In Progress pull requrests are encouraged, because they allow you to get feedback and help more easily.
Your code must pass all the required travis jobs before it is merged. As of now, this includes running on Python 2.7, 3.4, 3.5 and 3.6, and building the docs succesfully.