Contributing to Kayrock

Thank you for your interest in contributing to Kayrock!

Development Setup

Prerequisites

• Elixir 1.14 or later
• Erlang/OTP 24.3 or later
• Docker (for integration tests)

Getting Started

# Clone the repository
git clone https://github.com/kafkaex/kayrock.git
cd kayrock

# Install dependencies
mix deps.get

# Run tests
mix test

# Run static analysis
mix credo --strict
mix dialyzer

Code Generation

Kayrock uses code generation from kafka_protocol schemas. The generated code is in lib/generated/.

Important: Do not edit files in lib/generated/ manually.

To regenerate the protocol code:

mix gen.kafka_protocol

This is only needed when:

• Updating the kafka_protocol dependency
• Adding support for new Kafka protocol versions

Running Tests

Unit Tests

mix test

Integration Tests

Integration tests require a Kafka cluster. We use testcontainers:

# Requires Docker to be running
mix test.integration

Code Quality Requirements

All contributions must pass:

1. Compilation without warnings

   mix compile --warnings-as-errors
   

2. Unit tests

   mix test
   

3. Credo (code style)

   mix credo --strict
   

4. Dialyzer (type checking)

   mix dialyzer
   

5. Code formatting

   mix format --check-formatted
   

Pull Request Process

1. Fork the repository
2. Create a feature branch (git checkout -b feature/my-feature)
3. Make your changes
4. Ensure all checks pass (see above)
5. Commit with a descriptive message
6. Push to your fork
7. Open a Pull Request

Commit Messages

Use clear, descriptive commit messages:

Add support for Kafka 3.x protocol changes

- Updated FetchRequest to support new fields
- Added tests for new behavior
- Updated documentation

PR Description

Include:

• What the change does
• Why it's needed
• Any breaking changes
• Related issues (if applicable)

Project Structure

kayrock/
├── lib/
│   ├── kayrock/           # Core library code
│   │   ├── client.ex      # Kafka client (development only)
│   │   ├── compression.ex # Compression handling
│   │   ├── record_batch.ex# Record batch serialization
│   │   └── ...
│   ├── generated/         # Auto-generated protocol code
│   └── mix/tasks/         # Mix tasks (code generation)
├── test/
│   ├── kayrock/           # Unit tests
│   ├── integration/       # Integration tests
│   └── support/           # Test helpers
└── config/                # Configuration

LLM/AI Integration

Kayrock includes a usage-rules.md file that provides guidelines for LLM-based coding assistants. This file is automatically available to tools that support the usage_rules package.

For users of Kayrock

If you use LLM coding assistants (Claude, Cursor, etc.), you can pull in Kayrock's usage rules:

# Add usage_rules to your project
mix igniter.install usage_rules

# Sync Kayrock's rules to your AI config file
mix usage_rules.sync CLAUDE.md kayrock --link-to-folder deps

For contributors

When updating usage-rules.md, ensure it includes:

• Common mistakes and how to avoid them
• Correct usage patterns with code examples
• API-specific guidance

Questions?

• Open an issue for bugs or feature requests
• Check existing issues before creating new ones

License

By contributing, you agree that your contributions will be licensed under the MIT License.