Версионирование и Build

Независимое версионирование

Проекты Lino могут содержать несколько сервисов и веб-приложений. У каждого развертываемого элемента есть собственная версия, поэтому небольшое исправление в одном сервисе не вынуждает делать искусственный release всей системы. Это важно в модульных и распределенных архитектурах, где APIs, workers, web apps, migrations и интеграционные контракты могут развиваться с разной скоростью.

Операционная версия хранится в простом текстовом файле version.txt. Для сервисов файл находится в src/Services/<ServiceName>/version.txt. Для веб-приложений он находится в src/WebApps/<WebAppName>/version.txt. Lino CLI читает эти файлы при выводе списка, просмотре, увеличении версии и генерации версионированных builds.

Правило SemVer, используемое Lino

MAJOR.MINOR.PATCH

• PATCH увеличивает последнее число и должен использоваться для совместимых исправлений, небольших внутренних улучшений и изменений, которые не меняют публичный контракт.
• MINOR увеличивает среднее число и сбрасывает patch в ноль. Используйте его для обратно совместимых функций, новых endpoints, необязательных полей или аддитивного поведения.
• MAJOR увеличивает первое число и сбрасывает minor и patch в ноль. Используйте его, когда потребители должны адаптироваться, например если API contract изменился несовместимо или поведение было намеренно заменено.

Примеры: 1.0.0 может представлять первую стабильную версию, 1.0.1 совместимое исправление, 1.1.0 новую совместимую возможность или новые endpoints без breaking changes, а 2.0.0 release с изменениями, требующими обновления клиентов.

Просмотр текущих версий

Используйте lino version list, чтобы увидеть текущие версии всех сервисов и веб-приложений проекта:

lino version list

Используйте lino version show, когда нужно посмотреть версию конкретного сервиса или веб-приложения. Команда спрашивает, является ли цель сервисом или веб-приложением, и показывает версию, прочитанную из соответствующего файла version.txt.

lino version show

Увеличение версии

Используйте lino version bump, когда сервис или веб-приложение готово к новому release:

lino version bump

1. Запустите команду из корня проекта.
2. Выберите один или несколько сервисов или веб-приложений. Prompt показывает каждый элемент с его текущей версией.
3. Выберите тип увеличения: patch, minor или major.
4. Подтвердите ответы. Lino обновляет выбранные файлы version.txt и показывает таблицу с новыми версиями.

Каждый запуск сохраняет понятное отслеживание изменений, повышает согласованность с release-практиками и упрощает выравнивание с CI/CD pipelines. Номер версии перестает быть отдельной деталью и начинает идентифицировать развертываемый артефакт, который действительно изменился.

Изменения версии нужно рассматривать вместе с техническим влиянием release. Database migration может быть связана с версией сервиса, потребителям API могут понадобиться contract notes, а интеграционным событиям могут потребоваться проверки совместимости. Хранение версии рядом с развертываемым элементом делает эти решения явными и более удобными для аудита.

Перед увеличением major проверьте публичные APIs, event contracts, migrations, совместимость клиентов и внешних потребителей. Перед увеличением minor подтвердите, что новое поведение является аддитивным. Перед patch подтвердите, что изменение совместимо и не меняет ожидания использования.

Build и контейнеризация

В видео и ежедневной разработке dotnet build часто используется, чтобы проверить, что сгенерированное решение по-прежнему компилируется после каждого этапа моделирования. У команды lino build другая цель: подготовить выбранные сервисы и веб-приложения к release, публикуя их в режиме Release с профилем публикации container .NET.

Такое разделение не позволяет воспринимать простую проверку компиляции как пакет поставки. Используйте dotnet build во время разработки, чтобы находить ошибки раньше. Используйте lino build, когда артефакт готов получить версию, стать container image и перейти в registry или deploy pipeline.

Что делает lino build

Запустите команду из корня проекта Lino:

lino build

CLI проверяет аутентифицированного пользователя и текущую конфигурацию проекта, спрашивает, какие сервисы или веб-приложения должны войти в build, а затем спрашивает, нужно ли сохранить версию или увеличить ее. Когда выбрано увеличение, Lino обновляет соответствующий version.txt перед генерацией build-команд.

Backend возвращает точные команды для выполнения. Сейчас эти команды используют dotnet publish с -c Release, -p:PublishProfile=DefaultContainer, -p:ContainerRepository, -p:ContainerImageTag и -p:ContainerLabelVersion. Tag образа и label версии container получают одно и то же значение SemVer, выбранное для release.

На практике процесс компилирует код сервиса или веб-приложения, применяет нужную конфигурацию публикации, генерирует container image на основе текущей SemVer-версии и назначает артефакту стандартизированные имя, tag и metadata.

Сгенерированные имена repositories

Lino нормализует имена проекта и элементов, чтобы генерировать предсказуемые container repositories:

• Простая service API: <project-name>/services/<service-name>-api:1.2.3
• Модульный service host: <project-name>/services/<service-name>-host:1.2.3
• Веб-приложение Blazor: <project-name>/webapps/<webapp-name>:1.2.3

Эта конвенция разделяет service APIs, модульные hosts и веб-приложения в registry, сохраняя release-версию в tag. Шаблон также устраняет повторяющиеся ручные решения и снижает расхождения между окружениями, CI/CD scripts и операционной документацией.

Публикация в registries

Сгенерированные images можно публиковать в registry, используемый вашей deploy-платформой:

• Docker Hub
• GitHub Container Registry
• AWS ECR
• Azure Container Registry
• любой другой OCI-совместимый registry.

По возможности выполняйте deploy с указанием неизменяемых version tags, например 1.2.3, вместо плавающих tags. Это улучшает rollback, аудит и сравнение между тем, что было собрано, опубликовано и развернуто.

Рекомендуемый release-процесс

1. Запустите тесты проекта и dotnet build, чтобы проверить исходный код перед упаковкой.
2. Посмотрите текущие версии с помощью lino version list и проверьте, какие сервисы или веб-приложения изменились.
3. Используйте lino build и выберите, будет ли текущая версия сохранена или получит увеличение patch, minor или major.
4. Опубликуйте сгенерированные container images в registry, используемый платформой развертывания, например Docker Hub, GitHub Container Registry, AWS ECR, Azure Container Registry или другой совместимый registry.
5. Развертывайте, ссылаясь на трассируемые version tags, и держите changelog, migrations и rollback plan связанными с тем же release.

Не помещайте secrets, production connection strings или учетные данные конкретного окружения внутрь сгенерированных images. Используйте переменные окружения, user secrets для локальной разработки, хранилища secrets в CI/CD или механизм secrets deploy-платформы.

В этом процессе версионирование и build остаются связанными: одно и то же значение SemVer, записанное в проекте, используется как container tag и как release metadata, улучшая трассируемость между исходным кодом, migrations, API contracts, интеграционными событиями и развернутыми артефактами.