Contributing

Patches for github2 are most welcome!

Forks on GitHub and patches attached to issues are both great ways to contribute. If you’re comfortable with git then using a fork hosted on GitHub is probably the simpler solution, both for the github2 maintainers and for you as a contributor.

Following the simple guidelines below makes it easier to review and integrate your changes:

• PEP 8, the Python style guide, should be followed where possible
• Adding documentation for new methods and classes is very important
• Testing your changes with multiple Python versions is fantastically useful, it is all too easy to use functionality that exists in only specific Python versions

The documentation format used in the code’s docstrings is Sphinx autodoc-compatible. If you’re not comfortable with the format, a close approximation is good enough. It is often easier to fix broken formatting than write documentation from scratch.

Documentation patches and the addition of new examples are as equally appreciated as patches to code.

Tests

Note

Unfortunately test coverage isn’t as high as one would hope, patches to increase test coverage are greatly appreciated!

The preferred way to run the package’s tests is with nose. nosetests, nose’s command-line test runner, provides excellent reporting options and its additional features make it invaluable, see the nose documentation for usage information.

There is a tox configuration file included in the repository, you can use it to run the tests against multiple Python versions with a single command. The configuration file also includes targets for testing the documentation. The tox documentation includes a fantastic number of examples on how to use it, and advice on adding new testing targets.

Notes

github2 supports Python 2.4-3.2, so some attention to compatibility between Python releases needs to be made when writing code.

The official Python docs provide a fantastically useful index of changes between versions.

Note

If you don’t have access to multiple releases of Python it is still possible to contribute. However, it may take a little longer to merge your pull request if additional work needs to be done to make the code compatible with all the supported Python releases.

Test specific concerns

The unittest module received a massive upgrade in Python 2.7, including some very useful new functionality. However, retaining compatibility with older Python versions is very important, so this new functionality can’t be used. Some specific issues to bear in mind are listed below.

Many assertions, such as assertIn() and assertGreater(), only exist from 2.7, and can’t be used. The simple workaround is to evaluate an expression to test with assertTrue()

The incredibly useful functions for skipping tests(skip()) and marking expected failures(expectedFailure()) were only added in 2.7, and unfortunately can’t be used.