Contributing

Instructions

Before submitting a pull request on GitHub, please make sure you meet the following requirements:

  • The pull request points to the dev (development) branch.
  • All changes are squashed into a single commit (I like to use git rebase -i to do this).
  • The commit message is in present tense (good: “Add feature”, bad: “Added feature”).
  • Correct and consistent style: Sphinx-compatible docstrings, correct snake and camel casing, and PEP8 compliance (see below).
  • No classes/methods/functions with missing docstrings or commented-out lines. You can take a look at the existing code in binarytree for examples.
  • The test coverage remains at %100. You may find yourself having to write superfluous unit tests to keep this number up. If a piece of code is trivial and has no need for tests, use this to exclude it from coverage.
  • No build failures on TravisCI. The builds automatically trigger on PR submissions.
  • Does not break backward-compatibility (unless there is a really good reason).
  • Compatibility with all supported Python versions: 2.7, 3.4, 3.5 and 3.6.

Warning

The dev branch is occasionally rebased, and its commit history may be overwritten in the process. Before you begin feature work, git fetch or pull to ensure that your local branch has not diverged. If you see git conflicts and just want to start from scratch, run these commands:

~$ git checkout dev
~$ git fetch origin
~$ git reset --hard origin/dev  # THIS WILL WIPE ALL LOCAL CHANGES

Style

To ensure PEP8 compliance, run flake8:

~$ pip install flake8
~$ git clone https://github.com/joowani/binarytree.git
~$ cd binarytree
~$ flake8

You must resolve all issues reported. If there is a good reason to ignore errors coming from a specific piece of code, visit here to see how to exclude the lines.

Testing

To test your changes, run the unit tests that come with binarytree on your local machine. The tests use pytest.

To run the unit tests:

~$ pip install pytest
~$ git clone https://github.com/joowani/binarytree.git
~$ cd binarytree
~$ py.test --verbose

To run the unit tests with coverage report:

~$ pip install coverage pytest pytest-cov
~$ git clone https://github.com/joowani/binarytree.git
~$ cd binarytree
~$ py.test --verbose --cov=binarytree --cov-report=html

# Open the generated file htmlcov/index.html in a browser

Documentation

The documentation (including the README) is written in reStructuredText and uses Sphinx. To build the HTML version of the documentation on your local machine:

~$ pip install sphinx sphinx_rtd_theme
~$ git clone https://github.com/joowani/binarytree.git
~$ cd binarytree/docs
~$ sphinx-build . build

# Open the generated file build/index.html in a browser

As always, thank you for your contribution!