Contributing

I happily accept patches if they make sense for the project and work well. If you aren’t sure if I’ll merge a patch upstream, please open an issue and describe it.

Patches should meet the following criteria before I’ll merge them:

  • All existing tests must pass.

  • Bugfixes and new features must include new tests or asserts.

  • Must not introduce any PEP8 or PyFlakes violations.

I recommend doing all development in a virtualenv, though this is really up to you.

It would be great if new or changed features had documentation and included updates to the CHANGES file, but it’s not totally necessary.

Running Tests

To run the tests, you just need nose and mock. These can be installed with pip:

$ mkvirtualenv statsd
$ pip install -r requirements.txt
$ nosetests

You can also run the tests with tox:

$ tox

Tox will run the tests in Pythons 3.7, 3.8, 3.9, 3.10 and PyPy3, if they’re available.

Writing Tests

New features or bug fixes should include tests that fail without the relevant code changes and pass with them.

For example, if there is a bug in the StatsClient._send method, a new test should demonstrate the incorrect behavior by failing, and the associated changes should fix it. The failure can be a FAILURE or an ERROR.

Tests and the code to fix them should be in the same commit. Bisecting should not stumble over any otherwise known failures.

Note

Pull requests that only contain tests to demonstrate bugs are welcome, but they will be squashed with code changes to fix them.

PEP8 and PyFlakes

The development requirements (requirements.txt) include the flake8 tool. It is easy to run:

$ flake8 statsd/

flake8 should not raise any issues or warnings.

Note

The docs directory includes a Sphinx-generated conf.py that has several violations. That’s fine, don’t worry about it.

Documentation

The documentation lives in the docs/ directory and is automatically built and pushed to ReadTheDocs.

If you change or add a feature, and want to update the docs, that would be great. New features may need a new chapter. You can follow the examples already there, and be sure to add a reference to docs/index.rst. Changes or very small additions may just need a new heading in an existing chapter.