Nimbus Docs

Appearance

Руководство по версионированию Nimbus ​

Обзор ​

Проект Nimbus использует комбинированный подход к версионированию:

  • Глобальная версия для всей системы (отображается в UI)
  • Независимые версии микросервисов (для DevOps и разработки)
  • Версия frontend синхронизирована с глобальной

Структура версий ​

nimbus/
├── VERSION                                # 0.1.0 (глобальная версия)
├── frontend/package.json                  # 0.1.0 (синхронизирована)
└── services/
    ├── auth-service/VERSION              # 0.1.0 (независимая)
    ├── core-service/VERSION              # 0.1.0 (независимая)
    └── billing-service/VERSION           # 0.1.0 (независимая)

Просмотр версий ​

Показать все версии ​

bash
make version

Вывод:

=== Версии Nimbus ===
Система:          0.1.0
Frontend:         0.1.0
Auth Service:     0.1.0
Core Service:     0.1.0
Billing Service:  0.1.0

В UI приложения ​

После запуска приложения, в боковом меню снизу отображается:

  • Nimbus v0.1.0 - глобальная версия
  • Раскрывающаяся секция "Информация о версиях" с деталями по каждому сервису

Обновление версий ​

1. Обновление глобальной версии (для релиза) ​

PATCH версия (0.1.0 -> 0.1.1) ​

Для исправлений и патчей:

bash
make version-bump-patch

MINOR версия (0.1.0 -> 0.2.0) ​

Для новых функций с обратной совместимостью:

bash
make version-bump-minor

MAJOR версия (0.1.0 -> 1.0.0) ​

Для breaking changes:

bash
make version-bump-major

Эти команды автоматически:

  • Обновляют глобальную версию в VERSION
  • Синхронизируют все версии микросервисов
  • Обновляют package.json frontend

2. Обновление версии отдельного микросервиса ​

Если микросервис развивается независимо:

bash
make version-service SERVICE=core VERSION=1.2.0

Доступные сервисы: auth, core, billing

Пример:

bash
# Core service получил новую функцию
make version-service SERVICE=core VERSION=0.2.0

# Auth service исправили баг
make version-service SERVICE=auth VERSION=0.1.1

3. Синхронизация всех версий ​

Синхронизировать все версии с глобальной:

bash
make version-sync

Это полезно после обновления глобальной версии вручную.

Создание релиза ​

Полный релиз ​

bash
make release VERSION=1.0.0

Эта команда:

  1. Обновляет глобальную версию
  2. Синхронизирует все версии микросервисов и frontend
  3. Создает git commit
  4. Создает git tag v1.0.0

После этого нужно запушить изменения:

bash
git push && git push --tags

Пример создания релиза ​

bash
# 1. Создать релиз
make release VERSION=1.0.0

# 2. Запушить в репозиторий
git push origin main
git push origin v1.0.0

# 3. Собрать Docker образы с версией
docker-compose -f docker-compose.microservices.yml build

Разработка микросервисов ​

Запуск с версией ​

Каждый микросервис имеет Makefile с автоматической установкой версии:

bash
cd services/core-service
make run

Это запустит сервис с установленными:

  • Version (из VERSION файла)
  • BuildTime (текущее время)
  • GitCommit (короткий хеш)
  • GitBranch (текущая ветка)

Проверка версии сервиса ​

bash
# Через Makefile
cd services/core-service
make version

# Через API
curl http://localhost:8002/health

Ответ:

json
{
  "status": "ok",
  "version": "0.1.0",
  "buildTime": "2025-01-18T12:30:00Z",
  "commit": "a1b2c3d",
  "branch": "main"
}

Сборка с версией ​

bash
cd services/core-service
make build

Это создаст бинарный файл bin/core-service с встроенной информацией о версии.

API для получения версий ​

GET /api/version ​

Возвращает информацию о всех компонентах системы:

bash
curl http://localhost:8002/api/version

Ответ:

json
{
  "system": "0.1.0",
  "frontend": "0.1.0",
  "services": {
    "core": {
      "version": "0.1.0",
      "buildTime": "2025-01-18T12:30:00Z",
      "commit": "a1b2c3d",
      "branch": "main"
    },
    "auth": {
      "version": "0.1.0",
      "buildTime": "2025-01-18T12:29:00Z",
      "commit": "a1b2c3d",
      "branch": "main"
    },
    "billing": {
      "version": "0.1.0",
      "buildTime": "2025-01-18T12:31:00Z",
      "commit": "a1b2c3d",
      "branch": "main"
    }
  }
}

GET /api/version/core ​

Возвращает только версию core-service:

bash
curl http://localhost:8002/api/version/core

Docker сборка ​

Сборка с версией ​

При сборке через docker-compose версия устанавливается автоматически:

bash
docker-compose -f docker-compose.microservices.yml build

Ручная сборка ​

bash
VERSION=$(cat VERSION)
docker build \
  --build-arg VERSION=$VERSION \
  --build-arg GIT_COMMIT=$(git rev-parse --short HEAD) \
  -t nimbus/core-service:$VERSION \
  ./services/core-service

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

Semantic Versioning (SemVer) ​

Проект следует Semantic Versioning 2.0.0:

Формат: MAJOR.MINOR.PATCH

  • MAJOR (X.0.0) - Несовместимые изменения API, breaking changes
  • MINOR (0.X.0) - Новая функциональность с обратной совместимостью
  • PATCH (0.0.X) - Исправления ошибок, патчи безопасности

Когда обновлять версии ​

PATCH (0.1.0 -> 0.1.1) ​

  • Исправление бага
  • Патч безопасности
  • Опечатки в документации
  • Улучшение производительности без изменения API

MINOR (0.1.0 -> 0.2.0) ​

  • Новая функция с обратной совместимостью
  • Новый API endpoint
  • Улучшение существующей функции
  • Новый UI компонент

MAJOR (0.1.0 -> 1.0.0) ​

  • Breaking changes в API
  • Изменение структуры БД (миграция)
  • Удаление устаревших функций
  • Первый стабильный релиз (1.0.0)

Примеры использования ​

Пример 1: Исправление бага в core-service ​

bash
# 1. Исправить баг в коде
# 2. Обновить версию только core-service
make version-service SERVICE=core VERSION=0.1.1

# 3. Протестировать
cd services/core-service
make run

# 4. Коммит
git add services/core-service/VERSION
git commit -m "fix(core): исправлена ошибка в расчете услуг ЖКХ"
git tag core-service/v0.1.1
git push && git push --tags

Пример 2: Релиз новой версии системы ​

bash
# 1. Завершить все функции для релиза
# 2. Обновить CHANGELOG.md
# 3. Создать релиз
make release VERSION=1.0.0

# 4. Запушить
git push origin main
git push origin v1.0.0

# 5. Собрать Docker образы
docker-compose -f docker-compose.microservices.yml build

# 6. Развернуть в production

Пример 3: Независимое развитие микросервисов ​

bash
# Auth service получил новую функцию 2FA
make version-service SERVICE=auth VERSION=1.1.0

# Core service исправил баг
make version-service SERVICE=core VERSION=1.0.1

# Billing service получил breaking change
make version-service SERVICE=billing VERSION=2.0.0

# Глобальная версия остается 1.0.0
# В UI отобразятся разные версии сервисов

Работа с CHANGELOG ​

Формат CHANGELOG.md ​

Ведите CHANGELOG.md по формату Keep a Changelog:

markdown
# Changelog

## [Unreleased]
### Added
- Новые функции в разработке

## [1.0.0] - 2025-01-18
### Added
- Система версионирования
- UI компонент для отображения версий

### Changed
- Улучшена архитектура API

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

## [0.1.0] - 2024-12-01
### Added
- Первый релиз

Автоматическое обновление CHANGELOG ​

При каждом релизе:

  1. Обновите секцию [Unreleased]
  2. Создайте новую секцию с версией и датой
  3. Коммитите вместе с обновлением версии

Команды Makefile ​

Корневой Makefile ​

bash
make version              # Показать все версии
make version-bump-patch   # Увеличить PATCH версию
make version-bump-minor   # Увеличить MINOR версию
make version-bump-major   # Увеличить MAJOR версию
make version-service      # Обновить версию микросервиса
make version-sync         # Синхронизировать все версии
make release              # Создать релиз
make help                 # Показать справку

Makefile микросервиса ​

bash
make run       # Запустить с версией
make build     # Собрать с версией
make version   # Показать версию
make test      # Запустить тесты
make tidy      # Обновить зависимости
make clean     # Удалить собранные файлы

Troubleshooting ​

Версия показывает "unknown" ​

Проблема: В /health endpoint версия показывается как "unknown"

Решение: Запускайте сервис через Makefile:

bash
cd services/core-service
make run

Или вручную с build flags:

bash
go run -ldflags "-X nimbus/core-service/internal/version.Version=0.1.0" ./cmd/server

Версии не синхронизированы ​

Проблема: Версии микросервисов отличаются от глобальной

Решение: Синхронизируйте версии:

bash
make version-sync

Скрипт version-bump.sh не исполняется ​

Проблема: Permission denied при запуске скрипта

Решение: Сделайте скрипт исполняемым:

bash
chmod +x scripts/version-bump.sh

Best Practices ​

✅ Рекомендуется ​

  • Используйте make version для просмотра всех версий
  • Обновляйте CHANGELOG.md при каждом релизе
  • Используйте git tags для всех релизов
  • Тестируйте перед обновлением версии
  • Синхронизируйте версии при глобальном релизе

❌ Не рекомендуется ​

  • Не изменяйте версию вручную (используйте Makefile)
  • Не пропускайте версии (0.1.0 -> 0.3.0)
  • Не забывайте обновлять CHANGELOG.md
  • Не создавайте релизы без git tags
  • Не обновляйте версию без тестирования

Дополнительные ресурсы ​