147 lines
3.3 KiB
Markdown
147 lines
3.3 KiB
Markdown
# 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 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:
|
||
|
||
```bash
|
||
# 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](tests/e2e/README.md) для деталей.
|
||
|
||
## 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
|
||
```
|