Contributing to Klein¶
Klein is an open source project that welcomes contributions of all kinds coming from the community, including:
Here is a list of shell commands that will install the dependencies of Klein, run the test suite with Python 2.7 and the current version of Twisted, compile the documentation, and check for coding style issues with pyflakes.
pip install --user tox tox -e py27-twcurrent tox -e docs tox -e pyflakes
Tox makes a virtualenv, installs Klein’s dependencies into the virtualenv, and then runs a set of commands based on the
-e (environment) argument.
This strategy allows one to make and test changes to Klein without needing to change system-level Python packages.
Here are some suggestions to make the contributing process easier for everyone:
- Use Twisted’s coding standards as a guideline for code changes you make.
Some parts of Klein (eg.
klein.resource.ensure_utf8_bytes) do not adhere to the Twisted style guide, but changing that would break public APIs, which is worse than breaking the style guidelines. Similarly, if you change existing code, following the Twisted style guide is good, but is less important than not breaking public APIs.
- Compatibility across versions is important: here are `Twisted’s compatibility guidelines<https://twistedmatrix.com/trac/wiki/CompatibilityPolicy>`_, which Klein shares.
- If you’re adding a new feature, please add a file with an example and some explanation to the examples directory, then add your example to
- Please run
tox -e pyflakesto check for style issues in changed code. PyFlakes and similar tools expose many small-but-common errors early enough that it’s easy to remedy the problem.
- Code changes should have tests: untested code is buggy code.
Klein uses Twisted Trial and tox for its tests.
The command to run the full test suite is
toxwith no arguments. This will run tests against several versions of Python and Twisted, which can be time-consuming. To run tests against only one or a few versions, pass a
-eargument with an environment from the envlist in
tox.ini: for example,
tox -e py33-tw150will run tests with Python 3.3 and Twisted 15.0. To run only one or a few specific tests in the suite, add a filename or fully-qualified Python path to the end of the test invocation: for example,
tox klein.test.test_app.KleinTestCase.test_foowill run only the
test_foo()method of the
klein/test/test_app.py. These two test shortcuts can be combined to give you a quick feedback cycle, but make sure to check on the full test suite from time to time to make sure changes haven’t had unexpected side effects.
- Show us your code changes through pull requests sent to Klein’s GitHub repo. This is the best way to make your code visible to others and to get feedback about it.
- If your pull request is a work in progress, please put
[WIP]in its title.
- Add yourself to
AUTHORS. Your contribution matters.
In documents with headers, use this format and order for headers:
======== Header 1 ======== Header 2 ======== Header 3 -------- Header 4 ~~~~~~~~
In prose, please use gender-neutral pronouns or structure sentences such that using pronouns is unecessary.
It’s best to put each sentence on a different line: this makes diffs much easier to read. Sentences that are part of list items need to be indented to be considered part of the same list item.
All code changes added to Klein must be reviewed by at least one other person who is not an author of the code being added. This helps prevent bugs from slipping through the net, gives another source for improvements, and makes sure that the code productively follows guidelines.
Reviewers should read Glyph’s mailing list post on reviewing – code and docs don’t have to be perfect, only better.