Contributing ============ We're thrilled that you're interested in contributing to the taxii-client! Here are some things you should know: - `contribution-guide.org `_ has great ideas for contributing to any open-source project (not just this one). - All contributors must sign a Contributor License Agreement. See `CONTRIBUTING.md `_ in the project repository for specifics. - If you are planning to implement a major feature (vs. fixing a bug), please discuss with a project maintainer first to ensure you aren't duplicating the work of someone else, and that the feature is likely to be accepted. Now, let's get started! Setting up a development environment ------------------------------------ We recommend using a `virtualenv `_. 1. Clone the repository. If you're planning to make pull request, you should fork the repository on GitHub and clone your fork instead of the main repo: .. code-block:: bash $ git clone https://github.com/yourusername/cti-taxii-client.git 2. Install develoment-related dependencies: .. code-block:: bash $ cd cti-taxii-client $ pip install -r requirements.txt 3. Install `pre-commit `_ git hooks: .. code-block:: bash $ pre-commit install At this point you should be able to make changes to the code. Code style ---------- All code should follow `PEP 8 `_. We allow for line lengths up to 160 characters, but any lines over 80 characters should be the exception rather than the rule. PEP 8 conformance will be tested automatically by Tox and Travis-CI (see below). Testing ------- .. note:: All of the tools mentioned in this section are installed when you run ``pip install -r requirements.txt``. This project uses `pytest `_ for testing. We encourage the use of test-driven development (TDD), where you write (failing) tests that demonstrate a bug or proposed new feature before writing code that fixes the bug or implements the features. Any code contributions should come with new or updated tests. To run the tests in your current Python environment, use the ``pytest`` command from the root project directory: .. code-block:: bash $ pytest This should show all of the tests that ran, along with their status. You can run a specific test file by passing it on the command line: .. code-block:: bash $ pytest taxii2client/test/test_.py To ensure that the test you wrote is running, you can deliberately add an ``assert False`` statement at the beginning of the test. This is another benefit of TDD, since you should be able to see the test failing (and ensure it's being run) before making it pass. `tox `_ allows you to test a package across multiple versions of Python. Setting up multiple Python environments is beyond the scope of this guide, but feel free to ask for help setting them up. Tox should be run from the root directory of the project: .. code-block:: bash tox We aim for high test coverage, using the `coverage.py `_ library. Though it's not an absolute requirement to maintain 100% coverage, all code contributions must be accompanied by tests. To run coverage and look for untested lines of code, run: .. code-block:: bash $ pytest --cov=taxii2client $ coverage html then look at the resulting report in ``htmlcov/index.html``. All commits pushed to the ``master`` branch or submitted as a pull request are tested with `Travis-CI `_ automatically. Adding a dependency ------------------- One of the pre-commit hooks we use in our develoment environment enforces a consistent ordering to imports. If you need to add a new library as a dependency please add it to the `known_third_party` section of `.isort.cfg` to make sure the import is sorted correctly.