contributing/index.md

Contributing to Kirak

Thank you for contributing! This document covers everything you need to get started.

Ways to contribute

Report a bug or request a feature – open a GitHub issue. Search first to avoid duplicates.
Ask a question or discuss an idea – use GitHub Discussions.
Contribute code or docs – open a pull request (see below).

Security issues are different. Do not open a public issue for a suspected vulnerability – follow SECURITY.md.

Before you start

This repository is the open-source Kirak runtime. It does not include Kirak Studio (the hosted service), which is separate and proprietary.
For anything more than a small fix, open an issue first so we can agree on the approach before you spend time on it.
By participating you agree to our Code of Conduct.

Development setup

# Clone and enter the repo
git clone https://github.com/kirak-io/kirak.git
cd kirak

# Create a virtual environment
python -m venv kirak_venv
source kirak_venv/bin/activate   # Windows: kirak_venv\Scripts\activate

# Install with all optional dependencies and dev tools
pip install -e ".[all,dev]"

You need a running MySQL or PostgreSQL instance. Copy .env.example to .env and fill in your database credentials.

Running tests

# Full suite with coverage
pytest --cov=kirak --cov-report=term-missing

# Single file
pytest tests/test_auth/test_login.py -v

# Fast (no coverage)
pytest -x -q

Unit tests use mock DB fixtures defined in tests/conftest.py. Integration tests require a real database connection and are gated behind KIRAK_INTEGRATION=1. See tests/conftest.py for fixture setup and docs/guides/testing.md for the full testing guide.

Linting and formatting

black kirak/        # auto-format (line length 100)
ruff check kirak/   # lint
mypy kirak/         # strict type check

All three must pass before a PR is mergeable. The CI pipeline enforces this.

Branching strategy

Branch	Purpose
`main`	Latest stable release
`develop`	Integration branch for the next release
`feature/<name>`	New features
`fix/<name>`	Bug fixes
`security/<name>`	Security patches (merge to `main` directly after review)

Branch from develop for features and bug fixes. Security patches branch from main.

Commit style

We follow Conventional Commits:

<type>(<scope>): <short summary>

[optional body]

Types: feat, fix, security, refactor, test, docs, chore

Examples:

feat(auth): add PKCE to OAuth2 callback flow
fix(core): guard soft-delete clause against WHERE-in-column-name edge case
security(auth): remove MD5 password fallback

Keep the subject line under 72 characters. Write the body in present tense.

Pull request checklist

Before opening a PR:

Tests added or updated for every changed behaviour
pytest passes locally
ruff check kirak/ reports no errors
mypy kirak/ passes
No print() statements added (use logger.debug())
No parameter values logged in SQL statements
Type hints present on all new public functions/methods
CHANGELOG.md updated under [Unreleased]
All commits signed off (see Sign off your commits below)

Security-sensitive changes (auth, payments, crypto): tag a maintainer for an explicit security review before merge.

Sign off your commits (Developer Certificate of Origin)

Kirak uses the Developer Certificate of Origin (DCO) – a lightweight statement that you have the right to submit the code you’re contributing. It is not a copyright assignment; you keep the copyright in your contribution, and it is licensed to the project under Apache License 2.0. Contribution model: DCO, not a CLA – inbound license equals outbound license, and Sizmic cannot unilaterally relicense contributed code.

To sign off, add a Signed-off-by line to each commit:

Signed-off-by: Jane Developer <jane@example.com>

The easiest way is to use the -s flag:

git commit -s -m "Fix off-by-one in booking overlap check"

To sign off a series of commits you already made:

git rebase --signoff main

The name and email in the sign-off must match your commit author details and be a real identity (no anonymous or pseudonymous contributions). By signing off you certify the statement in the DCO file. A bot checks every PR for sign-off – if it complains, add the sign-off with git rebase --signoff and force-push your branch.

License of contributions

By contributing, you agree that your contributions are licensed under the Apache License 2.0, the same license as the project (see LICENSE.md).

Code style

Line length: 100 (enforced by Black)
Python 3.10+ syntax only
async/await for all I/O
No print() – use the module logger
No feature flags or backward-compatibility shims – just change the code
No comments explaining what code does – only why (hidden constraints, workarounds)
SQL must use dialect.placeholder(i) – never f-string interpolation of values
Log SQL at logger.debug() – never include parameter values

Adding a new module

Create kirak/<module>/ with __init__.py and a class extending BaseModule
Add it to Kirak._lazy_modules in kirak_instance.py
Add an optional-dependency group to pyproject.toml
Add tests in tests/test_<module>/