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/toxto 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_sphinxproduces 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.
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.
$ python3 -mvenv env $ env/bin/pip install -r dev-requirements.txt
Tests are written using the standard unittest package and run using nose and tox.
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.