# Release Guide — kwork-api

## 📋 Стратегия версионирования

Используем **SemVer** (Semantic Versioning): `MAJOR.MINOR.PATCH`

- **MAJOR** — ломающие изменения API
- **MINOR** — новая функциональность (обратно совместимая)
- **PATCH** — багфиксы (обратно совместимые)

---

## 🚀 Процесс релиза

### 1. Подготовка

```bash
# Убедись что все тесты проходят
uv run pytest

# Проверь линтеры
uv run ruff check src/ tests/

# Проверь сборку
uv build
```

### 2. Обновление версии

```bash
# Обновить версию в pyproject.toml
# Например: 0.1.0 → 0.1.1

# Создать тег
git tag -a v0.1.1 -m "Release v0.1.1"

# Отпушить тег
git push origin v0.1.1
```

### 3. Автоматическая публикация

После пуша тега:
1. ✅ Запускается CI/CD pipeline
2. ✅ Прогоняются тесты
3. ✅ Собирается пакет
4. ✅ Публикуется в Gitea Registry

---

## 📦 Gitea Package Registry

**URL:** `https://git.much-data.ru/api/packages/claw/pypi`

**Установка:**
```bash
# Создать .pypirc в домашней директории
cat > ~/.pypirc << EOF
[pypi]
username = claw
password = YOUR_GITEA_TOKEN

[git.much-data.ru]
repository = https://git.much-data.ru/api/packages/claw/pypi
username = claw
password = YOUR_GITEA_TOKEN
EOF

# Установить из Gitea
uv pip install kwork-api --index-url https://git.much-data.ru/api/packages/claw/pypi
```

---

## 🔑 Получение Gitea Token

1. Зайди в https://git.much-data.ru
2. Профиль → Settings → Applications
3. Создать токен с правами `write:package`
4. Сохрани токен в секреты репозитория: `GITEA_TOKEN`

---

## 📊 Changelog

Ведётся в `CHANGELOG.md` по формату [Keep a Changelog](https://keepachangelog.com/).

### Пример:
```markdown
## [0.1.1] - 2026-03-23

### Fixed
- Исправлена ошибка аутентификации при истечении токена

### Changed
- Обновлены зависимости

## [0.1.0] - 2026-03-23

### Added
- Первый релиз
- Базовая функциональность клиента
- Документация 100%
```

---

## ✅ Чеклист перед релизом

- [ ] Все тесты проходят
- [ ] Линтеры без ошибок
- [ ] Документация обновлена
- [ ] CHANGELOG.md обновлён
- [ ] Версия в pyproject.toml обновлена
- [ ] Тег создан и отправлен
- [ ] CI/CD pipeline успешен
- [ ] Пакет опубликован

---

## 🔧 Ручная публикация (если нужно)

```bash
# Собрать
uv build

# Опубликовать
uv publish \
  --publish-url https://git.much-data.ru/api/packages/claw/pypi \
  --token YOUR_GITEA_TOKEN
```