Contributing to ietfparse

Do you want to contribute extensions, fixes, improvements?

Awesome! and thank you very much

This is a nice little open source project that is released under the permissive BSD license so you don’t have to push your changes back if you do not want to. But if you do, they will be more than welcome.

Set up a development environment

The first thing that you need to do is set up a development environment so that you can run the test suite. The easiest way to do that is to create a virtual environment for your endeavours:

$ pyvenv env

If you are developing against something earlier than Python 3.4, then I highly recommend using virtualenv to create the environment. The earlier versions of pyvenv were slightly broken. The next step is to install the development tools that you will need.

dev-requirements.txt is a pip-formatted requirements file that will install everything that you need:

$ env/bin/pip install -qr dev-requirements.txt
$ env/bin/pip freeze

As usual, is the swiss-army knife in the development tool chest. The following commands are the ones that you will be using most often:

./ nosetests
Run the test suite using nose and generate a coverage report.
./ build_sphinx
Generate the documentation suite into build/sphinx/html
./ flake8
Run the flake8 over the code and report any style violations.
./ clean
Remove generated files. By default, this will remove any top-level egg-related files and the build directory.

Running tests

The easiest way to run the test suite is with nosetests. It will run the test suite with the currently installed python version and report the result of the test run as well as the coverage:

$ env/bin/python nosetests

running nosetests
running egg_info
writing dependency_links to ietfparse.egg-info/dependency_links.txt
writing top-level names to ietfparse.egg-info/top_level.txt
writing ietfparse.egg-info/PKG-INFO
reading manifest file 'ietfparse.egg-info/SOURCES.txt'
reading manifest template ''
warning: no previously-included files matching '__pycache__'...
warning: no previously-included files matching '*.swp' found ...
writing manifest file 'ietfparse.egg-info/SOURCES.txt'
test_that_differing_parameters_is_acceptable_as_weak_match ...

Name                       Stmts   Miss Branch BrMiss  Cover   Missing
ietfparse                      0      0      0      0   100%
ietfparse.algorithms          36      1     24      1    97%   98
ietfparse.datastructures      26      0     21      0   100%
ietfparse.errors               4      0      0      0   100%
ietfparse.headers             29      1     14      1    95%   82
TOTAL                         95      2     59      2    97%
Ran 44 tests in 0.054s


Before you can call the code complete, you really need to make sure that it works across the supported python versions. Travis-CI will take care of making sure that this is the case when the code is pushed to github but you should do this before you push. The easiest way to do this is to install detox and run it:

$ env/bin/python install -q detox
$ env/bin/detox
py27 recreate: /.../ietfparse/build/tox/py27
GLOB sdist-make: /.../ietfparse/
py33 recreate: /.../ietfparse/build/tox/py33
py34 recreate: /.../ietfparse/build/tox/py34
py27 installdeps: -rtest-requirements.txt, mock
py33 installdeps: -rtest-requirements.txt
py34 installdeps: -rtest-requirements.txt
py27 inst: /.../ietfparse/build/tox/dist/
py27 runtests: PYTHONHASHSEED='2156646470'
py27 runtests: commands[0] | /../ietfparse/build/tox/py27/bin/nosetests
py33 inst: /../ietfparse/.build/tox/dist/
py34 inst: /../ietfparse/.build/tox/dist/
py33 runtests: PYTHONHASHSEED='2156646470'
py33 runtests: commands[0] | /.../ietfparse/build/tox/py33/bin/nosetests
py34 runtests: PYTHONHASHSEED='2156646470'
py34 runtests: commands[0] | /.../ietfparse/build/tox/py34/bin/nosetests
_________________________________ summary _________________________________
  py27: commands succeeded
  py33: commands succeeded
  py34: commands succeeded
  congratulations :)

This is what you want to see. Tests passing across the board. Time to submit a PR.

Submitting a Pull Request

The first thing to do is to fork the repository and set up a nice shiny environment in it. Once you can run the tests, it’s time to write some. I developed this library using a test-first methodology. If you are fixing a defect, then write a test that verifies the correct behavior. It should fail. Now, fix the defect making the test pass in the process. New functionality follows a similar path. Write a test that verifies the correct behavior of the new functionality. Then add enough functionality to make the test pass. Then, on to the next test. This is test driven development at its core. This actually is pretty important since pull requests that are not tested will not be merged. This is why nose is configured to report coverage. The coverage doesn’t have to be 100% but it should be pretty close. Anything that isn’t covered is usually scrutinized.

Once you have a few tests are written and some functionality is working, you should probably commit your work. If you are not comfortable with rebasing in git or cleaning up a commit history, your best bet is to create small commits – commit early, commit often. The smaller the commit is, the easier it will be to squash and rearrange them.

When your change is written and tested, make sure to update and/or add documentation as needed. The documentation suite is written using ReStructuredText and the excellent sphinx utility. If you don’t think that documentation matters, read Kenneth Reitz’s Documentation is King presentation. Pull requests that are not simply bug fixes will almost always require some documentation.

After the tests are written, code is complete, and documents are up to date, it is time to push your code back to and submit a pull request against the upstream repository.