Skip to content

Latest commit

 

History

History
110 lines (77 loc) · 4.1 KB

CONTRIBUTING.md

File metadata and controls

110 lines (77 loc) · 4.1 KB
Raw

Welcome!

Contributions are very welcome on Karapace. When contributing please keep this in mind:

  • Open an issue to discuss new bigger features.
  • Write code consistent with the project style and make sure the tests are passing.
  • Stay in touch with us if we have follow up questions or requests for further changes.

Development

Local Environment

There is very little you need to get started coding for Karapace:

python -m venv <path_to_venv>
source <path_to_venv>/bin/activate
pip install -r ./requirements/requirements-dev.txt
pip install -e .

Website

Karapace documentation is part of this GitHub repository. You can find it in website folder. Its README file contains instructions explaining how you can run documentation website locally.

Tests

Tests are written with the pytest framework, and All PRs are tested for each supported Python version using GitHub Flow.

There are two flavors of tests, unit tests and integration tests:

  • Unit: These are faster and very useful for quick iterations. They are usually testing pure functions.
  • Integration: Are slower but more complete. These tests run Karapace, ZooKeeper, and Kafka servers, pytest's fixtures are used to start/stop these for you.

Both flavors run in parallel using pytest-xdist. New tests should be engineered with this in mind:

  • Don't reuse schema/subject/topic names
  • Expect other clients to be interacting with the servers at the same time.

Before running the tests make sure you have protoc installed. protoc is part of the protobuf-compiler package. In Fedora® distributions you can install it using:

dnf install protobuf-compiler

To run the tests use the binary pytest available in the virtualenv. It will download Kafka to be used in the tests for you:

make karapace/version.py
pytest tests/unit
pytest tests/integration

The integration tests can be configured with the use of a few parameters:

  • --kafka-version: allows to change the version of the Kafka server used by the tests. Example versions: 2.7.2, 2.8.1, 3.0.0.
  • --kafka-bootstrap-servers: A comma separated list of servers. This option allows to use an external server (the tests won't start a server for you)

Other options can be seen with pytest test/integration --help

Static checking and Linting

The code is statically checked and formatted using a few tools. To run these automatically on each commit please enable the pre-commit hooks.

Manual testing

To use your development code, you need to set up a Kafka server and run Karapace from you virtual environment:

docker compose -f ./container/compose.yml up -d kafka
karapace karapace.config.json

Configuration

To see descriptions of configuration keys see our README.

Each configuration key can be overridden with an environment variable prefixed with KARAPACE_, exception being configuration keys that actually start with the karapace string. For example, to override the bootstrap_uri config value, one would use the environment variable KARAPACE_BOOTSTRAP_URI.

Opening a PR

  • Commit messages should describe the changes, not the filenames. Win our admiration by following the excellent advice from Chris Beams when composing commit messages.
  • Choose a meaningful title for your pull request.
  • The pull request description should focus on what changed and why.
  • Check that the tests pass (and add test coverage for your changes if appropriate).

Trademarks:

Fedora and the Infinity design logo are trademarks of Red Hat, Inc.