Contributing¶
We’re thrilled that you’re interested in contributing to the stix2-elevator! 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:
$ git clone https://github.com/yourusername/cti-stix-elevator.git
- Install develoment-related dependencies:
$ cd cti-stix-elevator
$ pip install -r requirements.txt
- Install pre-commit git hooks:
$ 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:
$ 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:
$ pytest stix2elevator/test/test_<xxx>.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:
$ 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:
$ pytest --cov=stix2elevator
$ 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.