# Semantic Release — Автоматическое версионирование

## 📋 Обзор

**python-semantic-release** автоматически определяет версию на основе Conventional Commits.

**Как работает:**
```
Commit → Анализ сообщения → Определение типа → Bump версии → Тег → Релиз
```

---

## 🎯 CONVENTIONAL COMMITS

### **Формат коммита:**

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

[optional body]

[optional footer]
```

### **Типы коммитов и влияние на версию:**

| Тип | Влияние | Пример | Версия |
|-----|---------|--------|--------|
| `feat` | **MINOR** | `feat: add new API endpoint` | 0.1.0 → 0.2.0 |
| `fix` | **PATCH** | `fix: handle timeout errors` | 0.1.0 → 0.1.1 |
| `perf` | **PATCH** | `perf: optimize HTTP requests` | 0.1.0 → 0.1.1 |
| `feat` + BREAKING | **MAJOR** | `feat: change auth method` | 0.1.0 → 1.0.0 |
| `docs`, `style`, `refactor`, `test`, `chore`, `ci`, `build` | Нет | `docs: update README` | Без изменений |

---

## 📝 ПРИМЕРЫ КОММИТОВ

### **PATCH (багфиксы):**

```bash
git commit -m "fix: handle 404 error in catalog API"
git commit -m "fix(auth): restore session from token correctly"
git commit -m "perf: reduce HTTP connection overhead"
```

### **MINOR (новая функциональность):**

```bash
git commit -m "feat: add batch kwork details endpoint"
git commit -m "feat(projects): add get_payer_orders method"
git commit -m "feat: support HTTP/2 for faster requests"
```

### **MAJOR (ломающие изменения):**

```bash
git commit -m "feat: redesign authentication flow

BREAKING CHANGE: login() now returns KworkClient instead of tuple

Migration:
  Before: token, cookies = await login(user, pass)
  After: client = await KworkClient.login(user, pass)
"
```

### **Без влияния на версию:**

```bash
git commit -m "docs: add usage examples to README"
git commit -m "test: increase coverage to 95%"
git commit -m "style: fix formatting with ruff"
git commit -m "refactor: simplify error handling"
git commit -m "chore: update dependencies"
git commit -m "ci: add Gitea Actions workflow"
git commit -m "build: configure UV build system"
```

---

## 🔄 WORKFLOW

### **Разработка:**

```bash
# Делай коммиты по Conventional Commits
git commit -m "feat: add new endpoint"
git commit -m "fix: handle edge case"
git commit -m "docs: update documentation"

# Пуш в main
git push origin main
```

### **CI/CD (автоматически):**

```
1. Тесты запускаются
2. Сборка пакета
3. Semantic Release анализирует коммиты
4. Определяет тип версии (MAJOR/MINOR/PATCH)
5. Обновляет версию в pyproject.toml и __init__.py
6. Создаёт Git тег
7. Генерирует CHANGELOG
8. Создаёт релиз в Gitea
9. Публикует пакет в Gitea Registry
```

### **Результат:**

```
✅ v0.1.1 создан
✅ CHANGELOG.md обновлён
✅ Пакет опубликован
✅ Релиз в Gitea создан
```

---

## 🔧 РУЧНОЕ УПРАВЛЕНИЕ

### **Проверить следующую версию:**

```bash
cd /root/kwork-api
uv run semantic-release version --print
```

### **Сгенерировать CHANGELOG:**

```bash
uv run semantic-release changelog
```

### **Создать релиз вручную:**

```bash
# Bump версии
uv run semantic-release version --no-push

# Проверить что изменилось
git diff

# Запушить
git push origin main --tags
```

---

## 📊 ПРИМЕР ИСТОРИИ ВЕРСИЙ

```
v0.1.0 (2026-03-23)
  - Initial release
  - Complete API client
  - 100% documentation

v0.1.1 (2026-03-24)
  - fix: handle timeout errors
  - fix: restore session correctly

v0.2.0 (2026-03-25)
  - feat: add batch endpoint
  - feat: support HTTP/2

v0.2.1 (2026-03-26)
  - perf: optimize requests

v1.0.0 (2026-03-27)
  - feat: new authentication
  - BREAKING CHANGE: API changed
```

---

## ⚙️ КОНФИГУРАЦИЯ

**Файл:** `pyproject.toml`

```toml
[tool.semantic_release]
version_toml = ["pyproject.toml:project.version"]
version_variables = ["src/kwork_api/__init__.py:__version__"]
branch = "main"
build_command = "uv build"
commit_parser = "angular"
tag_format = "v{version}"

[tool.semantic_release.commit_parser_options]
minor_tags = ["feat"]
patch_tags = ["fix", "perf"]
breaking_change_tags = ["feat"]

[tool.semantic_release.remote]
type = "gitea"
domain = "https://git.much-data.ru"
owner = "claw"
repo_name = "kwork-api"
```

---

## 🚨 TROUBLESHOOTING

### **Ошибка: "No commits to release"**

```bash
# Значит не было коммитов с типами feat/fix/perf
# Сделай коммит с правильным форматом
git commit -m "feat: add something new"
```

### **Ошибка: "Gitea token invalid"**

```bash
# Проверь токен
# Settings → Applications → Create new token
# Права: write:repository, write:package
# Обнови секрет в Gitea Actions
```

### **Версия не обновляется**

```bash
# Проверь конфигурацию
uv run semantic-release --version

# Проверь что __version__ есть в __init__.py
grep "__version__" src/kwork_api/__init__.py
```

---

## 📋 ЧЕКЛИСТ ПЕРЕД ПУШЕМ

- [ ] Коммиты по Conventional Commits
- [ ] Тесты проходят
- [ ] CHANGELOG обновлён (автоматически)
- [ ] Версия в __init__.py совпадает
- [ ] GITEA_TOKEN настроен в секретах

---

## 🎯 BEST PRACTICES

### **✅ Делай:**

```bash
# Атомарные коммиты
git commit -m "feat: add user endpoint"
git commit -m "fix: handle 404 error"

# Понятные описания
git commit -m "fix: restore session from saved token"

# Scope для больших изменений
git commit -m "feat(auth): add OAuth2 support"
```

### **❌ Не делай:**

```bash
# Слишком общие
git commit -m "fix stuff"

# Несколько изменений в одном
git commit -m "feat: add user endpoint and fix auth and update docs"

# Не по формату
git commit -m "added new feature"
```

---

## 📞 ССЫЛКИ

- [python-semantic-release](https://python-semantic-release.readthedocs.io/)
- [Conventional Commits](https://www.conventionalcommits.org/)
- [Angular Commit Guidelines](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#commit)