Contributing to kwork-api

Development Setup

# 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:

# Install docs dependencies
uv sync --group docs

# Build HTML docs
uv run mkdocs build

# Serve locally (optional)
uv run mkdocs serve

Documentation is built automatically by CI.

End-to-End Testing

E2E тесты требуют реальных credentials Kwork.ru:

# 1. Скопируй шаблон
cp tests/e2e/.env.example tests/e2e/.env

# 2. Заполни credentials
nano tests/e2e/.env  # KWORK_USERNAME, KWORK_PASSWORD

# 3. Запусти тесты
uv run pytest tests/e2e/ -v

# С задержками (rate limiting)
uv run pytest tests/e2e/ -v --slowmo=1

⚠️ Не запускай E2E в CI — только локально с тестовым аккаунтом!

См. tests/e2e/README.md для деталей.

Branch Naming

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

Commit Messages

Используем Conventional Commits:

<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

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

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

Перед push:

pytest — запуск тестов

Pull Requests

Создай ветку от main
Вноси изменения с правильными коммитами
Запушь ветку
Создай PR в main
Дождись прохождения CI
После 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:

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

Для создания релиза:

git tag v1.2.3
git push origin v1.2.3

3.3 KiB Raw Permalink Blame History Unescape Escape