Contributing

Requirements

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

  • The pull request points to dev branch.
  • Changes are squashed into a single commit. I like to use git rebase for this.
  • Commit message is in present tense. For example, “Fix bug” is good while “Fixed bug” is not.
  • Sphinx-compatible docstrings.
  • PEP8 compliance.
  • No missing docstrings or commented-out lines.
  • Test coverage remains at %100. If a piece of code is trivial and does not need unit tests, use this to exclude it from coverage.
  • No build failures on Travis CI. Builds automatically trigger on pull request submissions.
  • Documentation is kept up-to-date with the new changes (see below).

Warning

The dev branch is occasionally rebased, and its commit history may be overwritten in the process. Before you begin your feature work, git fetch or pull to ensure that your local branch has not diverged. If you see git conflicts and want to start with a clean slate, run the following 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/kq.git
~$ cd kq
~$ flake8

If there is a good reason to ignore a warning, see here on how to exclude it.

Testing

To test your changes, run the integration test suite that comes with kq. It uses pytest and requires an actual Kafka instance.

To run the integration test suite:

~$ pip install pytest
~$ git clone https://github.com/joowani/kq.git
~$ cd kq
~$ py.test -v -s --host=127.0.0.1 --port=9092  # Enter your Kafka host and port

To run the unit tests with coverage report:

~$ pip install coverage pytest pytest-cov
~$ git clone https://github.com/joowani/kq.git
~$ cd kq
~$ py.test -v -s --host=127.0.0.1 --port=9092 --cov=kq --cov-report=html

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

As the test suite creates real topics and messages, it should only be run in development environments.

Documentation

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

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

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

As always, thank you for your contribution!