0975b68334
Initial release: - Complete async API client (45+ endpoints) - Pydantic models for all responses - Two-step authentication - Comprehensive error handling - 92% test coverage - Gitea Actions CI/CD - Semantic release configured
282 lines
6.6 KiB
Markdown
282 lines
6.6 KiB
Markdown
# 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)
|