# Contributing to kwork-api

## Development Setup

```bash
# Clone repository
git clone https://git.much-data.ru/much-data/kwork-api.git
cd kwork-api

# Install UV (if not installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync --group dev

# Install pre-commit hooks
uv run pre-commit install
```

## Documentation

Generate documentation locally:

```bash
# Install docs dependencies
uv sync --group dev

# Build HTML docs
uv run mkdocs build

# Serve locally (optional)
uv run mkdocs serve
```

Documentation is built automatically by CI and available in `site/` folder.

## Branch Naming

- `feature/description` — новые фичи
- `fix/description` — багфиксы
- `docs/description` — документация
- `refactor/description` — рефакторинг

## Commit Messages

Используем [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <description>

[optional body]

[optional footer]
```

**Types:**
- `feat` — новая фича
- `fix` — исправление бага
- `docs` — документация
- `style` — форматирование
- `refactor` — рефакторинг
- `test` — тесты
- `chore` — обслуживание
- `ci` — CI/CD

**Примеры:**
```
feat(validation): add /api/validation/checktext endpoint
fix(auth): handle expired token error
docs(api): update client examples
```

## Pre-commit Hooks

Автоматически запускаются перед коммитом:

1. **ruff check** — линтинг с авто-исправлением
2. **ruff format** — форматирование кода
3. **commitlint** — проверка формата коммита

Перед push:
- **pytest** — запуск тестов

## Pull Requests

1. Создай ветку от `main`
2. Вноси изменения с правильными коммитами
3. Запушь ветку
4. Создай PR в `main`
5. Дождись прохождения CI
6. После review — merge

## CI/CD

**PR Checks:**
- ✅ Тесты с coverage (90% threshold)
- ✅ Линтинг (ruff)
- ✅ Форматирование (ruff format)
- ✅ Безопасность (pip-audit + secrets scan)
- ✅ Commitlint (PR title)

**Release (merge в main):**
- 📦 Semantic release (auto versioning)
- 📝 CHANGELOG generation
- 🏷️ Git tag creation

**Tag (v*):**
- 📦 Сборка пакета
- 🚀 Публикация в Gitea Packages

## Versioning

Используем [Semantic Versioning](https://semver.org/):

- `MAJOR.MINOR.PATCH` (например, `1.2.3`)
- Теги: `v1.2.3`

Для создания релиза:
```bash
git tag v1.2.3
git push origin v1.2.3
```