Contributing Guide¶

Thank you for your interest in contributing to Kreuzberg! This guide covers everything you need — from picking an issue to getting your pull request merged.

First time contributing?¶

Welcome! Here's how to get started:

1. Pick an issue that matches your experience level:
2. Good first issue — small, well-scoped tasks ideal for newcomers
3. Help wanted — tasks where we'd especially appreciate community help
4. Read through the issue and any existing comments
5. Leave a comment letting maintainers know you'd like to work on it
6. Ask questions — we're here to help!

Congratulations — that's really all it takes to start contributing! Fork, fix, and open a PR. We keep the process simple so you can focus on what matters: the code.

Want to propose a larger change or new feature? Open an issue to discuss it with maintainers first.

Prerequisites¶

You only need the toolchains for the areas you plan to work on.

Required for all contributions:

• Git
• Task — our task runner for all build and test workflows
• Rust stable (via rustup) — required for core and all bindings. The wasm32-unknown-unknown target is configured automatically via rust-toolchain.toml

Required for WASM builds:

• WASI SDK — provides a wasm-capable C/C++ compiler needed by tree-sitter, tesseract, and pdfium. Install to $HOME/wasi-sdk or set the WASI_SDK_PATH environment variable to your install location

Language-specific toolchains (only install what you need):

For platform-specific build dependencies (compilers, OpenSSL, etc.), see the Installation guide.

Development setup¶

Set up your entire environment with a single command:

task setup

This installs all toolchains and dependencies. Safe to re-run anytime.

For building individual language bindings, use the namespace pattern:

task rust:build
task python:build
task node:build

Development workflow¶

1. Fork and clone¶

Fork the repository on GitHub, then clone your fork:

git clone git@github.com:<your-username>/kreuzberg.git
cd kreuzberg
git remote add upstream https://github.com/kreuzberg-dev/kreuzberg.git

2. Create a branch¶

git checkout -b feat/your-feature-name main

Use a prefix that matches your change type: feat/, fix/, docs/, perf/, chore/, test/.

3. Make your changes¶

Keep commits small and focused.

4. Run checks¶

task check

This runs both linting and formatting checks. For language-specific tests:

task rust:test
task python:test
task node:test

5. Commit with conventional messages¶

We use Conventional Commits. The pre-commit hook validates this.

feat: add PDF table extraction support
fix: handle empty MIME type in archive entries
docs: update Python API reference for v4.4
perf: parallelize layout inference

6. Update documentation¶

When adding user-facing features, add or update pages under docs/ and reference them in zensical.toml.

Issues¶

Finding issues¶

Browse the issue tracker and filter by labels: good first issue, help wanted, bug, or enhancement.

Reporting a bug¶

Include: what you expected, what happened (with error output), steps to reproduce, your environment (OS, language version, Kreuzberg version), and a minimal sample file if applicable.

Suggesting improvements¶

Search for existing issues first. Describe the use case and keep scope focused — break large ideas into smaller, actionable issues.

Submitting a pull request¶

PR checklist¶

Before opening a PR, verify locally:

• task check passes
• Targeted tests pass
• Docs updated (if applicable)
• Commits follow Conventional Commits

Writing a good PR description¶

Include what changed, why, and how you tested it. Use Fixes #123 to auto-close related issues.

Review and merge¶

1. CI runs — automated builds and tests across platforms
2. Maintainers review — code correctness, style, and design
3. Feedback rounds — make requested changes and push
4. Merge — once approved with all checks passing

Merge requirements: all CI checks pass, at least one maintainer approval, no unresolved conversations, branch up to date with main.

CI/CD¶

Kreuzberg ships six GitHub Actions workflows under .github/workflows/. The first two run automatically on contributor PRs; the rest are manual or release-driven and contributors do not need to invoke them.

Reading workflow failures¶

Open the failing PR's Checks tab and click into the failing job to expand its log. The job name maps directly to the step in ci.yaml that failed (for example, clippy or python-test). To re-run after pushing a fix, GitHub Actions will pick the new commit up automatically; to re-run without a new commit (for flakes), use the Re-run failed jobs button at the top right of the workflow run page.

If a check is reporting "expected check missing" rather than failing outright, the workflow file probably wasn't reachable from your branch — rebase on main and the check will register on the next push.

Coding standards¶

• Rust: Edition 2024, no unwrap() in production paths, document all public items, SAFETY comments for unsafe blocks
• Python: frozen=True / slots=True dataclasses, function-based pytest, follow Ruff and Mypy rules
• TypeScript: Strict types, no any, bindings in packages/typescript/src
• Ruby: No global state outside Kreuzberg module, panic-free native bridge, follow RuboCop
• Go / Java / C#: Follow standard language conventions and project linters

Testing: language-specific tests live in each package; shared E2E behavior belongs in e2e/ fixtures. When adding features, regenerate with task e2e:<lang>:generate.

Community and support¶

• Star the repo: Give us a star on GitHub — it helps others discover Kreuzberg!
• Discord: Join our community
• Issues: GitHub Issues
• License: Elastic License 2.0 (ELv2)

Thank you for contributing to Kreuzberg!