kwork-api/docs/SEMANTIC_RELEASE.md

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 (багфиксы):

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 (новая функциональность):

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 (ломающие изменения):

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)
"

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

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

Разработка:

# Делай коммиты по 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 создан

---

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

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

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

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

uv run semantic-release changelog

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

# 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

[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"

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

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

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

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

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

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

---

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

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

---

🎯 BEST PRACTICES

✅ Делай:

# Атомарные коммиты
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"

❌ Не делай:

# Слишком общие
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
• Conventional Commits
• Angular Commit Guidelines