PyKafka Contribution Guidelines
Get the source code:
git clone https://github.com/Parsely/pykafka.git
Set up the project for development and run the tests:
python setup.py develop tox
Now any changes made in the
pykafka/ folder will immediately be reflected in the
pykafka in your environment.
Check the issues list for the "help wanted" tag if you're interested in finding a place to contribute.
PyKafka uses Tox and pytest for testing. The preferred way to run the tests is via Tox:
pip install tox tox
This tests PyKafka under all of the currently supported Python interpreters.
Master should always pass all tests, but branches are allowed to have failing tests.
It can be helpful to set up a git hook to run the tests before pushing to master. This hook lives in pykafka/.git/hooks/pre-push and looks like this:
#! /usr/bin/env sh BRANCH=`git symbolic-ref -q HEAD` if [ "$BRANCH" = "refs/heads/master" ]; then tox else echo "Not on master. Unit tests not required." fi
Pull Request Guidelines
Everything going into the master branch, except the most trivial fixes, should
first start on a feature branch. Feature branches should be named in the format of
<description> is some descriptive name for what's
enhancement prefixes can be used in place of
The Pull Request can be made via the normal GitHub interface and should include some meaningful description as well as a link to a related Issue, if that exists. The branch should also include tests when possible.
PyKafka adheres to the semantic versioning specification. It uses version numbers of the form X.Y.Z where X is the major version, Y is the minor version, and Z is the patch version. Releases with different major versions indicate changes to the public API.
Past versions of PyKafka are maintained in git with tags. When patches or private code changes are made to the latest version, it is sometimes desirable to backport those changes to older versions. We like to avoid backporting changes when possible, but sometimes it's necessary to continue supporting past versions. In these cases, the changes should be applied on a branch from a checkout of the old version. This new HEAD should be tagged with the appropriately incremented version number, and the tag and branch should be pushed to github. After the release has been created, the branch should be deleted so that only the tagged release remains.
- Verify that all tests pass on master
- Add and commit updates to the changelog
- Increment the version according to SemVer, commit and tag with the version string
- Use the GitHub release UI to create a new release
- Push to PyPI with
python setup.py sdist upload
- Update conda-forge version string and SHA with a pull request here