Contributing

This page is a summary. The full guide, with coding standards and the migration rules, is CONTRIBUTING.md. Everyone taking part follows the Code of Conduct. Report security problems privately as described in SECURITY.md, never in a public issue.

How a pull request gets merged#

tech-pw/cryo on GitHub is the source of truth. Pull requests are reviewed and merged there.

Open an issue or pick one
For anything bigger than a small fix, open an issue first so the change can be discussed before you write it. Starter work is labelled good first issue.
Open a pull request
Fork, branch from main, and open the pull request against tech-pw/cryo. GitHub Actions runs lint, type checks, tests and the docs check on it.
Review and merge
A maintainer reviews it. Keep the pull request focused on one change and link the issue it fixes with Fixes #N. Once checks are green and it's approved, a maintainer squash-merges it into main.

The "Edit this page" link at the bottom of every docs page opens GitHub's editor, and your edit becomes a pull request the same way.

Development setup#

You need Python 3.12+, Node 22 for the web UI and the docs site, Docker with Compose for the local stack, and Git. Go 1.25 is needed only for the native compactor in engine-go/, Rust only for cryo-engine/, and Java 17+ only to run PySpark.

terminal

$ git clone https://github.com/YOUR_USERNAME/cryo.git && cd cryo
$ python3.12 -m venv .venv && source .venv/bin/activate
$ make install
$ ./start-local.sh start

make install installs the package with its dev extras. ./start-local.sh start brings up the dev datalake (MinIO, Iceberg REST, Hive Metastore, Trino, Spark), Postgres and Redis, and the observability stack, then runs the Alembic migrations. make up starts the containers only, without migrating or seeding. For the UI and API without the datalake, run make api and make web-dev against a local Postgres and Redis.

Tests and checks#

Command	What it checks
`make test`	Python unit tests (pytest, in-memory SQLite; no Docker stack needed)
`make lint`, `make typecheck`	ruff lint and format check, mypy. `make format` fixes what it can.
`make web-quality`	Web UI type check, CSS size budget and unit tests
`make web-test`	Web UI unit tests only (vitest)
`make test-engine-go`	Go native compactor tests
`cargo test` in `cryo-engine/`	Rust engine tests

make test isn't everything CI runs. Run the rows that match the parts you touched.

Docs site#

These pages are built from site/_src/pages/*.html with navigation in site/_src/site.json. The generator has no dependencies beyond Node 22. Commit the generated output along with your source edit; CI fails when they don't match.

terminal

$ make docs-preview
$ make docs
$ node site/scripts/build.mjs --check

make docs-preview serves the site on http://localhost:4173 and rebuilds on save. make docs renders once. The changelog page comes from CHANGELOG.md, so rebuild the site when you add a changelog entry. More detail is in site/README.md.

Commits and pull requests#

Use conventional commit messages: feat(scanner): …, fix(planner): …, docs: …, test: …, refactor: …, chore: ….
Add tests for new behaviour and update the docs in the same pull request.
Add a line under [Unreleased] in CHANGELOG.md for anything a user or operator would notice.
Alembic migrations are additive first, one concern per revision. Read the migration section of CONTRIBUTING.md before adding one.
Fill in the pull request template, and add screenshots for UI changes.

ChangelogWhat changed, release by release.IssuesReport a bug or propose a feature with the issue forms.