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
Fluent-Test==3.0.0
Jinja2==2.7.3
MarkupSafe==0.23
Pygments==1.6
Sphinx==1.2.3
coverage==3.7.1
docutils==0.12
flake8==2.2.3
mccabe==0.2.1
mock==1.0.1
nose==1.3.4
pep8==1.5.7
pyflakes==0.8.1
sphinx-rtd-theme==0.1.6
As usual, setup.py is the swiss-army knife in the development tool chest. The following commands are the ones that you will be using most often:
- ./setup.py nosetests
- Run the test suite using nose and generate a coverage report.
- ./setup.py build_sphinx
- Generate the documentation suite into build/sphinx/html
- ./setup.py flake8
- Run the flake8 over the code and report any style violations.
- ./setup.py 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 setup.py 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 setup.py 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 'MANIFEST.in'
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
OK
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/setup.py
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/ietfparse-0.0.0.zip
py27 runtests: PYTHONHASHSEED='2156646470'
py27 runtests: commands[0] | /../ietfparse/build/tox/py27/bin/nosetests
py33 inst: /../ietfparse/.build/tox/dist/ietfparse-0.0.0.zip
py34 inst: /../ietfparse/.build/tox/dist/ietfparse-0.0.0.zip
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 github.com and submit a pull request against the upstream repository.