Contributing to bitmath
This section describes the guidelines for contributing to bitmath.
If you are encounter an issue with the bitmath library, please use the provided template.
Please conform to PEP 0008 for code formatting. This specification outlines the style that is required for patches.
Your code must follow this (or note why it can't) before patches will be accepted. There is one consistent exception to this rule:
- Line too long
pycodestyle tests for bitmath include a
--ignore option to
automatically exclude E501 errors from the tests.
Please write intelligent commit messages.
Capitalized, short (50 chars or less) summary More detailed explanatory text, if necessary. Wrap it to about 72 characters or so. In some contexts, the first line is treated as the subject of an email and the rest of the text as the body. The blank line separating the summary from the body is critical (unless you omit the body entirely); tools like rebase can get confused if you run the two together. Write your commit message in the imperative: "Fix bug" and not "Fixed bug" or "Fixes bug." This convention matches up with commit messages generated by commands like git merge and git revert. Further paragraphs come after blank lines. - Bullet points are okay, too - Typically a hyphen or asterisk is used for the bullet, followed by a single space, with blank lines in between, but conventions vary here - Use a hanging indent
After a pull request is submitted on GitHub two automatic processes are started:
- Travis-CI clones the new pull request and runs the :ref:`automated test suite <contributing_automated_tests>`.
- Coveralls clones the new pull request and determines if the request would increase or decrease the overall code test coverage.
Please check back shortly after submitting a pull request to verify that the Travis-CI process passes.
Pull requests which break the build will be looked at closely and you may be asked to fix the tests.
The bitmath project welcomes all contributors so it's OK if you're unable to fix the tests yourself. Just leave a comment in the pull request explaining so if that is the case.
Likewise, if Coveralls indicates the pull request would decrease the overall test-coverage, and you aren't able to fix it yourself, just leave a comment in the pull request.
Write unittests for any new functionality, if you are up to the task. This is not a requirement, but it does get you a lot of karma.
All bitmath code includes unit tests to verify expected functionality. In the rest of this section we'll learn how the unit tests are put together and how to interact with them.
bitmath unit tests are integrated with/depend on the following items:
- Travis CI - Free online service providing continuous integration functionality for open source projects. Tests are ran automatically on every git commit. Integrates with GitHub to notify you if a pull request passes or fails all unitests.
- Coveralls - Free online service providing code test coverage reporting. Integrates with GitHub to notify you if a pull-request would improve/decrease overall code test coverage.
- unittest - Python unit testing framework. All bitmath tests are written using this framework.
- nose - Per the nose website: "extends unittest to make testing easier". nose is used to run our unit tests.
- coverage - A tool for measuring code coverage of Python programs. For bitmath we require a minimum test coverage of 90%. This is invoked by nose automatically.
- pycodestyle - A tool to check Python code against some of the style conventions in PEP 0008.
- pyflakes - A simple program which checks Python source files for errors.
- virtualenv - A tool to create isolated Python environments. Allows us to install additional package dependencies without requiring access to the system site-packages directory.
- Makefiles - Utility scripts used for project building and testing. How bitmath uses Makefiles is described later in this section.
In the scope of this document, we use the term target in the context of makefile targets. For the purpose of this documentation, we can think of these targets as pre-defined commands coded in a makefile. bitmath testing targets include:
ci- Run the tests exactly how they are ran in Travis-CI. The
citarget automatically calls the
ci3- Is the same as the
citarget, except it runs using the Python 3.x interpreter.
unittests- Run the functional test suite.
pycodestyle- Run PEP 0008 syntax checks.
pyflakes- Run pyflakes error checks.
clean- Remove temporary files and build artifacts from the checked-out repository.
uniquetestnames- Ensures no unit tests have the same name.
tests- A quicker version of
ci. Different from
testsuses libraries installed on the local development workstation.
To ensure the highest degree of confidence in test results you should
always use the
When Travis-CI runs an integration test, it calls the
The bitmath test suite is invoked via the Makefile. The following is
an example of how to run the
ci test target manually:
On line 2 we see how to call a makefile target. In this case it's
make ci. Other targets are called in the
same way. For example, to run the
clean target, you run the
make clean. To run the Python 3.x test suite, you would
run the command
If you find yourself unable to run the unit tests:
- Search for relevant error messages
- Read the error message closely. The solution could be hidden in the error message output. The problem could be as simple as a missing dependency
- If you are unable to figure out all the necessary dependencies to run the tests, file an issue on that specific projects GitHub issue tracker. Include the full error message.