Hacking on this Code¶
I’m always open to contributions from others provided that the are not completely worthless. I do request that you follow a few basic rules though.
(Almost) All code is tested: if you think that your contributions do not require tests for whatever reason, please justify it.
All tests pass. This is non-negotiable. If you cannot get a particular test case to pass. Submit the PR on github and we can probably work through it. What I won’t do is accept code that breaks a pile of tests without any effort to fix them. Run
env/bin/tox
to run the tests.Features are documented. I use sphinx for all documentation. Edit the documentation sources as required and make sure that running
python setup.py build_sphinx
produces something reasonable.
I apologize for being pretty opinionated about this but code quality doesn’t disappear suddenly, it continually degrades. This set of minimum requirements is my attempt to help prevent quality issues.
Getting Started¶
Congratulations for not being immediately put off by my attitude ;) Let’s
get started. First thing is to create a new sandbox for you to play in.
If you are using Python 3.4 or newer, use pyvenv env
to create a new
virtual environment in the env directory. Otherwise, install
virtualenv and run virtualenv env
to create the environment.
PLEASE DO NOT USE SUDO! DO NOT INSTALL INTO YOUR SYSTEM ENVIRONMENT!!
If you did not chuckle at the previous line, then you really do need to pay careful attention to it. Use virtual environments for developing code.
Once you have an environment, install the requirements listed in dev-requirements.txt. This is a pip-formatted requirements file that will pull in packages that the code depends on as well as packages required to test, document, and generally hack on the code base.
TL;DR
$ python3 -mvenv env
$ env/bin/pip install -r dev-requirements.txt
Running Tests¶
Tests are written using the standard unittest package and run using nose and tox.
$ env/bin/tox
Documentation¶
All documentation is written in ReStructuredText with HTML generated by the sphinx utility.
$ env/bin/python setup.py build_sphinx
The HTML output is written to build/sphinx/html.