Like every open-source project, pytest-django is always looking for motivated individuals to contribute to it’s source code. However, to ensure the highest code quality and keep the repository nice and tidy, everybody has to follow a few rules (nothing major, I promise :) )
The fastest way to get feedback on contributions/bugs are usually to open an issue in the issue tracker.
Discussions also happends via IRC in #pylib on irc.freenode.org. You may also be interested in following @andreaspelme on Twitter.
Here’s what the contribution process looks like, in a bullet-points fashion:
Since we’re hosted on GitHub, pytest-django uses git as a version control system.
The GitHub help is very well written and will get you started on using git and GitHub in a jiffy. It is an invaluable resource for newbies and old timers alike.
We try to conform to PEP8 as much as possible. A few highlights:
This is how you fix a bug or add a feature:
Having a wide and comprehensive library of unit-tests and integration tests is of exceeding importance. Contributing tests is widely regarded as a very prestigious contribution (you’re making everybody’s future work much easier by doing so). Good karma for you. Cookie points. Maybe even a beer if we meet in person :)
Generally tests should be:
In a similar way to code, pull requests will be reviewed before pulling (obviously), and we encourage discussion via code review (everybody learns something this way) or IRC discussions.
To run the tests simply execute py.test from your shell. Make sure you have Django and py.test installed before running the tests.
Some of tests are executed in subprocesses. Because of that regular coverage measurements (using pytest-cov plugin) are not reliable.
If you want to measure coverage you’ll need to create .pth file as described in subprocess section of coverage documentation. If you’re using “setup.py develop” thing you should uninstall pytest_django (using pip) for the time of measuring coverage.
You’ll also need mysql and postgres databases. There are predefined settings for each database in tests directory. You may want to modify these files but please don’t include them in your pull requests.
After this short initial setup you’re ready to run tests:
$ COVERAGE_PROCESS_START=`pwd`/.coveragerc COVERAGE_FILE=`pwd`/.coverage PYTHONPATH=`pwd` py.test --ds=tests.postgres_settings
You should repeat above step for sqlite and mysql before next step. This step will create a lot of .coverage files with additional suffix for every process.
The final step is to combine all files created by different processes and generate html coverage report:
$ coverage combine $ coverage html
Your coverage report is now ready in htmlcov directory.
Travis is used to automatically run all tests against all supported versions of Python, Django and different database backends.
The pytest-django Travis page shows the latest test run. Travis will automatically pick up pull requests, test them and report the result directly in the pull request.
Perhaps considered “boring” by hard-core coders, documentation is sometimes even more important than code! This is what brings fresh blood to a project, and serves as a reference for old timers. On top of this, documentation is the one area where less technical people can help most - you just need to write a semi-decent English. People need to understand you. We don’t care about style or correctness.
Documentation should be:
Pulling of documentation is pretty fast and painless. Usually somebody goes over your text and merges it, since there are no “breaks” and that GitHub parses rst files automagically it’s really convenient to work with.
Also, contributing to the documentation will earn you great respect from the core developers. You get good karma just like a test contributor, but you get double cookie points. Seriously. You rock.
This very document is based on the contributing docs of the django CMS project. Many thanks for allowing us to steal it!