# Contributing to cuframes

Спасибо за интерес. Проект на ранней стадии — каждый вклад ценен.

## Перед началом

1. Прочитайте [docs/architecture.md](docs/architecture.md) — там подробный
   design document с обоснованием решений
2. Проверьте [open issues](https://git.goldix.org/gx/cuframes/issues) —
   возможно ваша идея уже обсуждается
3. Большие изменения — сначала RFC-issue, чтобы синхронизировать с design

## Структура репо

```
cuframes/
├── docs/                 архитектура, протокол, benchmarks
├── filter/               FFmpeg filter (vf_cuda_ipc_export.c)
├── libcuframes/          producer/consumer core (C)
├── bindings/             C++ и Python wrappers
├── examples/             working examples (CV, PyTorch, Frigate)
├── docker/               Dockerfile'ы для dev и distribution
├── scripts/              build, patch, packaging
├── tools/spike/          PoC код для Phase 0
└── tests/                integration + stress
```

## Development setup

Всё собирается **в Docker**, чтобы не зависеть от системного CUDA toolkit.

```bash
# Dev-контейнер с CUDA 12.x + build tools
docker compose -f docker/docker-compose.dev.yml up -d
docker exec -it cuframes-dev bash

# Внутри контейнера
cmake -B build -S . -G Ninja
cmake --build build
ctest --test-dir build --output-on-failure
```

См. [docker/README.md](docker/README.md) для деталей.

## Code style

- **C** — стиль FFmpeg (для filter), K&R + 4 spaces
- **C++** — C++17, Google C++ style (clang-format с проектным `.clang-format`)
- **Python** — PEP 8, black + ruff

CI прогоняет formatter checks автоматически.

## Commit messages

Conventional Commits:

```
feat(filter): add cuda_ipc_export FFmpeg filter
fix(consumer): handle producer reconnect race
docs(arch): clarify backpressure semantics
test: add 24-hour stress test
chore: bump CMake to 3.25
```

## Phase 0 contributors

Если хотите помочь с самым ранним этапом (PoC spike) —
см. [tools/spike/README.md](tools/spike/README.md) (когда появится).

Главные вопросы Phase 0:
- Latency producer→consumer на разных GPU (Ampere/Ada/Blackwell)
- CUDA IPC behavior cross-container (docker → docker, host → docker)
- Sync через `cudaStreamSynchronize` vs CUDA IPC events
- Memory leak detection при random producer/consumer kill

## License

Contributions accepted under LGPL-2.1+ (см. [LICENSE](LICENSE)).